Clients

Create New Client

Creates a new client linked to crypto vault and creates new wallets for each of the integrated blockchains. Clients represent external entities in segregated and consolidated vaults - they are identified by an externalId (your system's ID) and are used to separate funds and transactions by client in RoxCustody.

Body Parameters
id

string

requiredmax(255)

Client ID

BODY
{
  "id": "client123"
}

Responses

201

Client Created Successfully
message

string

Success message

client

object

Created client details

Show child parameters
externalId

string

External client ID (Your system ID) provided in your request

id

number

Internal client ID (Our system ID)

createdAt

string

Client creation timestamp

updatedAt

string

Client last updated timestamp

status

number

HTTP status code

201 RESPONSE
{
  "message": "Client created successfully.",
  "client": {
    "externalId": "client123",
    "id": 4,
    "createdAt": "20 August, 2025 11:18:53",
    "updatedAt": "20 August, 2025 11:18:53"
  },
  "status": 201
}

404

Vault Not Found
message

string

Error message

status

number

HTTP status code

errors

object

Error details

Show child parameters
message

string

Error message

code

string

Error code

404 RESPONSE
{
  "status": 404,
  "message": "Vault not found, or vault type is not allowed for creating clients",
  "errors": {
    "message": "Vault not found, or vault type is not allowed for creating clients"
  },
  "code": "E05401"
}

422

Client ID Already Exists
message

string

Error message

errors

object

Validation errors

Show child parameters
clients

array

Error message for clients field

Show child parameters
id

string

Id of the client

externalId

string

External id of the client

status

number

HTTP status code

code

string

Error code

422 RESPONSE
{
  "status": 422,
  "message": "UnprocessableEntityException",
  "errors": {
    "clients": [
      {
        "id": 1,
        "externalId": "client"
      }
    ]
  },
  "code": "E03401"
}

422

Validation Error
message

string

Error message

errors

object

Validation errors

Show child parameters
message

string

Error message

id

array

Array of error messages for id field

status

number

HTTP status code

code

string

Error code

422 RESPONSE
{
  "status": 422,
  "message": "id must be a string",
  "errors": {
    "message": "id must be a string",
    "id": [
      "id must be a string",
      "The value must not exceed 255 characters",
      "The id field is required."
    ]
  },
  "code": "E00402"
}

Create Clients

Creates multiple clients at once linked to the crypto vault and creates new wallets for each of the integrated blockchains. Clients represent external entities in segregated and consolidated vaults - they are identified by an externalId (your system's ID) and are used to separate funds and transactions by client in RoxCustody.

Body Parameters
ids

array

requiredeach max(255)

Array of client IDs

Show child parameters
id

string

Individual client ID

BODY
{
  "ids": [
    "client1",
    "client2",
    "client3",
    "client4",
    "client5"
  ]
}

Responses

201

Clients Created Successfully
message

string

Success message

clients

array

Array of created client details

Show child parameters
externalId

string

External client ID provided in request

id

number

Internal client ID

createdAt

string

Client creation timestamp

updatedAt

string

Client last updated timestamp

status

number

HTTP status code

201 RESPONSE
{
  "message": "Clients created successfully.",
  "clients": [
    {
      "externalId": "client1",
      "id": 9,
      "createdAt": "20 August, 2025 11:51:20",
      "updatedAt": "20 August, 2025 11:51:20"
    },
    {
      "externalId": "client2",
      "id": 10,
      "createdAt": "20 August, 2025 11:51:20",
      "updatedAt": "20 August, 2025 11:51:20"
    },
    {
      "externalId": "client3",
      "id": 11,
      "createdAt": "20 August, 2025 11:51:20",
      "updatedAt": "20 August, 2025 11:51:20"
    },
    {
      "externalId": "client4",
      "id": 12,
      "createdAt": "20 August, 2025 11:51:20",
      "updatedAt": "20 August, 2025 11:51:20"
    },
    {
      "externalId": "client5",
      "id": 13,
      "createdAt": "20 August, 2025 11:51:20",
      "updatedAt": "20 August, 2025 11:51:20"
    }
  ],
  "status": 201
}

422

Some Client IDs Already Exist
message

string

Error message

errors

object

Validation errors

Show child parameters
clients

array

Error message for clients field

Show child parameters
id

string

Id of the client

externalId

string

External id of the client

status

number

HTTP status code

code

string

Error code

422 RESPONSE
{
  "status": 422,
  "message": "UnprocessableEntityException",
  "errors": {
    "clients": [
      {
        "id": 1,
        "externalId": "client1"
      },
      {
        "id": 2,
        "externalId": "client2"
      },
      {
        "id": 3,
        "externalId": "client3"
      }
    ]
  },
  "code": "E03401"
}

404

Vault Not Found
message

string

Error message

status

number

HTTP status code

errors

object

Error details

Show child parameters
message

string

Error message

code

string

Error code

404 RESPONSE
{
  "status": 404,
  "message": "Vault not found, or vault type is not allowed for creating clients",
  "errors": {
    "message": "Vault not found, or vault type is not allowed for creating clients"
  },
  "code": "E05401"
}

422

Validation Error
message

string

Error message

errors

object

Validation errors

Show child parameters
message

string

Error message

ids

array

Array of validation error messages for ids field

status

number

HTTP status code

code

string

Error code

422 RESPONSE
{
  "status": 422,
  "message": "Each value must not exceed 255 characters",
  "errors": {
    "message": "Each value must not exceed 255 characters",
    "ids": [
      "Each value must not exceed 255 characters",
      "each value in ids must be a string",
      "The ids field is required.",
      "ids must not be empty",
      "ids must be an array"
    ]
  },
  "code": "E00402"
}

Create Fiat Client

Creates a new client of category FIAT linked to this vault. Allowed only for Fiat Vault credentials. Refunding Prerequisite: Under the hood, fiat deposits are only refundable if the client's bank details are known. You must provide the client's IBAN during registration to make transactions eligible for refunding. Without a registered IBAN, the payment gateway cannot identify the destination account to reverse/refund funds.

Body Parameters
id

string

required

Unique client identifier in your system

name

string

required

Full legal name as registered at their bank

identityNumber

string

required

National ID, Iqama, or Commercial Registration number (10 to 12 characters)

IBAN

string

optional

Bank IBAN. Required to support refunds. Must begin with Saudi Arabia prefix 'SA'

email

string

optional

Valid email address

mobile

string

optional

Mobile phone number

BODY
{
  "id": "client_external_id_123",
  "name": "Full Legal Name",
  "identityNumber": "1098765432",
  "IBAN": "SA1234567890123456789012",
  "email": "user@domain.com",
  "mobile": "+966500000002"
}

Responses

201

Client Created Successfully
message

string

Success message

client

object

Created client details

Show child parameters
externalId

string

External client ID

name

string

Client name

email

string

Email address

mobile

string

Mobile number

id

number

Internal ID

createdAt

string

Creation timestamp

updatedAt

string

Update timestamp

status

number

HTTP status code

201 RESPONSE
{
  "message": "Client created successfully.",
  "client": {
    "externalId": "client_external_id_123",
    "name": "Full Legal Name",
    "identityNumber": "1098765432",
    "IBAN": "SA1234567890123456789012",
    "email": "user@domain.com",
    "mobile": "+966500000002",
    "id": 104,
    "createdAt": "20 August, 2025 11:18:53",
    "updatedAt": "20 August, 2025 11:18:53"
  },
  "status": 201
}

404

Vault Not Found
message

string

Error message

status

number

HTTP status code

errors

object

Error details

Show child parameters
message

string

Error message

code

string

Error code

404 RESPONSE
{
  "status": 404,
  "message": "Vault not found, or vault type is not allowed for creating clients",
  "errors": {
    "message": "Vault not found, or vault type is not allowed for creating clients"
  },
  "code": "E05401"
}

422

Client ID Already Exists
message

string

Error message

errors

object

Validation errors

Show child parameters
clients

array

Error message for clients field

Show child parameters
id

string

Id of the client

externalId

string

External id of the client

status

number

HTTP status code

code

string

Error code

422 RESPONSE
{
  "status": 422,
  "message": "UnprocessableEntityException",
  "errors": {
    "clients": [
      {
        "id": 1,
        "externalId": "client"
      }
    ]
  },
  "code": "E03401"
}

422

Validation Error
message

string

Error message

errors

object

Validation errors

Show child parameters
message

string

Error message

id

array

Array of error messages for id field

status

number

HTTP status code

code

string

Error code

422 RESPONSE
{
  "status": 422,
  "message": "id must be a string",
  "errors": {
    "message": "id must be a string",
    "id": [
      "id must be a string",
      "The value must not exceed 255 characters",
      "The id field is required."
    ]
  },
  "code": "E00402"
}

Bulk Create Fiat Clients

Bulk creates clients of category FIAT linked to this vault. Allowed only for Fiat Vault credentials.

Body Parameters
clients

array

required

Array of fiat client objects to create

BODY
{
  "clients": [
    {
      "id": "client_1",
      "name": "Name A",
      "identityNumber": "1092837465",
      "IBAN": "SA1234567890123456789012",
      "email": "client1@domain.com",
      "mobile": "+966500000003"
    }
  ]
}

Responses

201

Clients Created Successfully
message

string

Success message

clients

array

Array of created client details

Show child parameters
externalId

string

External client ID

name

string

Client name

id

number

Internal ID

createdAt

string

Creation timestamp

updatedAt

string

Update timestamp

status

number

HTTP status code

201 RESPONSE
{
  "message": "Clients created successfully.",
  "clients": [
    {
      "externalId": "client_1",
      "name": "Name A",
      "identityNumber": "1092837465",
      "IBAN": "SA1234567890123456789012",
      "email": "client1@domain.com",
      "mobile": "+966500000003",
      "id": 105,
      "createdAt": "20 August, 2025 11:51:20",
      "updatedAt": "20 August, 2025 11:51:20"
    }
  ],
  "status": 201
}

404

Vault Not Found
message

string

Error message

status

number

HTTP status code

errors

object

Error details

Show child parameters
message

string

Error message

code

string

Error code

404 RESPONSE
{
  "status": 404,
  "message": "Vault not found, or vault type is not allowed for creating clients",
  "errors": {
    "message": "Vault not found, or vault type is not allowed for creating clients"
  },
  "code": "E05401"
}

422

Client ID Already Exists
message

string

Error message

errors

object

Validation errors

Show child parameters
clients

array

Error message for clients field

Show child parameters
id

string

Id of the client

externalId

string

External id of the client

status

number

HTTP status code

code

string

Error code

422 RESPONSE
{
  "status": 422,
  "message": "UnprocessableEntityException",
  "errors": {
    "clients": [
      {
        "id": 1,
        "externalId": "client"
      }
    ]
  },
  "code": "E03401"
}

422

Validation Error
message

string

Error message

errors

object

Validation errors

Show child parameters
message

string

Error message

id

array

Array of error messages for id field

status

number

HTTP status code

code

string

Error code

422 RESPONSE
{
  "status": 422,
  "message": "id must be a string",
  "errors": {
    "message": "id must be a string",
    "id": [
      "id must be a string",
      "The value must not exceed 255 characters",
      "The id field is required."
    ]
  },
  "code": "E00402"
}