Entitlements

An Entitlement is a triggerable capability (for example: KYC Onboarding, Derivatives Request, or Proof of Source of Funds) granted to an account.

Most entitlements are triggered by the client application, but some (like Ad Hoc EDD or Request For Information) are exclusively triggered internally by DLT.

Goals

• Preview: Allow clients to fetch all required questionnaires and documents before triggering the workflow, enabling frontends to preload necessary UI elements.
• Control: Give clients explicit control over when workflows start and allow them to track status via webhooks.

High-Level Flow

The Entitlement workflow allows you to request specific capabilities for a user. The process is asynchronous and relies on webhooks to drive the collection of data (questionnaires and documents).

Workflow Steps

1. Trigger Entitlement: Call POST /persons/{id}/entitlement_triggers.
2. Receive Requirements: Listen for the webhook containing the list of questionnaire IDs that must be answered next.
3. Fetch Details: Call GET /questionnaires/{questionnaire_id} to render the form to the user.
4. Upload Documents (Optional): If the form requires files, upload them via POST /persons/{id}/documents and retain the returned Document.id.
5. Submit Answers: Post the answers (referencing document IDs if necessary) to POST /persons/{id}/questionnaires/{questionnaire_id}/response.
6. Handle Updates: The system may send subsequent webhooks requesting further information.
7. Completion: Receive the final completion webhook (success/failure).

---

Listing Available Entitlements

Before triggering a workflow, you can see which entitlements are available for a specific account type.

Endpoints:

• Retail: GET /entitlements?owner_type=person
• Corporate: GET /entitlements?owner_type=corporate

View Response Example

{
  "items": [
    {
      "id": "7b88b3a6-d6a6-49f4-a03f-a7ec57237ff1",
      "name": "onboarding",
      "description": "Onboarding entitlement is used to onboard new retail accounts",
      "created_at": "2025-10-31T12:29:41.138347Z",
      "updated_at": "2025-10-31T12:29:41.138347Z",
      "questionnaires": [
        {
          "entitlement_id": "7b88b3a6-d6a6-49f4-a03f-a7ec57237ff1",
          "questionnaire_id": "3cb3bdae-96eb-4097-9cc1-01c4fcf911ca",
          "position": 1
        }
      ]
    }
  ],
  "total": 1,
  "page": 1,
  "size": 50,
  "pages": 1
}

---

Triggering an Entitlement

To start the workflow, perform a POST request to the specific entity.

Endpoints:

• Retail: POST /persons/{person_id}/entitlement_triggers
• Corporate: POST /corporates/{corporate_id}/entitlement_triggers

Request Body

Field	Type	Description
entitlement_id	UUID	Unique identifier of the entitlement (retrieved from the Listing endpoint).

Example Request

curl -X POST https://<kyc_domain>/api/v1/persons/b14254a1-cb2d-4c7c-93b2-b4ecb88a903b/entitlement_triggers \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "entitlement_id": "7b88b3a6-d6a6-49f4-a03f-a7ec57237ff1"
  }'

Example Response

View Response Example

{
  "id": "ff95245d-0c69-4d6a-9d79-8459865ac653",
  "entitlement_id": "7b88b3a6-d6a6-49f4-a03f-a7ec5723ff1",
  "status": "pending",
  "owner_type": "person",
  "owner_id": "b14254a1-cb2d-4c7c-93b2-b4ecb88a903b",
  "created_at": "2025-11-03T11:43:45.443324Z"
}

---

Checking Status (Listing Triggers)

To check the history or current status of workflows, fetch the triggers.

Endpoints:

• Retail: GET /persons/{person_id}/entitlement_triggers
• Corporate: GET /corporates/{corporate_id}/entitlement_triggers

View Response Example

{
  "items": [
    {
      "id": "ff95245d-0c69-4d6a-9d79-8459865ac653",
      "entitlement_id": "7b88b3a6-d6a6-49f4-a03f-a7ec57237ff1",
      "status": "pending",
      "owner_type": "person",
      "created_at": "2024-11-03T11:43:45.443324Z"
    },
    {
      "id": "25568503-1ead-41ff-85a9-01b6f85c4ea9",
      "entitlement_id": "2b34e3f6-6f13-4d34-b74a-9ea4930e7ae2",
      "status": "ongoing",
      "result": "success",
      "owner_type": "person",
      "created_at": "2024-12-03T12:23:13.233324Z"
    }
  ],
  "total": 2
}

---

Data Models

Entitlement

Represents a workflow definition that can activate a specific action (e.g., onboarding, proof of source of funds, derivatives).

Field	Type	Description
id	UUID	Unique identifier of the entitlement.
name	String	System name of the entitlement.
description	String	Short description of the entitlement’s purpose.
only_once	Boolean	If true, the entitlement can only be triggered once. Defaults to false.
depends_on	List[UUID]	List of entitlement IDs that must be satisfied before this one can be triggered.
retrigger_after_failure	Boolean	If true, the entitlement can be triggered again after a failure. Defaults to false.
one_at_time	Boolean	If true, only one trigger of this entitlement can be active at a time. Defaults to false.
retrigger_after_lock	Boolean	If true, the entitlement can only be triggered again once its lock has been released. Defaults to false.
api_triggerable	Boolean	Whether the entitlement can be triggered via the API. Defaults to true. When false, it is triggered internally by DLT only.
questionnaires	List[EntitlementQuestionnaire]	List of required questionnaires that need to be answered.
created_at	DateTime	Creation timestamp.
updated_at	DateTime	Last update timestamp.

Entitlement Questionnaire

Field	Type	Description
entitlement_id	UUID	Unique identifier of the parent entitlement.
questionnaire_id	UUID	Unique identifier of the questionnaire.
country	String or NULL	Optional country (ISO 3166-1 alpha-3) for which this questionnaire applies.
position	Integer	Suggested order for presenting the questionnaire in the frontend.

Entitlement Trigger

Stores information about triggered entitlements (instances of a workflow) and their results.

Field	Type	Description
id	UUID	Unique identifier of the trigger.
entitlement_id	UUID	ID of the entitlement definition used.
status	Enum	Current state. See Status below.
result	Enum	Final result. See Result below.
owner_id	UUID	ID of the entity (Person/Corporate).
owner_type	String	Type of entity (person or corporate).
created_at	DateTime	Timestamp when the trigger was created.
updated_at	DateTime	Timestamp of the last update to the trigger.

Status Values

• pending
• ongoing
• terminated
• canceled
• blocked
• failed
• finished

Result Values

• success
• fail