List of documents

This endpoint retrieves a list of all documents associated with a specific application, identified by its unique application ID ({id}). The response provides metadata for each document, including its type, upload date, and a download URL.

Request
Response
Payload examples

Request

Endpoint

environment	HTTP method	endpoint
Sandbox testing	GET	https://api-sandbox.flexfactor.io/v1/onboarding/application/{id}/documents
Production environment	GET	https://api.flexfactor.io/v1/onboarding/application/{id}/documents

Required keys

Parameter	Description
`{id}`	The unique application identifier returned during application creation or listing endpoints.
`bearer token`	The auth token returned by `/oauth2/token`

Body parameters

This endpoint does not require body parameters.

Response

Field Definitions

Field Name	Type	Description
`status`	String	Status of the API request (`SUCCESS`, `FAILED`).
`success`	Boolean	Indicates if the document retrieval was successful.
`totalDocuments`	Integer	The total number of documents associated with the application.
`documents`	Array of Objects	List of documents with their details. Each entry includes the fields below.
`documentId`	String	The unique identifier of the document.
`documentType`	String	Type of the document (e.g., `"ID"`, `"ProofOfAddress"`, `"BusinessLicense"`).
`description`	String	Optional description provided during document upload.
`uploadedOn`	String	Timestamp of when the document was uploaded (ISO 8601 format).
`fileName`	String	Original file name of the uploaded document.
`fileType`	String	MIME type of the document (e.g., `application/pdf`, `image/jpeg`).
`fileSize`	Integer	Size of the document in bytes.
`downloadUrl`	String	A pre-signed URL to download the document. Valid for a limited time.
`errors`	Array of Strings	Any errors encountered during the document retrieval process.

❗️
Notes

The downloadUrl for each document is time-limited; use it promptly to download the document.

Ensure secure storage and handling of sensitive documents retrieved using this endpoint.

The response may contain multiple documents, each with its unique details.

Payload Examples

Request

cURL Request Example

curl --request GET \
     --url https://api-sandbox.flexfactor.io/v1/onboarding/application/{application_id}/documents/ \
     --header 'Authorization: bearer {the token returned by /oauth2}' \
     --header 'accept: application/json'

Response

JSON Example for a Successful Retrieval

{
   "status": "SUCCESS",
   "success": true,
   "totalDocuments": 3,
   "documents": [
       {
           "documentId": "document_789012",
           "documentType": "ID",
           "description": "Uploaded government-issued ID",
           "uploadedOn": "2024-11-16T10:00:00Z",
           "fileName": "gov_id.pdf",
           "fileType": "application/pdf",
           "fileSize": 524288,
           "downloadUrl": "https://api-sandbox.flexfactor.com/download/document_789012?token=xyz123"
       },
       {
           "documentId": "document_789013",
           "documentType": "ProofOfAddress",
           "description": "Uploaded utility bill for address proof",
           "uploadedOn": "2024-11-16T10:10:00Z",
           "fileName": "utility_bill.pdf",
           "fileType": "application/pdf",
           "fileSize": 1024000,
           "downloadUrl": "https://api-sandbox.flexfactor.com/download/document_789013?token=abc123"
       },
       {
           "documentId": "document_789014",
           "documentType": "BusinessLicense",
           "description": "Uploaded business license",
           "uploadedOn": "2024-11-16T10:20:00Z",
           "fileName": "business_license.pdf",
           "fileType": "application/pdf",
           "fileSize": 2048000,
           "downloadUrl": "https://api-sandbox.flexfactor.com/download/document_789014?token=def456"
       }
   ],
   "errors": []
}

JSON Example for a Failed Retrieval

{
   "status": "FAILED",
   "success": false,
   "totalDocuments": 0,
   "documents": [],
   "errors": [
       "Invalid application ID."
   ]
}

Example for Handling Errors

If the application ID is invalid, the API will return an error.
If the bearer token is unauthorized, the API will respond with an Unauthorized error.

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "errors": [
    "Invalid application ID."
  ]
}

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "errors": [
    "Authentication failed. Invalid bearer token."
  ]
}

Updated 15 days ago