User Management

Users must be created before they can transact on the platform. A user can be either an individual (natural person) or a business (legal entity), and can act as a sender (payins / collections) or a recipient (payouts).

Note

After creating a user, you will typically need to submit KYC (for individuals) or KYB (for businesses) before the user can process transactions. See KYC & KYB for details.

Endpoints Overview

POST /v2/users/individual Create an individual user

GET /v2/users/individuals List individual users

POST /v2/users/business Create a business user

GET /v2/users/business List business users

Create Individual User

Register a new individual (natural person) in the system. The returned userId is used in all subsequent API calls for this user, including KYC submission, order creation, and status retrieval.

POST /v2/users/individual

Request Body

Parameter	Type	Required	Description
email	string	Required	Unique email address for the user
firstName	string	Required	First name
lastName	string	Required	Last name
date	string	Required	Date of birth in `DD-MM-YYYY` format
country	string	Required	Citizenship country (ISO 3166-1 alpha-2, e.g. `US`)
phone	string	Required	Phone number
address	object	Required	Address object (see below)
gender	string	Optional	Gender of the user
phoneCode	string	Optional	International phone code prefix (e.g. `+1`)

Address Object

Field	Type	Required	Description
city	string	Required	City
postalCode	string	Required	Postal / ZIP code
state	string	Required	State or province
street	string	Required	Street address

Request Example

JSON

POST /v2/users/individual
Content-Type: application/json
Authorization: Basic <base64(username:password)>

{
  "email": "john@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "date": "20-01-2002",
  "country": "US",
  "phone": "123412340",
  "address": {
    "city": "Springfield",
    "postalCode": "62701",
    "state": "IL",
    "street": "123 Main St"
  },
  "gender": "male",
  "phoneCode": "+1"
}

Response

201 Created

JSON

{
  "userId": "UX-241125161812424"
}

Error Responses

HTTP Status	Error Code	Description
`400`	`MISSING_ARGUMENTS`	One or more required fields are missing from the request body
`400`	`INVALID_REQUEST`	Invalid field values (e.g. unsupported country code, malformed email)
`400`	`DUPLICATE_REQUEST`	A user with this email already exists in the system
`409`	`CONFLICT`	Email is already registered as a different user type (e.g. business)

List Individual Users

Retrieve a paginated list of individual users. You can filter by email or userId to look up a specific user.

GET /v2/users/individuals

Query Parameters

Parameter	Type	Required	Description
email	string	Optional	Filter by user email address
userId	string	Optional	Filter by user ID (e.g. `UX-241125161812424`)

Request Example

HTTP

GET /v2/users/individuals?email=john@example.com
Authorization: Basic <base64(username:password)>

Response

200 OK

JSON

{
  "pages": 10,
  "total": 20,
  "users": [
    {
      "userId": "UX-241125161812424",
      "email": "john@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "gender": "male",
      "country": "US",
      "dob": "2002-01-20T00:00:00.000Z",
      "phone": "123412340",
      "status": "trial_user",
      "address": {
        "city": "Springfield",
        "postalCode": "62701",
        "state": "IL",
        "street": "123 Main St"
      }
    }
  ]
}

Response Fields

Field	Type	Description
pages	integer	Total number of pages
total	integer	Total number of users matching the query
users[]	array	Array of user objects
users[].userId	string	Unique user identifier
users[].email	string	User email address
users[].firstName	string	First name
users[].lastName	string	Last name
users[].country	string	ISO 3166-1 alpha-2 country code
users[].dob	string	Date of birth (ISO 8601)
users[].phone	string	Phone number
users[].status	string	Current user status
users[].address	object	Address object with `city`, `postalCode`, `state`, `street`

Create Business User

Register a new business (legal entity) in the system. Business users can act as senders or recipients in payin and payout transactions.

POST /v2/users/business

Request Body

Parameter	Type	Required	Description
email	string	Required	Business email address
businessName	string	Required	Company legal name
country	string	Required	Country of registration (ISO 3166-1 alpha-2)
regNo	string	Required	Company registration number
phone	string	Required	Contact phone number
address	object	Required	Address object with `city`, `postalCode`, `state`, `street`
date	string	Optional	Incorporation date in `DD-MM-YYYY` format
phoneCode	string	Optional	International phone code prefix (e.g. `+1`)

Request Example

JSON

POST /v2/users/business
Content-Type: application/json
Authorization: Basic <base64(username:password)>

{
  "email": "finance@acmecorp.com",
  "businessName": "Acme Corporation",
  "country": "US",
  "regNo": "REG-123456789",
  "phone": "5551234567",
  "address": {
    "city": "New York",
    "postalCode": "10001",
    "state": "NY",
    "street": "456 Broadway"
  },
  "date": "15-03-2010",
  "phoneCode": "+1"
}

Response

201 Created

JSON

{
  "userId": "UX-12345678901"
}

List Business Users

Retrieve a paginated list of business users. Supports the same query parameters and returns the same response structure as the individual users listing endpoint.

GET /v2/users/business

Query Parameters

Parameter	Type	Required	Description
email	string	Optional	Filter by business email address
userId	string	Optional	Filter by user ID

Request Example

HTTP

GET /v2/users/business?email=finance@acmecorp.com
Authorization: Basic <base64(username:password)>

Response

200 OK

JSON

{
  "pages": 5,
  "total": 12,
  "users": [
    {
      "userId": "UX-12345678901",
      "email": "finance@acmecorp.com",
      "businessName": "Acme Corporation",
      "country": "US",
      "regNo": "REG-123456789",
      "phone": "5551234567",
      "status": "trial_user",
      "address": {
        "city": "New York",
        "postalCode": "10001",
        "state": "NY",
        "street": "456 Broadway"
      }
    }
  ]
}

Next Steps

After creating a user, proceed with identity verification before the user can transact:

KYC & KYB

Submit identity verification for individuals (KYC) or businesses (KYB) to enable transactions.

View KYC & KYB docs

Orders & Payments

Create payin and payout orders once the user has passed verification.

View Orders docs