Universal KYC

Endpoints

Method	URL	Description
POST	`/entity/{entityId}/requirement`	Submit requirement for entity
POST	`/entity/{entityId}/requirement-slug/{requirementSlug}/upload`	Upload a file for entity

Submit Requirement for Entity

POST /entity/{entityId}/requirement

Submits a KYC requirement with canonical identity data for a given entity.

Path Parameters

Name	Type	Required	Description
`entityId`	string	Yes	The unique identifier (UUID) of the entity

Request Body (application/json)

Field	Type	Required	Description
`requirementSlug`	string	Yes	Requirement slug. Allowed value: `ukyc-canonical-kyc-data`
`value`	string	Yes	JSON-stringified canonical KYC payload (see Payload Schema below)

Payload Schema

The value field must be a JSON-stringified object conforming to the following structure:

{
  "externalUserId": "usr-12345",             // Required — your external user identifier (max 255 chars)
  "cardProcessorPublicToken": "tok_abc",     // Optional — card processor public token

  "provider": {
    "name": "sumsub",                        // Required — "sumsub" | "jumio" | "comply_advantage"
    "status": "APPROVED",                    // Required — "APPROVED" | "REJECTED" | "WARNING" | "NOT_EXECUTED"
    "data": [{}]                             // Required — array of provider-specific data objects
  },

  "identity": {
    "firstName": "John",                     // Required — Latin characters only (max 100)
    "middleName": "Michael",                 // Optional — Latin characters only (max 100)
    "lastName": "Doe",                       // Optional — Latin characters only (max 100)
    "fullName": "John Michael Doe",          // Required — Latin characters only (max 200)
    "dob": "1990-01-15",                     // Required — YYYY-MM-DD; applicant must be aged 18–150
    "nationality": "USA"                     // Required — ISO 3166-1 alpha-3 country code
  },

  "document": [                              // Required — at least one document
    {
      "type": "PASSPORT",                   // Required — see Document Types below
      "number": "AB1234567",                // Required — max 50 chars; must not be whitespace-only
      "country": "USA",                     // Required — ISO 3166-1 alpha-3 country code
      "issuingDate": "2020-03-01",          // Required — YYYY-MM-DD; must not be in the future
      "expiryDate": "2030-03-01"            // Optional — YYYY-MM-DD; must not be expired; must be after issuingDate
    }
  ],

  "address": {
    "country": "USA",                        // Required — ISO 3166-1 alpha-3 country code
    "postCode": "10001",                     // Required — max 20 chars
    "street": "123 Main St",                // Required — max 200 chars
    "town": "New York",                     // Optional — max 100 chars
    "subStreet": "Apt 4B",                  // Optional — max 200 chars
    "state": "NY",                          // Optional — max 100 chars
    "buildingName": "Tower A",              // Optional — max 100 chars
    "flatNumber": "4B",                     // Optional — max 20 chars
    "buildingNumber": "123",                // Optional — max 20 chars
    "formattedAddress": "123 Main St, …"    // Optional — max 500 chars
  },

  "liveness": {
    "result": "APPROVED",                    // Required — "APPROVED" | "REJECTED" | "WARNING" | "NOT_EXECUTED"
    "checkedAt": "2024-01-15T10:30:00Z"     // Required unless result is "NOT_EXECUTED"; ISO 8601 datetime
  }
}

Document Types

Value	Description
`PASSPORT`	International passport
`ID_CARD`	National identity card
`DRIVERS_LICENCE`	Driver's licence
`RESIDENCE_PERMIT`	Residence permit or visa
`UTILITY_BILL`	Proof-of-address document (utility bill, bank statement, etc.)
`UTILITY_BILL2`	Secondary proof-of-address document

Responses

Status	Description
`201`	Requirement successfully submitted
`400`	Validation error (invalid payload or parameters)
`401`	Unauthorized — missing or invalid API key
`404`	Entity not found

Upload a File for Entity

POST /entity/{entityId}/requirement-slug/{requirementSlug}/upload

Uploads a supporting document (e.g., ID scan, proof of address) for an entity requirement.

Path Parameters

Name	Type	Required	Description
`entityId`	string	Yes	The unique identifier (UUID) of the entity
`requirementSlug`	string	Yes	Requirement slug. Allowed values: `ukyc-id-document`, `ukyc-proof-of-address-document`

Query Parameters

Name	Type	Required	Description
`memberId`	string	No	The ID of the entity member the file is being uploaded for

Request Body (multipart/form-data)

Field	Type	Required	Description
`files`	binary[]	Yes	The file(s) to upload

Responses

Status	Description
`201`	File uploaded successfully
`401`	Unauthorized — missing or invalid API key
`404`	Entity or requirement not found