Identifications

An identification is the verified identity behind one or more accounts: KYC for a person, KYB for a company. Its status decides what the linked accounts can do.

Status	Meaning
`initiated`	Verification has started but isn't finished.
`approved`	Verification passed. Services are enabled.
`attention`	Depa needs to review it manually.
`rejected`	Verification failed.
`blocked`	Suspended. Trades and payments are blocked on every linked account.
`closed`	Closed before verification finished.

There are three ways to create one:

Hosted verification: POST /identifications/create_identify_process returns a Depa URL where your customer completes KYC or KYB.
Soft KYC: POST /identifications/soft_kyc submits a person's or company's details for Depa to review.
Import: POST /identifications/import_identity brings in an identity you've already verified. Depa has to enable this for your vault.

Blocking an identification stops trades and payments on all its accounts and sends an account_locked webhook for each one. Unblocking restores them and sends account_unlocked.

List identifications

GET/identifications

Returns the identifications in your vault. Filter by filter[external_uuid] to find one by your own ID.

Authorization

BearerAuth

AuthorizationBearer <token>

Token from POST /sign_in, sent as Authorization: Bearer <token>.

In: header

Query Parameters

filter[external_uuid]?string

Return only the identification with this external ID.

page?integer

Page number, starting at 1.

Range1 <= value

Default1

per_page?integer

Number of results per page.

Range1 <= value

`application/json`

curl -X GET "https://example.com/identifications?filter%5Bexternal_uuid%5D=016aba24-5d22-4008-b7ed-0c77bbe044c6&page=1"

{  "data": [    {      "id": "25f21bf7-54d2-4b47-9db2-af48558df5eb",      "status": "approved",      "name": "Jane",      "surname": "Doe",      "external_uuid": "016aba24-5d22-4008-b7ed-0c77bbe044c6",      "account_id": "8f3a2c1e-5b7d-4e9a-9c21-7d4b6e0f1a23",      "account_referral": "IEM1DJ",      "created_at": 1766421280    }  ]}

Retrieve an identification

GET/identifications/{identification_id}

Returns an identification, its verification status and the account it's linked to.

Authorization

BearerAuth

AuthorizationBearer <token>

Token from POST /sign_in, sent as Authorization: Bearer <token>.

In: header

Path Parameters

identification_id*string

ID of the identification.

Formatuuid

`application/json`

curl -X GET "https://example.com/identifications/25f21bf7-54d2-4b47-9db2-af48558df5eb"

{  "data": {    "id": "25f21bf7-54d2-4b47-9db2-af48558df5eb",    "status": "approved",    "name": "Jane",    "surname": "Doe",    "external_uuid": "016aba24-5d22-4008-b7ed-0c77bbe044c6",    "account_id": "8f3a2c1e-5b7d-4e9a-9c21-7d4b6e0f1a23",    "account_referral": "IEM1DJ",    "created_at": 1766421280  }}

Update an identification

PUT/identifications/{identification_id}

Updates the contact details, address and profile of an identification. Send only the fields you want to change.

Authorization

BearerAuth

AuthorizationBearer <token>

Token from POST /sign_in, sent as Authorization: Bearer <token>.

In: header

Path Parameters

identification_id*string

ID of the identification.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Send only the fields you want to change.

email?string

Updated email address

Formatemail

phone?string

Phone number with country prefix.

employment_status?string

Current employment status

occupation?string

Current occupation

address_country?string

Two-letter country code as defined in ISO 3166-1 alpha-2 standard (e.g., ES for Spain, US for United States).

Match^[A-Z]{2}$

Lengthlength <= 2

address?string

Street address

city?string

City of residence

state?string

State or province

postal_code?string

Postal or ZIP code

`application/json`

curl -X PUT "https://example.com/identifications/25f21bf7-54d2-4b47-9db2-af48558df5eb" \  -H "Content-Type: application/json" \  -d '{    "phone": "+34612345678",    "address": "Calle de Alcalá 42",    "city": "Madrid",    "postal_code": "28014",    "address_country": "ES"  }'

{  "data": {    "id": "25f21bf7-54d2-4b47-9db2-af48558df5eb",    "status": "approved",    "name": "Jane",    "surname": "Doe",    "external_uuid": "016aba24-5d22-4008-b7ed-0c77bbe044c6",    "account_id": "8f3a2c1e-5b7d-4e9a-9c21-7d4b6e0f1a23",    "account_referral": "IEM1DJ",    "created_at": 1766421280  }}

Close an identification

PUT/identifications/{identification_id}/close

Closes an identification you no longer need. What happens depends on its status:

initiated: it becomes closed. Use this to abandon a KYC or KYB process that was never finished.
approved: it becomes blocked, and trades, fiat payments, blockchain payments and card payments are blocked on its accounts.

