KYC Sessions

Endpointhttps://api.dossiers.wiki

List KYC sessions

GET

https://api.dossiers.wiki

/kyc-sessions

Retrieves a paginated list of KYC sessions for the authenticated organization. Supports filtering by state, completion status, date range, and free-text search across session ID, external ID, customer name, and email.

List KYC sessions › Request Body optional

searchQuery

string

Free-text search across session ID, external ID, customer name, and email.

Example: john

state

string · enum

Filter by session state.

Enum values:

home

permission-granting

dv-get-started

dv-document-selection

dv-document-upload

dv-positioning-front

dv-capturing-front

dv-flip-prompt

Example: home

isComplete

boolean

Filter by completion status.

Example: false

isInvalid

boolean

Filter by invalid/flagged status.

Example: false

createdAt

object

sortBy

string · enum

Field to sort by.

Enum values:

createdAt

expiresAt

completedAt

Default: createdAt

sortOrder

string · enum

Sort direction.

Enum values:

asc

desc

Default: desc

limit

number · min: 1 · max: 100

Maximum number of results to return (1–100).

Example: 20

Default: 50

offset

number · min: 0

Number of results to skip for pagination.

Example: 0

Default: 0

List KYC sessions › Responses

Paginated list of sessions.

object[] · required

List of KYC sessions matching the query.

totalCount

number · required

Total number of sessions matching the filters (before pagination).

Example: 42

GET/kyc-sessions

curl --request GET \
  --url https://api.dossiers.wiki/kyc-sessions \
  --header 'Content-Type: application/json' \
  --data '
{
  "searchQuery": "john",
  "state": "home",
  "isComplete": false,
  "isInvalid": false,
  "createdAt": {},
  "sortBy": "createdAt",
  "sortOrder": "desc",
  "limit": 50,
  "offset": 0
}
'

shell

Example Request Body

{
  "searchQuery": "john",
  "state": "home",
  "isComplete": false,
  "isInvalid": false,
  "createdAt": {},
  "sortBy": "createdAt",
  "sortOrder": "desc",
  "limit": 50,
  "offset": 0
}

json

Example Responses

{
  "sessions": [
    {
      "id": "665f1a2b3c4d5e6f7a8b9c0d",
      "organizationId": "organizationId",
      "externalId": "usr_abc123",
      "customerName": "John Doe",
      "customerEmail": "john@example.com",
      "state": "home",
      "data": {
        "country": "LK",
        "documentType": "national-id",
        "documentRatio": 1.586,
        "isDoubleSided": true
      },
      "isInvalid": false,
      "isComplete": false,
      "createdAt": 1717430827000,
      "expiresAt": 1717434427000,
      "completedAt": 0,
      "documentVerification": {
        "instanceId": "instanceId",
        "processorId": "processorId",
        "status": "completed",
        "statusLabel": "statusLabel",
        "documentTypeId": "documentTypeId",
        "triggeredAt": 1717430828000,
        "completedAt": 0,
        "error": "error",
        "result": {},
        "stageProgress": [
          "string"
        ],
        "processingLog": [
          "string"
        ],
        "files": [
          "string"
        ]
      },
      "faceVerification": {
        "verified": true,
        "distance": 0.32,
        "threshold": 0.6,
        "model": "VGG-Face",
        "performedAt": 1717430830000,
        "error": "error"
      }
    }
  ],
  "totalCount": 42
}

json

application/json

Create a KYC session

POST

https://api.dossiers.wiki

/kyc-sessions

Creates a new KYC verification session. Returns a signed session URL that can be shared with the customer. If customerEmail and customerName are provided, an invitation email with the session link and QR code is sent automatically.

Create a KYC session › Request Body optional

externalId

string

External reference ID from your system, used to correlate this session with your records.

Example: usr_abc123

expiresInMs

number

Session expiry duration in milliseconds. Defaults to 1 hour (3,600,000 ms).

Example: 3600000

customerEmail

string

Customer email address. When provided along with customerName, an invitation email with the session link is sent automatically.

Example: john@example.com

customerName

string

Customer display name, used in the invitation email greeting.

Example: John Doe

Create a KYC session › Responses

Session created successfully.

object · required

token

string · required

Short-lived JWT token for customer access to the session.

sessionUrl

string · required

Full URL the customer should visit to complete KYC verification.

Example: https://kyc.example.com/kyc/665f1a2b3c4d5e6f7a8b9c0d?token=eyJ...

POST/kyc-sessions

