Contacts

Contacts represent any business or individual with whom you conduct transactions, either by receiving pay-ins from them or making payouts to them.

Every transaction must be associated with a contact ID, which makes creating a contact a mandatory first step.

Contacts created through the portal are assigned the party type EXTERNAL. In addition, each customer automatically has a contact with the party type OWN, which represents the customer themselves. This allows first-party deposits and payouts to be tracked more easily, as they typically require fewer compliance and operational checks.

Each contact also has a type:

• COMPANY

• INDIVIDUAL

The required data fields depend on the contact type, and some markets may have additional regulatory requirements.

Get list of contacts linked to the organization

get

Returns all EXTERNAL contacts linked to the organization.

Each contact includes a verificationStatus field that indicates its compliance approval state:

• VERIFIED – Approved by compliance

• PENDING – Verification in progress (check for messages from the compliance team)

• NOT_VERIFIED – Verification has not been started

• UNVERIFIED – Rejected by compliance

Query parameters

pageinteger · min: 1 · max: 9007199254740991OptionalDefault: 1

pageSizeinteger · max: 100OptionalDefault: 20

includeInactivebooleanOptional

searchstring · max: 255Optional

Responses

200

Default Response

application/json

get

/api/v1/contacts

HTTPcURLJavaScriptPython

GET /api/v1/contacts HTTP/1.1
Accept: */*

200

Default Response

{
  "records": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "type": "COMPANY",
      "email": "[email protected]",
      "displayName": "text",
      "verificationStatus": "VERIFIED"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 1,
    "totalItems": 1,
    "totalPages": 1
  }
}

Create a new contact

post

To create a contact, you must provide the following basic information:

Required for all contacts

• Email

• triggerVerification (boolean)

INDIVIDUAL contacts

• First name and last name

Address is optional. If you omit it, no country is required.

COMPANY contacts

• Company name

• Incorporation date

• Tax ID

• Full registered address: street, postal code, city or town, country

Verification process

The triggerVerification flag controls whether an email is sent to the contact with a link to our KYB/KYC onboarding tool.

When enabled, the contact will be asked to provide:

• Additional personal or business details

• Required documents

• Market-specific information

We strongly recommend setting triggerVerification to true to streamline the compliance approval process. If this flag is not enabled, our compliance team may need to request information manually, which can cause delays.

Mandatory verification for certain countries

For INDIVIDUAL contacts residing in the following countries:

• Kenya

• Zambia

• South Africa

• Nigeria

The triggerVerification flag must be set to true. This is required to collect additional personal data needed for on-ramp operations in these regions.

Required scopes

This endpoint requires the following scopes:

• : Allows managing the organization's contact book.

Authorizations

every

OAuth2authorizationCodeRequired

Authorization URL: Token URL:

Body

application/json

or

Responses

201

Default Response

application/json

post

/api/v1/contacts

HTTPcURLJavaScriptPython

POST /api/v1/contacts HTTP/1.1
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 309

{
  "email": "[email protected]",
  "description": "text",
  "triggerVerification": true,
  "companyName": "text",
  "registrationNumber": "text",
  "incorporationDate": "2026-04-03",
  "taxId": "text",
  "type": "COMPANY",
  "address": {
    "street": "text",
    "street2": "text",
    "postalCode": "text",
    "city": "text",
    "stateOrProvince": "text",
    "country": "text"
  }
}

201

Default Response

{
  "success": true
}

Get list of contacts linked to the organization (internal)

get

Query parameters

pageinteger · min: 1 · max: 9007199254740991OptionalDefault: 1

pageSizeinteger · max: 100OptionalDefault: 20

includeInactivebooleanOptional

searchstring · max: 255Optional

Responses

200

Default Response

application/json

get

/api/v1/internal/contacts

HTTPcURLJavaScriptPython

GET /api/v1/internal/contacts HTTP/1.1
Accept: */*

200

Default Response

{
  "records": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "type": "COMPANY",
      "email": "[email protected]",
      "displayName": "text",
      "verificationStatus": "VERIFIED",
      "identityType": "OWN",
      "deactivated": true
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 1,
    "totalItems": 1,
    "totalPages": 1
  }
}

Create a new contact (internal)

post

Required scopes

This endpoint requires the following scopes:

• : Allows managing the organization's contact book.

Authorizations

every

OAuth2authorizationCodeRequired

Authorization URL: Token URL:

Body

application/json

or

Responses

201

Default Response

application/json

post

/api/v1/internal/contacts