Identifications in any other status can't be closed (422, cannot_close). Closing can't be undone through the API.

Authorization

BearerAuth

AuthorizationBearer <token>

Token from POST /sign_in, sent as Authorization: Bearer <token>.

In: header

Path Parameters

identification_id*string

The UUID of the identification to close

Formatuuid

`application/json`

curl -X PUT "https://example.com/identifications/25f21bf7-54d2-4b47-9db2-af48558df5eb/close"

{  "data": {    "id": "25f21bf7-54d2-4b47-9db2-af48558df5eb",    "status": "approved",    "name": "Jane",    "surname": "Doe",    "external_uuid": "016aba24-5d22-4008-b7ed-0c77bbe044c6",    "account_id": "8f3a2c1e-5b7d-4e9a-9c21-7d4b6e0f1a23",    "account_referral": "IEM1DJ",    "created_at": 1766421280  }}

Block an identification

POST/identifications/{identification_id}/block

Suspends an identification immediately, for example on suspected fraud. Every account linked to it is blocked from trades, fiat payments, blockchain payments, card payments and, where enabled for your vault, internal settlements.

The identification's status becomes blocked.
Each affected account sends an account_locked webhook.
The reason and notes you send are recorded on every blocked service, together with the user who blocked it.

Blocking is idempotent: blocking an identification that's already blocked succeeds and returns its current state. A vault-scoped variant is available at POST /vaults/{vault_id}/identifications/{identification_id}/block.

Authorization

BearerAuth

AuthorizationBearer <token>

Token from POST /sign_in, sent as Authorization: Bearer <token>.

In: header

Path Parameters

identification_id*string

The UUID of the identification to block

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

reason?string

Reason for the block. Restricted to the allowed lock reasons: - fraud: suspected fraudulent activity - closure: closed at the customer's request - manual: manual block decided by operations If omitted, the block is recorded without a reason and webhooks report manual.

Value in

"fraud"
"closure"
"manual"

notes?string

Free-text notes describing the block. Stored and visible in the backoffice.

Response Body

`application/json`

curl -X POST "https://example.com/identifications/25f21bf7-54d2-4b47-9db2-af48558df5eb/block" \  -H "Content-Type: application/json" \  -d '{    "reason": "fraud",    "notes": "Cardholder reported the card as stolen; account frozen pending review"  }'

{  "data": {    "id": "25f21bf7-54d2-4b47-9db2-af48558df5eb",    "status": "blocked",    "name": "John",    "surname": "Doe",    "external_uuid": "016aba24-5d22-4008-b7ed-0c77bbe044c6",    "account_id": "e733a250-9d84-49c8-86b5-b413d4a86409",    "account_referral": "IEM1DJ",    "created_at": 1766421280  }}

Unblock an identification

POST/identifications/{identification_id}/unblock

Lifts a block: all services are restored, the status returns to approved, and each affected account sends an account_unlocked webhook. A vault-scoped variant is available at POST /vaults/{vault_id}/identifications/{identification_id}/unblock.

You can't unblock:

an identification that isn't blocked, including closed ones (422, cannot_unblock);
an identification blocked by Depa operations or transaction monitoring. These are managed in an internal case and return 422 with Identification has blocks managed by an internal case. Contact support.

Authorization

BearerAuth

AuthorizationBearer <token>

Token from POST /sign_in, sent as Authorization: Bearer <token>.

In: header

Path Parameters

identification_id*string

The UUID of the identification to unblock

Formatuuid

Response Body

`application/json`

curl -X POST "https://example.com/identifications/25f21bf7-54d2-4b47-9db2-af48558df5eb/unblock"

{  "data": {    "id": "25f21bf7-54d2-4b47-9db2-af48558df5eb",    "status": "approved",    "name": "John",    "surname": "Doe",    "external_uuid": "016aba24-5d22-4008-b7ed-0c77bbe044c6",    "account_id": "e733a250-9d84-49c8-86b5-b413d4a86409",    "account_referral": "IEM1DJ",    "created_at": 1766421280  }}

Import a verified identity

POST/identifications/import_identity

Creates an identification and an account from an identity you've already verified, keyed by your external_uuid. Depa has to enable imports for your vault before you can use it.

Authorization

BearerAuth

AuthorizationBearer <token>

Token from POST /sign_in, sent as Authorization: Bearer <token>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

external_uuid*string

Your ID for the person or company.

Response Body

`application/json`

curl -X POST "https://example.com/identifications/import_identity" \  -H "Content-Type: application/json" \  -d '{    "external_uuid": "016aba24-5d22-4008-b7ed-0c77bbe044c6"  }'