curl --request POST \
  --url https://api.dossiers.wiki/kyc-sessions \
  --header 'Content-Type: application/json' \
  --data '
{
  "externalId": "usr_abc123",
  "expiresInMs": 3600000,
  "customerEmail": "john@example.com",
  "customerName": "John Doe"
}
'

shell

Example Request Body

{
  "externalId": "usr_abc123",
  "expiresInMs": 3600000,
  "customerEmail": "john@example.com",
  "customerName": "John Doe"
}

json

Example Responses

{
  "session": {
    "id": "665f1a2b3c4d5e6f7a8b9c0d",
    "organizationId": "organizationId",
    "externalId": "usr_abc123",
    "customerName": "John Doe",
    "customerEmail": "john@example.com",
    "state": "home",
    "data": {
      "country": "LK",
      "documentType": "national-id",
      "documentRatio": 1.586,
      "isDoubleSided": true
    },
    "isInvalid": false,
    "isComplete": false,
    "createdAt": 1717430827000,
    "expiresAt": 1717434427000,
    "completedAt": 0,
    "documentVerification": {
      "instanceId": "instanceId",
      "processorId": "processorId",
      "status": "completed",
      "statusLabel": "statusLabel",
      "documentTypeId": "documentTypeId",
      "triggeredAt": 1717430828000,
      "completedAt": 0,
      "error": "error",
      "result": {},
      "stageProgress": [
        "string"
      ],
      "processingLog": [
        "string"
      ],
      "files": [
        "string"
      ]
    },
    "faceVerification": {
      "verified": true,
      "distance": 0.32,
      "threshold": 0.6,
      "model": "VGG-Face",
      "performedAt": 1717430830000,
      "error": "error"
    }
  },
  "token": "token",
  "sessionUrl": "https://kyc.example.com/kyc/665f1a2b3c4d5e6f7a8b9c0d?token=eyJ..."
}

json

application/json

Get a KYC session

GET

https://api.dossiers.wiki

/kyc-sessions/{id}

Retrieves a single KYC session by its ID, including document verification and face verification results if available. If document verification is still in progress, the latest status is refreshed before returning.

Get a KYC session › path Parameters

id

string · required

The unique session ID.

Example: 665f1a2b3c4d5e6f7a8b9c0d

Get a KYC session › Responses

Session details.

id

string · required

Unique session identifier.

Example: 665f1a2b3c4d5e6f7a8b9c0d

organizationId

string · required

Organization that owns this session.

state

string · enum · required

Current session state.

Enum values:

home

permission-granting

dv-get-started

dv-document-selection

dv-document-upload

dv-positioning-front

dv-capturing-front

dv-flip-prompt

Example: home

object · required

isInvalid

boolean · required

Whether the session has been flagged as invalid (e.g. exceeded attempt limit).

Example: false

isComplete

boolean · required

Whether the KYC verification flow has been completed.

Example: false

createdAt

number · required

Session creation timestamp (Unix ms).

Example: 1717430827000

externalId

string

External reference ID provided at creation.

Example: usr_abc123

customerName

string

Customer display name.

Example: John Doe

customerEmail

string

Customer email address.

Example: john@example.com

expiresAt

number | null

Session expiry timestamp (Unix ms). Null after completion.

Example: 1717434427000

completedAt

number | null

Completion timestamp (Unix ms). Null if not yet completed.

object

GET/kyc-sessions/{id}

curl --request GET \
  --url https://api.dossiers.wiki/kyc-sessions/:id

shell

Example Responses

{
  "id": "665f1a2b3c4d5e6f7a8b9c0d",
  "organizationId": "organizationId",
  "externalId": "usr_abc123",
  "customerName": "John Doe",
  "customerEmail": "john@example.com",
  "state": "home",
  "data": {
    "country": "LK",
    "documentType": "national-id",
    "documentRatio": 1.586,
    "isDoubleSided": true
  },
  "isInvalid": false,
  "isComplete": false,
  "createdAt": 1717430827000,
  "expiresAt": 1717434427000,
  "completedAt": 0,
  "documentVerification": {
    "instanceId": "instanceId",
    "processorId": "processorId",
    "status": "completed",
    "statusLabel": "statusLabel",
    "documentTypeId": "documentTypeId",
    "triggeredAt": 1717430828000,
    "completedAt": 0,
    "error": "error",
    "result": {},
    "stageProgress": [
      "string"
    ],
    "processingLog": [
      "string"
    ],
    "files": [
      "string"
    ]
  },
  "faceVerification": {
    "verified": true,
    "distance": 0.32,
    "threshold": 0.6,
    "model": "VGG-Face",
    "performedAt": 1717430830000,
    "error": "error"
  }
}

