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 Lirium has nothing to collect.

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
}

An empty data_requirements array with a null collection_url means there is nothing left for the Customer to submit. Read state on Customer Details to confirm the Customer reached active.

📘

Recipe

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