Use this endpoint when Lirium performs the KYC for your Customers. It returns a hosted collection_url you redirect the Customer to, plus the data_requirements still pending.

If instead you collect the documents yourself and send them to Lirium, use Upload KYC Document — you do not need this endpoint.

📘

Required scope

The API key must have read or customer_kyc_read. A key without either gets a 403 with error_code forbidden.

Response fields

What collection_url points to

The value depends on your partner configuration:

• Default — a link hosted by the KYC provider, where the Customer submits their documents directly.
• Lirium-hosted Customer login enabled — the Lirium landing page for your partner (https://{partner_id}.app.lirium.com). The Customer signs in there and completes the verification.

Both cases return the same field, so your integration only needs to redirect the Customer to collection_url.

⚠️

Do not cache the link

Call this endpoint each time you need to send the Customer to KYC instead of storing the URL. The link is generated per call and can change or expire.

Email delivery

If your configuration enables the KYC email and the Customer has a contact.email, this call also sends them an email containing the landing link with a one-time login code. The response reports it in email_sent.

email_sent is false when the email is disabled for your partner, when the Customer has no email on file, or when collection_url is null — there is no link to send.

Example

{
  "collection_url": "https://kyc.example.com/collect/9f2c1a7b4e5d",
  "data_requirements": [
    {
      "id": "document_id_front",
      "created": "2020-09-01T11:28:59+00:00",
      "type": "document",
      "document_type": "id_front",
      "status": "pending_submission",
      "last_updated_at": "2020-09-01T11:28:59+00:00"
    }
  ],
  "email_sent": false
}

When collection_url is null

A null link is a normal 200, not an error. It happens in two cases, and data_requirements tells them apart:

• Nothing pending — data_requirements is empty, or holds nothing awaiting submission. There is nothing to send the Customer to. Read state on Customer Details to confirm the Customer reached active.
• Your partner collects the documents — data_requirements still lists items, but your configuration does not collect through Lirium, so there is no hosted link for any of your Customers. Send the documents with Upload KYC Document instead.

{
  "collection_url": null,
  "data_requirements": [
    {
      "id": "document_id_front",
      "created": "2020-09-01T11:28:59+00:00",
      "type": "document",
      "document_type": "id_front",
      "status": "pending_submission",
      "last_updated_at": "2020-09-01T11:28:59+00:00"
    }
  ],
  "email_sent": false
}

📘

Read collection_url, not the status code

Handle the missing link by checking collection_url for null. A 4xx from this endpoint means the request itself failed, never that there is nothing to collect.

Errors

📘

Recipe

Onboarding Flow covers the KYC step end to end for the upload-your-own-documents case.