Download one of the Customer's KYC documents
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Returns a link to download one of the documents listed in the Customer's documents (for example, the front of the ID or the selfie captured during the KYC).
Enabled per agreementLirium enables document sharing for your integration when your agreement covers it, separately for
individualCustomers (KYC) andbusinessCustomers (KYB). The Customer'stypetells which one applies. Until then,documentsis an empty list and this endpoint answers404; after Lirium enables it, allow a few minutes beforedocumentslists anything. Ask Lirium to enable document sharing and to addcustomer_document_readto your API key.
Required scopeThe API key must have
customer_document_read.readalone is not enough: a key without it gets a403witherror_codeforbidden. Listingdocumentson the Customer needs no extra scope.
How to download a document
- Read the Customer with Customer Details. The Customer product changed and Customer requirement rejected webhooks carry the same
documents, but they can be sent before the files are stored (see below). - Pick the document from
documentsby itstype, or bydata_requirement_idto match an entry indata_requirements. - Call this endpoint with its
id, and download the file with a plainGETtourl, without yourAuthorizationheader.
A document is listed once its file is stored, which can be after its requirement is approved, and no webhook announces it. In a KYC Lirium performs, the ID and the selfie usually arrive after the Customer product changed webhook that announces the approval. If a document you expect is missing, read the Customer again a few minutes later with Customer Details, and contact Lirium if it is still missing.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | ID of the document. |
created | timestamp | Yes | When the document was submitted. |
type | string | Yes | Document type: id_front, id_back, proof_of_address, selfie, or an additional type enabled for your integration (see Upload KYC Document). |
data_requirement_id | string | No | ID of the entry in data_requirements the document was submitted for. Omitted when it was not submitted for one. |
url | string | Yes | Link to download the file. |
Do not store the link
urlexpires after a short time. Call this endpoint each time you need the file.
Daily limit
Each integration has a daily limit of calls to this endpoint; ask Lirium for yours. Every call that passes authentication and the scope check counts, including the ones answered with 404 or 429. Past the limit, you get a 429 with error_code too_many_requests and a Retry-After header with the seconds left until the limit resets at 00:00 UTC.
Error Responses
Error responses follow the format described in Errors and Error Codes.
| Status | Error Code | Description |
|---|---|---|
| 403 | forbidden | The API key does not have the customer_document_read scope |
| 404 | not_found | Customer not found: the Customer does not exist or is not yours |
| 404 | not_found | Document not found: the document is not in the Customer's documents. For example, a wrong id, sharing not enabled for this Customer type (or just turned off), or a document replaced by a newer submission |
| 429 | too_many_requests | The daily limit was reached; retry after the seconds in Retry-After |