json

application/json

Delete a KYC session

DELETE

https://api.dossiers.wiki

/kyc-sessions/{id}

Permanently deletes a KYC session and all associated data.

Delete a KYC session › path Parameters

id

string · required

The unique session ID.

Example: 665f1a2b3c4d5e6f7a8b9c0d

Delete a KYC session › Responses

Session deleted successfully.

success

boolean · required

Whether the deletion was successful.

Example: true

AML Screening

List KYC sessions

GET

https://api.dossiers.wiki

/kyc-sessions

List KYC sessions › Request Body optional

searchQuery

string

Free-text search across session ID, external ID, customer name, and email.

Example: john

state

string · enum

Filter by session state.

Enum values:

home

permission-granting

dv-get-started

dv-document-selection

dv-document-upload

dv-positioning-front

dv-capturing-front

dv-flip-prompt

Example: home

isComplete

boolean

Filter by completion status.

Example: false

isInvalid

boolean

Filter by invalid/flagged status.

Example: false

createdAt

object

sortBy

string · enum

Field to sort by.

Enum values:

createdAt

expiresAt

completedAt

Default: createdAt

sortOrder

string · enum

Sort direction.

Enum values:

asc

desc

Default: desc

limit

number · min: 1 · max: 100

Maximum number of results to return (1–100).

Example: 20

Default: 50

offset

number · min: 0

Number of results to skip for pagination.

Example: 0

Default: 0

List KYC sessions › Responses

Paginated list of sessions.

object[] · required

List of KYC sessions matching the query.

totalCount

number · required

Total number of sessions matching the filters (before pagination).

Example: 42

Create a KYC session

POST

https://api.dossiers.wiki

/kyc-sessions

Create a KYC session › Request Body optional

externalId

string

External reference ID from your system, used to correlate this session with your records.

Example: usr_abc123

expiresInMs

number

Session expiry duration in milliseconds. Defaults to 1 hour (3,600,000 ms).

Example: 3600000

customerEmail

string

Customer email address. When provided along with customerName, an invitation email with the session link is sent automatically.

Example: john@example.com

customerName

string

Customer display name, used in the invitation email greeting.

Example: John Doe

Create a KYC session › Responses

Session created successfully.

object · required

token

string · required

Short-lived JWT token for customer access to the session.

sessionUrl

string · required

Full URL the customer should visit to complete KYC verification.

Example: https://kyc.example.com/kyc/665f1a2b3c4d5e6f7a8b9c0d?token=eyJ...

Get a KYC session

GET

https://api.dossiers.wiki

/kyc-sessions/{id}

Get a KYC session › path Parameters

id

string · required

The unique session ID.

Example: 665f1a2b3c4d5e6f7a8b9c0d

Get a KYC session › Responses

Session details.

id

string · required

Unique session identifier.

Example: 665f1a2b3c4d5e6f7a8b9c0d

organizationId

string · required

Organization that owns this session.

state

string · enum · required

Current session state.

Enum values:

home

permission-granting

dv-get-started

dv-document-selection

dv-document-upload

dv-positioning-front

dv-capturing-front

dv-flip-prompt

Example: home

object · required

isInvalid

boolean · required

Whether the session has been flagged as invalid (e.g. exceeded attempt limit).

Example: false

isComplete

boolean · required

Whether the KYC verification flow has been completed.

Example: false

createdAt

number · required

Session creation timestamp (Unix ms).

Example: 1717430827000

externalId

string

External reference ID provided at creation.

Example: usr_abc123

customerName

string

Customer display name.

Example: John Doe

customerEmail

string

Customer email address.

Example: john@example.com

expiresAt

number | null

Session expiry timestamp (Unix ms). Null after completion.

Example: 1717434427000

completedAt

number | null

Completion timestamp (Unix ms). Null if not yet completed.

object

Delete a KYC session

DELETE

https://api.dossiers.wiki

/kyc-sessions/{id}

Permanently deletes a KYC session and all associated data.

Delete a KYC session › path Parameters

id

string · required

The unique session ID.

Example: 665f1a2b3c4d5e6f7a8b9c0d

Delete a KYC session › Responses

Session deleted successfully.

success

boolean · required

Whether the deletion was successful.

Example: true