{  "data": {    "id": "25f21bf7-54d2-4b47-9db2-af48558df5eb",    "status": "approved",    "name": "Jane",    "surname": "Doe",    "external_uuid": "016aba24-5d22-4008-b7ed-0c77bbe044c6",    "account_id": "8f3a2c1e-5b7d-4e9a-9c21-7d4b6e0f1a23",    "account_referral": "IEM1DJ",    "created_at": 1766421280  }}

Submit KYC details

POST/identifications/soft_kyc

Creates an identification from details you submit, for a person (kind: person) or a company (kind: company). Depa reviews it manually; follow the outcome through the identification's status.

Authorization

BearerAuth

AuthorizationBearer <token>

Token from POST /sign_in, sent as Authorization: Bearer <token>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Identity details of a person.

name*string

First name.

surname*string

Last name.

address*string

Street address.

city*string

City.

country*string

Two-letter country code as defined in ISO 3166-1 alpha-2 standard (e.g., ES for Spain, US for United States).

birthdate*string

Date of birth (YYYY-MM-DD).

Formatdate

email*string

Email address.

Formatemail

document_number*string

Number of the identity document.

document_type*string

Type of identity document.

Value in

"WORK_PERMIT"
"PASSPORT"
"NATIONAL_ID"
"DRIVERS_LICENCE"

kind*"person"

Always person.

Value in

"person"

Response Body

`application/json`

curl -X POST "https://example.com/identifications/soft_kyc" \  -H "Content-Type: application/json" \  -d '{    "kind": "person",    "name": "Jane",    "surname": "Doe",    "address": "10 Downing Street",    "city": "London",    "country": "GB",    "birthdate": "1990-04-21",    "email": "jane.doe@example.com",    "document_type": "PASSPORT",    "document_number": "502935023523J"  }'

{  "data": {    "id": "25f21bf7-54d2-4b47-9db2-af48558df5eb",    "status": "approved",    "name": "Jane",    "surname": "Doe",    "external_uuid": "016aba24-5d22-4008-b7ed-0c77bbe044c6",    "account_id": "8f3a2c1e-5b7d-4e9a-9c21-7d4b6e0f1a23",    "account_referral": "IEM1DJ",    "created_at": 1766421280  }}

Start hosted verification

POST/identifications/create_identify_process

Starts a KYC (type: kyc) or KYB (type: kyb) verification and returns the Depa URL where your customer completes it. For KYB, the response also includes generated_password, which the company uses to sign in and fill in the KYB form.

Verification finishes asynchronously; follow it through the identification's status.

Authorization

BearerAuth

AuthorizationBearer <token>

Token from POST /sign_in, sent as Authorization: Bearer <token>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

type*string

kyc to verify a person, kyb to verify a company.

Value in

"kyb"
"kyc"

external_id?string

Your ID for the person or company.

Response Body

`application/json`

curl -X POST "https://example.com/identifications/create_identify_process" \  -H "Content-Type: application/json" \  -d '{    "type": "kyc"  }'

{  "data": {    "url": "https://sandbox.depasify.com/en/25d1a676-14d1-4ee5-8b63-c1cfb3e1b187",    "generated_password": "11c2a59e90366568"  }}

List identificationsCopy Anchor Link

AuthorizationCopy Anchor Link

Query ParametersCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

401application/json

Retrieve an identificationCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

401application/json

404application/json

Update an identificationCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

401application/json

404application/json

422application/json

Close an identificationCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

401application/json

404application/json

422application/json

Block an identificationCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

401application/json

404application/json

422application/json

Unblock an identificationCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

401application/json

404application/json

422application/json

Import a verified identityCopy Anchor Link

AuthorizationCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

401application/json

422application/json

Submit KYC detailsCopy Anchor Link

AuthorizationCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

400

401application/json

422application/json

Start hosted verificationCopy Anchor Link

AuthorizationCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

401application/json

422application/json

List identifications

Authorization

Query Parameters

Response Body

`application/json`

`application/json`

Retrieve an identification

Authorization

Path Parameters

Response Body

`application/json`

`application/json`

`application/json`

Update an identification

Authorization

Path Parameters

Request Body

Response Body

`application/json`

`application/json`

`application/json`

`application/json`

Close an identification

Authorization

Path Parameters

Response Body

`application/json`

`application/json`

`application/json`

`application/json`

Block an identification

Authorization

Path Parameters

Request Body

Response Body

`application/json`

`application/json`

`application/json`

`application/json`

Unblock an identification

Authorization

Path Parameters

Response Body

`application/json`

`application/json`

`application/json`

`application/json`

Import a verified identity

Authorization

Request Body

Response Body

`application/json`

`application/json`

`application/json`

Submit KYC details

Authorization

Request Body

Response Body

`application/json`

`application/json`

`application/json`

Start hosted verification

Authorization

Request Body

Response Body

`application/json`

`application/json`

`application/json`