Entitlements

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

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/persons
• Corporate: GET /entitlements/corporates

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-a7ec57237ff1",
  "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.
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.
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).

Status Values

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

Result Values

• success
• fail