Create Customer

Creates a new customer (individual or business). This is the first step of the onboarding flow - use the
returned id for every later call.

Required Fields

Field	Type	Description	Constraints
`type`	`string`	`individual` or `business`	Pattern: `^(individual\|business)$`
`email`	`string (email)`	Unique email address	Max: 256 - Pattern: `^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$`
`phoneCode`	`string`	International dialling code (e.g. `+44`)	Must be a valid dialling code
`phoneNumber`	`string`	Phone number without the dialling code, unique per customer	Must be valid for the country
`countryOfResidencyIsoTwo`	`string`	2-letter ISO-3166 country code	Must be a supported country
`countryOfOriginIsoTwo`	`string`	2-letter ISO-3166 country code	Must be a supported country

Required when type is individual

Field	Type	Description	Constraints
`firstName`	`string`	Given name	Max: 100 - letters, spaces, `'`, `-`, `.` only
`lastName`	`string`	Family name	Max: 100 - same pattern
`dateOfBirth`	`string (date)`	`YYYY-MM-DD`	Minimum age 18
`gender`	`string`	e.g. `male`, `female`, `other`	-

Required when type is business

Field	Type	Description	Constraints
`businessName`	`string`	Legal business name	Max: 250

Optional Fields

Field	Type	Description	Constraints
`externalReference`	`string`	Your own customer id, echoed back on Get / List	Max: 200

Response Fields (inside data)

Field	Type	Description
`id`	`string (uuid)`	Unique customer identifier
`type`	`string`	`individual` or `business`
`firstName` / `lastName`	`string, nullable`	Individual customer name
`email`	`string`	Customer email
`phoneCode` / `phoneNumber`	`string`	Customer phone
`status`	`integer`	Record status - `1` = Active
`countryIsoTwo`	`string`	The person's original country / nationality.
`countryOfResidencyIsoTwo`	`string`	The country where the person currently lives.
`countryOfOriginIsoTwo`	`string`	The person's original country / nationality.
`businessName`	`string, nullable`	Business customer name
`createdAt`	`string (date-time)`	Creation timestamp (UTC)

Returns 200 OK. A duplicate email or phone number returns 422 VALIDATION_ERROR.

curl --location '/api/v1/customers' \ --header 'X-API-Key;' \ --header 'X-Signature;' \ --header 'X-Timestamp;' \ --header 'X-Nonce;' \ --header 'X-Body-Hash;' \ --header 'X-Idempotency-Key;' \ --header 'Content-Type: application/json' \ --data-raw '{ "type": "individual", "firstName": "Jane", "lastName": "Doe", "email": "jane.doe@example.com", "phoneCode": "+44", "phoneNumber": "7700900000", "dateOfBirth": "1990-06-15", "gender": "female", "countryOfOriginIsoTwo": "GB", "countryOfResidencyIsoTwo": "GB", "externalReference": "usr_12345" }'

{ "data": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "individual", "firstName": "Jane", "lastName": "Doe", "email": "jane.doe@example.com", "phoneCode": "+44", "phoneNumber": "7700900000", "country": "United Kingdom", "countryOrigin": "United Kingdom", "countryOfResidency": "India", "status": 1, "businessName": null, "createdAt": "2026-01-15T10:30:00Z" }, "requestId": "9f2c4b6e8a1d4f0cb7e35a91d2c46f80", "timestamp": "2026-08-22T10:30:00.123Z" }

Request

Responses