This endpoint retrieves the details of a specific document attached to an application, identified by its unique application ID ({id}) and document ID ({documentID}). It provides metadata and a download URL for the document.

Request

Endpoint

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

Required keys

Parameter	Description
`{id}`	The unique application identifier returned during application creation or listing endpoints.
`{documentID}`	The unique identifier of the document, returned during document upload.

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.
`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 is time-limited; use it promptly to download the document.

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

Payload Examples

Request

cURL Request Example

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

Response

JSON Example for a Successful Retrieval

{
   "status": "SUCCESS",
   "success": true,
   "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.io/download/document_789012?token=xyz123",
   "errors": []
}

JSON Example for a Failed Retrieval

{
   "status": "FAILED",
   "success": false,
   "documentId": null,
   "documentType": null,
   "description": null,
   "uploadedOn": null,
   "fileName": null,
   "fileType": null,
   "fileSize": null,
   "downloadUrl": null,
   "errors": [
       "Document not found.",
       "Invalid application ID or document ID."
   ]
}

Example for Handling Errors

If the application ID or document 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": [
    "Document not found."
  ]
}

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

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