Create Customer - Cartevo Documentation

curl --request POST \
  --url https://api.cartevo.co/api/v1/customers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form email=john.doe@example.com \
  --form first_name=John \
  --form last_name=Doe \
  --form country=Nigeria \
  --form 'street=123 Main Street' \
  --form city=Lagos \
  --form 'state=Lagos State' \
  --form postal_code=100001 \
  --form country_iso_code=CM \
  --form 'country_phone_code=+234' \
  --form phone_number=8012345678 \
  --form identification_number=12345678901 \
  --form id_document_type=NIN \
  --form date_of_birth=1990-01-15 \
  --form id_document_front='@example-file' \
  --form id_document_back='@example-file'

{
  "success": true,
  "statusCode": 200,
  "message": "Data retrieved successfully",
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "first_name": "<string>",
    "last_name": "<string>",
    "country": "<string>",
    "email": "jsmith@example.com",
    "street": "<string>",
    "city": "<string>",
    "state": "<string>",
    "postal_code": "<string>",
    "phone_country_code": "<string>",
    "phone_number": "<string>",
    "identification_number": "<string>",
    "type": "<string>",
    "image": "<string>",
    "photo": "<string>",
    "number": "<string>",
    "date_of_birth": "2023-11-07T05:31:56Z",
    "is_active": true,
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z"
  }
}

POST

customers

curl --request POST \
  --url https://api.cartevo.co/api/v1/customers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form email=john.doe@example.com \
  --form first_name=John \
  --form last_name=Doe \
  --form country=Nigeria \
  --form 'street=123 Main Street' \
  --form city=Lagos \
  --form 'state=Lagos State' \
  --form postal_code=100001 \
  --form country_iso_code=CM \
  --form 'country_phone_code=+234' \
  --form phone_number=8012345678 \
  --form identification_number=12345678901 \
  --form id_document_type=NIN \
  --form date_of_birth=1990-01-15 \
  --form id_document_front='@example-file' \
  --form id_document_back='@example-file'

{
  "success": true,
  "statusCode": 200,
  "message": "Data retrieved successfully",
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "first_name": "<string>",
    "last_name": "<string>",
    "country": "<string>",
    "email": "jsmith@example.com",
    "street": "<string>",
    "city": "<string>",
    "state": "<string>",
    "postal_code": "<string>",
    "phone_country_code": "<string>",
    "phone_number": "<string>",
    "identification_number": "<string>",
    "type": "<string>",
    "image": "<string>",
    "photo": "<string>",
    "number": "<string>",
    "date_of_birth": "2023-11-07T05:31:56Z",
    "is_active": true,
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z"
  }
}

Overview

POST /customers registers a new customer in your company and submits their KYC documents to Cartevo’s verification provider. This endpoint accepts the documents as uploaded files (multipart/form-data). For URL-based document submission, use POST /customers/enroll instead. After creation, the customer’s kyc_status starts as PENDING and transitions to APPROVED (or REJECTED) once the upstream verification completes — typically within minutes for automated checks.

When to use it

You hold the customer’s KYC documents locally as image/PDF files (e.g. uploaded by the customer through your app).
You want a single round-trip rather than uploading documents to your own storage first.

For comparison:

Use this endpoint when…	Use `POST /customers/enroll` when…
Documents are local files in your server’s memory or disk.	Documents are already hosted at public HTTPS URLs.
You want one HTTP call.	You want JSON-only requests for easier auditing/logging.

Prerequisites

Your company has completed KYB and is in APPROVED status.
You have a government-issued ID document for the customer (front; back required for some types).

Request

Headers

Name	Required	Description
`Authorization`	Yes	`Bearer <access_token>`
`Content-Type`	Yes	`multipart/form-data`

Query parameters

Name	Type	Default	Description
`enroll`	boolean	`false`	If `true`, also enroll the customer on the upstream card-issuer immediately after creation. Otherwise enrollment happens lazily before the first card is issued.

Body fields

Field	Type	Required	Constraints
`first_name`	string	Yes	3–255 chars
`last_name`	string	Yes	3–255 chars
`email`	string	Yes	Valid email
`country`	string	Yes	2–255 chars. Full country name, e.g. `"Cameroon"`
`street`	string	Yes	2–255 chars
`city`	string	Yes	2–255 chars
`state`	string	Yes	2–255 chars
`postal_code`	string	Yes	3–255 chars
`country_iso_code`	string	Yes	ISO 3166-1 alpha-2, e.g. `CM`, `NG`
`country_phone_code`	string	Yes	Dial code with `+`, e.g. `+237`
`phone_number`	string	Yes	Local subscriber number (no country code), 3–255 chars
`identification_number`	string	Yes	1–255 chars. Format depends on `id_document_type`
`id_document_type`	string	Yes	Enum: `NIN`, `PASSPORT`, `VOTERS_CARD`, `DRIVERS_LICENSE`
`date_of_birth`	string (date)	Yes	`YYYY-MM-DD`. Customer must be 18+
`id_document_front`	file	Yes	Image (JPG/PNG) or PDF of the front of the ID document
`id_document_back`	file	No	Image or PDF of the back. Required for `DRIVERS_LICENSE` and `NIN`; not used for `PASSPORT`

File constraints