HTTPcURLJavaScriptPython

POST /api/v1/internal/contacts HTTP/1.1
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 309

{
  "email": "[email protected]",
  "description": "text",
  "triggerVerification": true,
  "companyName": "text",
  "registrationNumber": "text",
  "incorporationDate": "2026-04-03",
  "taxId": "text",
  "type": "COMPANY",
  "address": {
    "street": "text",
    "street2": "text",
    "postalCode": "text",
    "city": "text",
    "stateOrProvince": "text",
    "country": "text"
  }
}

201

Default Response

{
  "success": true
}

Get a contact by ID (internal)

get

Path parameters

contactIdstring · uuidRequiredPattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Responses

200

Default Response

application/json

idstring · uuidRequiredPattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

typestring · enumRequiredPossible values:

verificationStatusstring · enumRequiredPossible values:

emailstring · emailRequiredPattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$

displayNameany ofRequired

stringOptional

or

undefined · enum · nullableOptionalPossible values:

descriptionany ofRequired

stringOptional

or

undefined · enum · nullableOptionalPossible values:

dateOfBirthany ofOptional

stringOptional

or

undefined · enum · nullableOptionalPossible values:

registrationNumberany ofOptional

stringOptional

or

undefined · enum · nullableOptionalPossible values:

addressany ofOptional

or

undefined · enum · nullableOptionalPossible values:

deactivatedbooleanRequired

incorporationDateany ofOptional

stringOptional

or

undefined · enum · nullableOptionalPossible values:

taxIdany ofOptional

stringOptional

or

undefined · enum · nullableOptionalPossible values:

phoneany ofOptional

stringOptional

or

undefined · enum · nullableOptionalPossible values:

idNumberany ofOptional

stringOptional

or

undefined · enum · nullableOptionalPossible values:

ninany ofOptional

stringOptional

or

undefined · enum · nullableOptionalPossible values:

bvnany ofOptional

stringOptional

or

undefined · enum · nullableOptionalPossible values:

identityTypestring · enumRequiredPossible values:

dataVerifiedbooleanRequired

404

Default Response

application/json

get

/api/v1/internal/contacts/{contactId}

HTTPcURLJavaScriptPython

GET /api/v1/internal/contacts/{contactId} HTTP/1.1
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "type": "COMPANY",
  "verificationStatus": "VERIFIED",
  "email": "[email protected]",
  "displayName": "text",
  "description": "text",
  "dateOfBirth": "text",
  "registrationNumber": "text",
  "address": {
    "street": "text",
    "street2": "text",
    "postalCode": "text",
    "city": "text",
    "stateOrProvince": "text",
    "country": "text"
  },
  "deactivated": true,
  "incorporationDate": "text",
  "taxId": "text",
  "phone": "text",
  "idNumber": "text",
  "nin": "text",
  "bvn": "text",
  "identityType": "OWN",
  "dataVerified": true
}

Get a contact by ID

get

Returns the full details of a specific contact.

The verificationStatus field indicates its compliance approval state:

• VERIFIED – Approved by compliance

• PENDING – Verification in progress (check for messages from the compliance team)

• NOT_VERIFIED – Verification has not been started

• UNVERIFIED – Rejected by compliance

Path parameters

contactIdstring · uuidRequiredPattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Responses

200

Default Response

application/json

idstring · uuidRequiredPattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

typestring · enumRequiredPossible values:

verificationStatusstring · enumRequiredPossible values:

emailstring · emailRequiredPattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$

displayNameany ofRequired

stringOptional

or

undefined · enum · nullableOptionalPossible values:

descriptionany ofRequired

stringOptional

or

undefined · enum · nullableOptionalPossible values:

dateOfBirthany ofOptional

stringOptional

or

undefined · enum · nullableOptionalPossible values:

registrationNumberany ofOptional

stringOptional

or

undefined · enum · nullableOptionalPossible values:

addressany ofOptional

or

undefined · enum · nullableOptionalPossible values:

deactivatedbooleanRequired

incorporationDateany ofOptional

stringOptional

or

undefined · enum · nullableOptionalPossible values:

taxIdany ofOptional

stringOptional

or

undefined · enum · nullableOptionalPossible values:

phoneany ofOptional

stringOptional

or

undefined · enum · nullableOptionalPossible values:

idNumberany ofOptional

stringOptional

or

undefined · enum · nullableOptionalPossible values:

ninany ofOptional

stringOptional

or

undefined · enum · nullableOptionalPossible values:

bvnany ofOptional

stringOptional

or

undefined · enum · nullableOptionalPossible values:

404

Default Response

application/json

get

/api/v1/contacts/{contactId}

HTTPcURLJavaScriptPython

GET /api/v1/contacts/{contactId} HTTP/1.1
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "type": "COMPANY",
  "verificationStatus": "VERIFIED",
  "email": "[email protected]",
  "displayName": "text",
  "description": "text",
  "dateOfBirth": "text",
  "registrationNumber": "text",
  "address": {
    "street": "text",
    "street2": "text",
    "postalCode": "text",
    "city": "text",
    "stateOrProvince": "text",
    "country": "text"
  },
  "deactivated": true,
  "incorporationDate": "text",
  "taxId": "text",
  "phone": "text",
  "idNumber": "text",
  "nin": "text",
  "bvn": "text"
}

Update a contact

patch

Automatic updates to contact details are not currently supported via the API.

If you need to change any contact information, please contact our operations team with the requested updates.

Path parameters

contactIdstring · uuidRequiredPattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Responses

501

Default Response

application/json

patch

/api/v1/contacts/{contactId}

HTTPcURLJavaScriptPython

PATCH /api/v1/contacts/{contactId} HTTP/1.1
Accept: */*

501

Default Response

{
  "message": "text"
}

Get a list of a contact's external accounts

get

Path parameters

contactIdstring · uuidRequiredPattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Query parameters

includeInactivebooleanOptional

Responses

200

Default Response

application/json

404

Default Response

application/json

get

/api/v1/contacts/{contactId}/external-accounts

HTTPcURLJavaScriptPython

GET /api/v1/contacts/{contactId}/external-accounts HTTP/1.1
Accept: */*

{
  "records": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "identityId": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "status": "ACTIVE",
      "country": "text",
      "deactivated": true,
      "paymentInstruction": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "type": "CRYPTO",
        "status": "ACTIVE",
        "asset": "text",
        "rail": "ETHEREUM",
        "paymentIdentifiers": [
          {
            "id": "text",
            "type": "BSB",
            "value": "text",
            "active": true,
            "sequenceNumber": "text",
            "amount": 1,
            "usdAmount": 1,
            "complete": true,
            "providerId": "text"
          }
        ],
        "isReadOnly": true,
        "thirdPartyDisabled": true
      }
    }
  ]
}

Create a contact's external account

post

Required scopes

This endpoint requires the following scopes:

• : Allows managing the organization's contact book.

Authorizations

every

OAuth2authorizationCodeRequired

Authorization URL: Token URL:

Path parameters

contactIdstring · uuidRequiredPattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Body

application/json

or

Responses

200

Default Response

application/json

stepUpVerificationOperationIdstring · uuidRequiredPattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

400

Default Response

application/json

404

Default Response

application/json

post

/api/v1/contacts/{contactId}/external-accounts

HTTPcURLJavaScriptPython

POST /api/v1/contacts/{contactId}/external-accounts HTTP/1.1
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 228

{
  "name": "text",
  "asset": "USDC",
  "paymentIdentifiers": [
    {
      "id": "text",
      "type": "BSB",
      "value": "text",
      "active": true,
      "sequenceNumber": "text",
      "amount": 1,
      "usdAmount": 1,
      "complete": true,
      "providerId": "text"
    }
  ],
  "type": "CRYPTO",
  "rail": "ETHEREUM"
}

{
  "stepUpVerificationOperationId": "123e4567-e89b-12d3-a456-426614174000"
}

Deactivate an external contact

post

Deactivates a contact to prevent accidental transactions in the future.

Path parameters

contactIdstring · uuidRequiredPattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Responses

200

Default Response

application/json

successbooleanRequired

403

Default Response

application/json

404

Default Response

application/json

post

/api/v1/contacts/{contactId}/deactivate

HTTPcURLJavaScriptPython

POST /api/v1/contacts/{contactId}/deactivate HTTP/1.1
Accept: */*

{
  "success": true
}

Activate an external contact

post

Reactivates a previously deactivated contact.

Path parameters

contactIdstring · uuidRequiredPattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Responses

200

Default Response

application/json

successbooleanRequired

403

Default Response

application/json

404

Default Response

application/json

post

/api/v1/contacts/{contactId}/activate

HTTPcURLJavaScriptPython

POST /api/v1/contacts/{contactId}/activate HTTP/1.1
Accept: */*

{
  "success": true
}