🦸‍♂️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

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

post

/customers

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

externalIdstringrequired

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

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.offblocks.xyz/v1/customers' \
  --header 'Authorization: Bearer JWT' \
  --header 'Signature: text' \
  --header 'Signature-Input: text' \
  --header 'Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000' \
  --header 'Content-Digest: text' \
  --header 'Content-Type: application/json' \
  --data '{
    "chainId": "eip155:1:0xab16a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb",
    "externalId": "text"
  }'

201

400

401

409

500

201

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "externalId": "text",
  "chainId": "eip155:1:0xab16a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb",
  "status": "initiating",
  "createdAt": "2025-02-28T07:02:41.015Z",
  "updatedAt": "2025-02-28T07:02:41.015Z",
  "challenge": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUZZd0VBWUhLb1pJemowQ0FRWUZLNEVFQUFvRFFnQUUzTEw1RldmVFgvL3BJaXNEL0xneFVIT2lxdlFTSUVWTgpGekloOTdLZXBlWk1iZVZsUGd1akZ4Yk5MN2x1ZVhRQnBpUWUzNmZLN0xSbXZNNHdEaWZFTkE9PQotLS0tLUVORCBQVUJMSUMgS0VZLS0tLS0="
}

Successful operation

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

Retrieves customers' details

get

/customers

Authorizations

Header parameters

Signaturestringrequired

HTTP message signature

Signature-Inputstringrequired

HTTP message signature input

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.offblocks.xyz/v1/customers' \
  --header 'Authorization: Bearer JWT' \
  --header 'Signature: text' \
  --header 'Signature-Input: text'

200

400

401

500

200

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "externalId": "text",
    "chainId": "eip155:1:0xab16a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb",
    "status": "initiating",
    "createdAt": "2025-02-28T07:02:41.015Z",
    "updatedAt": "2025-02-28T07:02:41.015Z"
  }
]

Successful operation

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

Retrieves customer's details

get

/customers/{customerId}

Authorizations

Path parameters

customerIdstring · uuidrequired

Unique customer ID

Header parameters

Signaturestringrequired

HTTP message signature

Signature-Inputstringrequired

HTTP message signature input

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.offblocks.xyz/v1/customers/{customerId}' \
  --header 'Authorization: Bearer JWT' \
  --header 'Signature: text' \
  --header 'Signature-Input: text'

200

400

401

404

500

200

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "externalId": "text",
  "chainId": "eip155:1:0xab16a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb",
  "status": "initiating",
  "createdAt": "2025-02-28T07:02:41.015Z",
  "updatedAt": "2025-02-28T07:02:41.015Z"
}

Successful operation

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

Deactivates customer and all associated resources

patch

/customers/{customerId}/deactivate

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

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PATCH \
  --url 'https://api.offblocks.xyz/v1/customers/{customerId}/deactivate' \
  --header 'Authorization: Bearer JWT' \
  --header 'Signature: text' \
  --header 'Signature-Input: text' \
  --header 'Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000'

200

400

401

404

409

500

200

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "externalId": "text",
  "chainId": "eip155:1:0xab16a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb",
  "status": "initiating",
  "createdAt": "2025-02-28T07:02:41.015Z",
  "updatedAt": "2025-02-28T07:02:41.015Z"
}

Successful operation

Reactivate a Customer

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

Activate customer

Activates customer and all associated resources

patch

/customers/{customerId}/activate

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

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PATCH \
  --url 'https://api.offblocks.xyz/v1/customers/{customerId}/activate' \
  --header 'Authorization: Bearer JWT' \
  --header 'Signature: text' \
  --header 'Signature-Input: text' \
  --header 'Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000'

200

400

401

404

409

500

200

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "externalId": "text",
  "chainId": "eip155:1:0xab16a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb",
  "status": "initiating",
  "createdAt": "2025-02-28T07:02:41.015Z",
  "updatedAt": "2025-02-28T07:02:41.015Z"
}

Successful operation