Accepted MIME types: image/jpeg, image/png, application/pdf.
Recommended resolution: ≥ 200 DPI; the entire document edge-to-edge visible; no glare; legible text.
Max file size: 10 MB per file (operational guidance — the upstream verifier may reject larger or lower-quality files).

Example

curl -X POST https://api.cartevo.co/api/v1/customers \
  -H "Authorization: Bearer $TOKEN" \
  -F "first_name=John" \
  -F "last_name=Doe" \
  -F "email=john.doe@example.com" \
  -F "country=Cameroon" \
  -F "country_iso_code=CM" \
  -F "country_phone_code=+237" \
  -F "phone_number=600000000" \
  -F "street=123 Main Street" \
  -F "city=Yaoundé" \
  -F "state=Centre" \
  -F "postal_code=00237" \
  -F "identification_number=12345678901" \
  -F "id_document_type=NIN" \
  -F "date_of_birth=1990-01-15" \
  -F "id_document_front=@/path/to/front.jpg" \
  -F "id_document_back=@/path/to/back.jpg"

Response

201 — Customer created

{
  "success": true,
  "statusCode": 201,
  "message": "Customer created successfully",
  "data": {
    "id": "8d4f2a1b-5c3e-4d7f-9a6b-2e1c8f9d0a3b",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "country": "Cameroon",
    "street": "123 Main Street",
    "city": "Yaoundé",
    "state": "Centre",
    "postal_code": "00237",
    "phone_country_code": "+237",
    "phone_number": "600000000",
    "identification_number": "12345678901",
    "type": "NIN",
    "number": "12345678901",
    "image": "https://cdn.cartevo.co/kyc/.../front.jpg",
    "photo": "https://cdn.cartevo.co/kyc/.../back.jpg",
    "date_of_birth": "1990-01-15T00:00:00.000Z",
    "is_active": true,
    "created_at": "2026-05-09T10:15:00.000Z",
    "updated_at": "2026-05-09T10:15:00.000Z"
  }
}

Field	Description
`id`	Cartevo customer ID (UUID). Use for all future calls — `POST /cards`, etc.
`type`	The `id_document_type` you submitted.
`number`	The `identification_number` you submitted (preserved as-is).
`image` / `photo`	Cartevo-hosted URLs for the front and back of the ID, available for your records.
`is_active`	`true` for newly created customers.

Note on KYC status: This response does not include a kyc_status field. KYC verification runs asynchronously after creation. Listen for the relevant webhook (customer.created is fired immediately; KYC outcome events will be added separately) or poll GET /customers/{id} to check the status.

Error responses

Status	`message` example	Trigger	Recommended action
`400`	`"first_name must be at least 3 characters"`	Field validation failure.	Fix the request.
`400`	`"Customer must be 18 or older"`	`date_of_birth` is less than 18 years ago.	The customer cannot be onboarded.
`409`	`"Customer with this email already exists"`	A customer with the same `email` exists in your company.	Fetch the existing customer instead of creating new.
`409`	`"Customer with this identification_number already exists"`	Duplicate ID number in your company.	Fetch the existing customer instead of creating new.
`413`	`"File too large"`	A document file exceeds the size limit.	Compress the file and retry.
`415`	`"Unsupported file type"`	A document is not JPG/PNG/PDF.	Convert and retry.
`422`	`"KYC document unreadable"`	The upstream verifier rejected the document quality.	Resubmit with a clearer scan.

Webhooks fired

customer.created — emitted immediately after the customer record is persisted.

POST /customers/enroll — JSON variant with hosted document URLs.
GET /customers — list your customers.
POST /cards — issue a card to an approved customer.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

enroll

string

Enroll customer on Provider

Example:

"true"

Body

multipart/form-data

string<email>

required

Example:

"john.doe@example.com"

first_name

string

required

Required string length: 3 - 255

Example:

"John"

last_name

string

required

Required string length: 3 - 255

Example:

"Doe"

country

string

required

Required string length: 2 - 255

Example:

"Nigeria"

street

string

required

Required string length: 2 - 255

Example:

"123 Main Street"

city

string

required

Required string length: 2 - 255

Example:

"Lagos"

state

string

required

Required string length: 2 - 255

Example:

"Lagos State"

postal_code

string

required

Required string length: 3 - 255

Example:

"100001"

country_iso_code

string

required

Required string length: 1 - 255

Example:

"CM"

country_phone_code

string

required

Required string length: 1 - 255

Example:

"+234"

phone_number

string

required

Required string length: 3 - 255

Example:

"8012345678"

identification_number

string

required

Required string length: 1 - 255

Example:

"12345678901"

id_document_type

enum<string>

required

Available options:

NIN,

PASSPORT,

VOTERS_CARD,

DRIVERS_LICENSE

Example:

"NIN"

date_of_birth

string<date>

required

Example:

"1990-01-15"

id_document_front

file

required

id_document_back

file

Response

Customer registered successfully

success

boolean

Example:

true

statusCode

integer

Example:

200

message

string

Example:

"Data retrieved successfully"

data

object

Show child attributes

​Overview

​When to use it

​Prerequisites

​Request

​Headers

​Query parameters

​Body fields

​File constraints

​Example

​Response

​201 — Customer created

​Error responses

​Webhooks fired

​Related

Authorizations

Query Parameters

Body

Response

Overview

When to use it

Prerequisites

Request

Headers

Query parameters

Body fields

File constraints

Example

Response

201 — Customer created

Error responses

Webhooks fired

Related