Onboarding
Customer API Documentation
Base URL
/api/v1/customersCreate Customer
/Request
Authorization: Bearer <token>Content-Type: application/jsonX-Correlation-ID: <optional trace id>{
"userId": "uuid",
"avatar": "https://…", // optional
"countryId": "uuid", // optional
"nationalityId": "uuid" // optional
}Response
{
"id": "uuid",
"user": { "id": "uuid" } | null,
"customerRef": "CXX12345678",
"avatar": "https://…" | null,
"countryId": "uuid" | null,
"country": { "id":"uuid","name":"…","code":"…"} | null,
"nationalityId": "uuid" | null,
"nationality": { "id":"uuid","name":"…","code":"…"} | null,
"kycStatus": "PENDING" | "APPROVED" | "REJECTED",
"createdAt": "2025-07-23T13:24:00.000Z",
"updatedAt": "2025-07-23T13:24:00.000Z"
}Get Customer by ID
/:idResponse
Same payload as Create Customer response.
Update Customer
/:idRequest
{
"userId": "uuid", // optional
"avatar": "https://…", // optional
"countryId": "uuid", // optional
"nationalityId": "uuid" // optional
}Response
Same payload as Create Customer response, with updated timestamps.
Delete Customer
/:idResponse
Restore Customer
/:id/restoreResponse
Same payload as Create Customer response.
List Customers
/Query Parameters
page (number, default 1)limit (number, default 20)customerRefContains (string, optional)kycStatus (string, optional)countryId (uuid, optional)nationalityId (uuid, optional)Response
[
{ /* customer DTO */ },
{ /* ... */ }
]X-Pagination-Total: <total>
X-Pagination-Page: <page>
X-Pagination-Limit: <limit>
X-Pagination-Total-Pages: <totalPages>Onboard Customer
/onboardRequest
{
"userId": "uuid",
"phoneNumber": "+123456789",
"strategyId": "uuid",
"secretHash": "…",
"avatar": "https://…", // optional
"countryId": "uuid", // optional
"nationalityId": "uuid", // optional
"config": { /* arbitrary key/value */ } // optional
}Response
{
"customerId": "uuid",
"phoneNumberId": "uuid",
"authenticatorId": "uuid"
}Error Responses
{
"errorCode": "VALIDATION_ERROR",
"message": "...",
"details": { "field": "…" }
}{
"errorCode": "UNAUTHORIZED",
"message": "Authentication token is invalid or missing."
}{
"errorCode": "DUPLICATE_ENTITY",
"message": "Customer with reference '…' already exists."
}{
"errorCode": "INTERNAL_SERVER_ERROR",
"message": "…"
}Notes
customerRef is read-only and always generated by the server.X-Correlation-ID for request tracing.phoneNumber in E.164 format on the client.Modified at 2025-07-23 11:19:21