List Files

Retrieves a paginated list of files from the storage system, optionally filtered by customer ID.

This endpoint allows you to browse uploaded documents and files with comprehensive metadata and pagination support.

Endpoint

GET/v2/storage/file

Link

Gateway APIstagep.tst-apidmndelss.com

Request

Headers

Key	Value	Required
Authorization	123	Yes
Accept	application/json	Yes

Query Parameters

Parameter	Type	Description	Required	Example
customerId	string	Customer ID to filter files by.	No	"cust_12345"
meta.page	integer	Page number (starts from 0).	No	0
meta.pageSize	integer	Items count per page.	No	50

---

Response (200 OK)

Returns a paginated list of file metadata with pagination information.

Response Fields

Items Array

Array of file objects with the following structure:

Field	Type	Description	Example
partnerId	string	Partner ID associated with the file.	"partner_abc"
customerId	string	Customer ID the file is linked to.	"cust_12345"
id	string	Unique file ID in the storage system.	"file_78901"
name	string	Original file name.	"passport_scan.pdf"
size	integer	File size in bytes.	2048576
mime	string	MIME type of the file.	"application/pdf"
isLock	boolean	Lock status (if file is locked from modifications).	false
createAt	string	Creation timestamp.	"2024-05-20T10:30:00Z"
deletedAt	string	Deletion timestamp (if applicable).	"2019-08-24T14:15:22Z"

Meta Object

Pagination metadata for the response:

Field	Type	Description	Example
pageSize	integer	Number of items per page.	50
page	integer	Current page number (0-based).	0
total	string	Total number of items across all pages.	"125"

---

Examples

Request (All Files with Pagination)

bash

curl -X GET 'https://stagep.tst-apidmndelss.com/v2/storage/file?meta.page=0&meta.pageSize=20' \
  -H 'Authorization: 123' \
  -H 'Accept: application/json'

Response

json

{
  "items": [
    {
      "partnerId": "partner_abc123",
      "customerId": "cust_12345",
      "id": "file_78901",
      "name": "passport_scan.pdf",
      "size": 2048576,
      "mime": "application/pdf",
      "isLock": false,
      "createAt": "2024-05-20T10:30:00Z",
      "deletedAt": "2019-08-24T14:15:22Z"
    },
    {
      "partnerId": "partner_abc123",
      "customerId": "cust_12345",
      "id": "file_78902",
      "name": "driver_license_front.jpg",
      "size": 1536000,
      "mime": "image/jpeg",
      "isLock": true,
      "createAt": "2024-05-19T14:20:00Z",
      "deletedAt": "2019-08-24T14:15:22Z"
    },
    {
      "partnerId": "partner_xyz789",
      "customerId": "cust_67890",
      "id": "file_45678",
      "name": "bank_statement_q1.pdf",
      "size": 3096576,
      "mime": "application/pdf",
      "isLock": false,
      "createAt": "2024-05-18T09:15:00Z",
      "deletedAt": "2019-08-24T14:15:22Z"
    }
  ],
  "meta": {
    "pageSize": 20,
    "page": 0,
    "total": "125"
  }
}

Request (Filtered by Customer ID)

bash

curl -X GET 'https://stagep.tst-apidmndelss.com/v2/storage/file?customerId=cust_12345&meta.page=0&meta.pageSize=10' \
  -H 'Authorization: 123' \
  -H 'Accept: application/json'

Response (Filtered)

json

{
  "items": [
    {
      "partnerId": "partner_abc123",
      "customerId": "cust_12345",
      "id": "file_78901",
      "name": "passport_scan.pdf",
      "size": 2048576,
      "mime": "application/pdf",
      "isLock": false,
      "createAt": "2024-05-20T10:30:00Z",
      "deletedAt": "2019-08-24T14:15:22Z"
    },
    {
      "partnerId": "partner_abc123",
      "customerId": "cust_12345",
      "id": "file_78902",
      "name": "driver_license_front.jpg",
      "size": 1536000,
      "mime": "image/jpeg",
      "isLock": true,
      "createAt": "2024-05-19T14:20:00Z",
      "deletedAt": "2019-08-24T14:15:22Z"
    },
    {
      "partnerId": "partner_abc123",
      "customerId": "cust_12345",
      "id": "file_78903",
      "name": "utility_bill.pdf",
      "size": 1024000,
      "mime": "application/pdf",
      "isLock": false,
      "createAt": "2024-05-18T16:45:00Z",
      "deletedAt": "2019-08-24T14:15:22Z"
    }
  ],
  "meta": {
    "pageSize": 10,
    "page": 0,
    "total": "3"
  }
}

Request (Default Pagination)

bash

curl -X GET 'https://stagep.tst-apidmndelss.com/v2/storage/file' \
  -H 'Authorization: 123' \
  -H 'Accept: application/json'

Response (Default)

json

{
  "items": [
    {
      "partnerId": "partner_abc123",
      "customerId": "cust_12345",
      "id": "file_78901",
      "name": "passport_scan.pdf",
      "size": 2048576,
      "mime": "application/pdf",
      "isLock": false,
      "createAt": "2024-05-20T10:30:00Z",
      "deletedAt": "2019-08-24T14:15:22Z"
    },
    {
      "partnerId": "partner_xyz789",
      "customerId": "cust_67890",
      "id": "file_45678",
      "name": "bank_statement_q1.pdf",
      "size": 3096576,
      "mime": "application/pdf",
      "isLock": false,
      "createAt": "2024-05-18T09:15:00Z",
      "deletedAt": "2019-08-24T14:15:22Z"
    }
  ],
  "meta": {
    "pageSize": 50,
    "page": 0,
    "total": "125"
  }
}

---

Error Responses

1. Invalid Customer ID:

   json

   { "error": "Customer not found: cust_99999" }

2. Invalid Page Parameters:

   json

   { "error": "Invalid page parameters: page must be >= 0" }

3. Unauthorized:

   json

   { "error": "Unauthorized" }

4. Rate Limit Exceeded:

   json

   { "error": "Rate limit exceeded" }

---

Notes

• Pagination: Default page size is typically 50 items if not specified
• Filtering: Use customerId to retrieve files for a specific customer only
• Sorting: Results are typically sorted by createAt descending (newest first)
• Soft Deletion: Files marked with deletedAt are typically excluded from results
• Performance: Large result sets should use pagination to optimize performance
• Lock Status: isLock=true indicates files that cannot be modified or deleted

Common Use Cases:

• Browsing customer document archives
• Audit and compliance reviews
• File management interfaces
• Document verification workflows
• Bulk operations on multiple files

Pagination Strategy:

• Start with page=0 for the first page
• Use total from meta to calculate total pages: totalPages = ceil(total / pageSize)
• Handle empty result sets gracefully when page exceeds available data