🦸‍♂️Customers

API reference for customer-related endpoints

Add a New Customer

To add a new customer to the system, use the authenticated /customer POST endpoint. This will initialise a new customer entity and start KYC verification process. The response contains a verification URL that redirects to our KYC partner's portal for further verification.

Create new customer

post

Creates new customer and generates a cryptographic challenge to verify ownership of blockchain account

Authorizations

Header parameters

SignaturestringRequired

HTTP message signature

Signature-InputstringRequired

HTTP message signature input

Idempotency-Keystring · uuidRequired

Idempotency key (UUID)

Content-DigeststringRequired

Content digest

Body

chainIdstringRequired

Unique customer ID in a form of a valid on-chain address. This would normally correspond to customer's EOA wallet address

Example: eip155:1:0xab16a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb

externalIdstringRequired

Unique customer ID in a form of an external identifier. This would normally correspond to customer's ID in your system

Responses

201

Successful operation

application/json

Responseall of

and

400

Invalid request

401

Not authorised

409

Customer already exists

500

Internal error

post

HTTPcURLJavaScriptPython

POST /v1/customers HTTP/1.1
Host: api.offblocks.xyz
Authorization: Bearer JWT
Signature: text
Signature-Input: text
Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000
Content-Digest: text
Content-Type: application/json
Accept: */*
Content-Length: 85

{
  "chainId": "eip155:1:0xab16a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb",
  "externalId": "text"
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "externalId": "text",
  "chainId": "eip155:1:0xab16a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb",
  "status": "initiating",
  "createdAt": "2025-05-09T06:52:38.272Z",
  "updatedAt": "2025-05-09T06:52:38.272Z",
  "challenge": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUZZd0VBWUhLb1pJemowQ0FRWUZLNEVFQUFvRFFnQUUzTEw1RldmVFgvL3BJaXNEL0xneFVIT2lxdlFTSUVWTgpGekloOTdLZXBlWk1iZVZsUGd1akZ4Yk5MN2x1ZVhRQnBpUWUzNmZLN0xSbXZNNHdEaWZFTkE9PQotLS0tLUVORCBQVUJMSUMgS0VZLS0tLS0="
}

Customer Entity Updates

Any internal updates to the customer entity will trigger a webhook update event. For details on how to set up and manage webhook subscriptions, please refer to Webhooks.

Blockchain Updates

In order to proceed with customer verification, a challenge needs to be signed and verified (see Blockchain Updates).

Retrieve Customer Entities

To retrieve a list of all customer entities registered for the programme, make a GET request to /customers.

Retrieve customers

get

Retrieves customers' details

Authorizations

Header parameters

SignaturestringRequired

HTTP message signature

Signature-InputstringRequired

HTTP message signature input

Responses

200

Successful operation

application/json

400

Invalid request

401

Not authorised

500

Internal error

get

HTTPcURLJavaScriptPython

GET /v1/customers HTTP/1.1
Host: api.offblocks.xyz
Authorization: Bearer JWT
Signature: text
Signature-Input: text
Accept: */*

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "externalId": "text",
    "chainId": "eip155:1:0xab16a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb",
    "status": "initiating",
    "createdAt": "2025-05-09T06:52:38.272Z",
    "updatedAt": "2025-05-09T06:52:38.272Z"
  }
]

Retrieve an Individual Customer

To retrieve information about an individual customer, make a GET request to /customers/{customerId} with customer ID as a path parameter.

Retrieve customer

get

Retrieves customer's details

Authorizations

Path parameters

customerIdstring · uuidRequired

Unique customer ID

Header parameters

SignaturestringRequired

HTTP message signature

Signature-InputstringRequired

HTTP message signature input

Responses

200

Successful operation

application/json

400

Invalid request

401

Not authorised

404

Customer not found

500

Internal error

get

HTTPcURLJavaScriptPython

GET /v1/customers/{customerId} HTTP/1.1
Host: api.offblocks.xyz
Authorization: Bearer JWT
Signature: text
Signature-Input: text
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "externalId": "text",
  "chainId": "eip155:1:0xab16a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb",
  "status": "initiating",
  "createdAt": "2025-05-09T06:52:38.272Z",
  "updatedAt": "2025-05-09T06:52:38.272Z"
}

Deactivate a Customer

To deactivate a customer, use a PATCH request to /customers/{customerId}/deactivate. This will also deactivate all associated resources, such as accounts and cards.

Deactivate customer

patch

Deactivates customer and all associated resources

Authorizations

Path parameters

customerIdstring · uuidRequired

Unique customer ID

Header parameters

SignaturestringRequired

HTTP message signature

Signature-InputstringRequired

HTTP message signature input

Idempotency-Keystring · uuidRequired

Idempotency key (UUID)

Responses

200

Successful operation

application/json

400

Invalid request

401

Not authorised

404

Customer not found

409

Invalid state transition

500

Internal error

patch

HTTPcURLJavaScriptPython

PATCH /v1/customers/{customerId}/deactivate HTTP/1.1
Host: api.offblocks.xyz
Authorization: Bearer JWT
Signature: text
Signature-Input: text
Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "externalId": "text",
  "chainId": "eip155:1:0xab16a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb",
  "status": "initiating",
  "createdAt": "2025-05-09T06:52:38.272Z",
  "updatedAt": "2025-05-09T06:52:38.272Z"
}

Reactivate a Customer

To reactivate a previously deactivated customer, use a PATCH request to /customers/{customerId}/activate.

Activate customer

patch

Activates customer and all associated resources

Authorizations

Path parameters

customerIdstring · uuidRequired

Unique customer ID

Header parameters

SignaturestringRequired

HTTP message signature

Signature-InputstringRequired

HTTP message signature input

Idempotency-Keystring · uuidRequired

Idempotency key (UUID)

Responses

200

Successful operation

application/json

400

Invalid request

401

Not authorised

404

Customer not found

409

Invalid state transition

500

Internal error

patch

HTTPcURLJavaScriptPython

PATCH /v1/customers/{customerId}/activate HTTP/1.1
Host: api.offblocks.xyz
Authorization: Bearer JWT
Signature: text
Signature-Input: text
Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "externalId": "text",
  "chainId": "eip155:1:0xab16a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb",
  "status": "initiating",
  "createdAt": "2025-05-09T06:52:38.272Z",
  "updatedAt": "2025-05-09T06:52:38.272Z"
}