Enroll Customer

Enroll new customer

curl --request POST \
  --url https://api.cartevo.co/api/v1/customers/enroll \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "first_name": "John",
  "last_name": "Doe",
  "country": "Nigeria",
  "email": "john.doe@example.com",
  "street": "123 Main Street",
  "city": "Lagos",
  "state": "Lagos State",
  "postal_code": "100001",
  "country_iso_code": "CM",
  "country_phone_code": "+234",
  "phone_number": "8012345678",
  "identification_number": "12345678901",
  "id_document_front_url": "https://example.com/documents/front.jpg",
  "id_document_back_url": "https://example.com/documents/back.jpg",
  "id_document_type": "NIN",
  "date_of_birth": "1990-01-15"
}
'

import requests

url = "https://api.cartevo.co/api/v1/customers/enroll"

payload = {
    "first_name": "John",
    "last_name": "Doe",
    "country": "Nigeria",
    "email": "john.doe@example.com",
    "street": "123 Main Street",
    "city": "Lagos",
    "state": "Lagos State",
    "postal_code": "100001",
    "country_iso_code": "CM",
    "country_phone_code": "+234",
    "phone_number": "8012345678",
    "identification_number": "12345678901",
    "id_document_front_url": "https://example.com/documents/front.jpg",
    "id_document_back_url": "https://example.com/documents/back.jpg",
    "id_document_type": "NIN",
    "date_of_birth": "1990-01-15"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    first_name: 'John',
    last_name: 'Doe',
    country: 'Nigeria',
    email: 'john.doe@example.com',
    street: '123 Main Street',
    city: 'Lagos',
    state: 'Lagos State',
    postal_code: '100001',
    country_iso_code: 'CM',
    country_phone_code: '+234',
    phone_number: '8012345678',
    identification_number: '12345678901',
    id_document_front_url: 'https://example.com/documents/front.jpg',
    id_document_back_url: 'https://example.com/documents/back.jpg',
    id_document_type: 'NIN',
    date_of_birth: '1990-01-15'
  })
};

fetch('https://api.cartevo.co/api/v1/customers/enroll', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cartevo.co/api/v1/customers/enroll",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'first_name' => 'John',
    'last_name' => 'Doe',
    'country' => 'Nigeria',
    'email' => 'john.doe@example.com',
    'street' => '123 Main Street',
    'city' => 'Lagos',
    'state' => 'Lagos State',
    'postal_code' => '100001',
    'country_iso_code' => 'CM',
    'country_phone_code' => '+234',
    'phone_number' => '8012345678',
    'identification_number' => '12345678901',
    'id_document_front_url' => 'https://example.com/documents/front.jpg',
    'id_document_back_url' => 'https://example.com/documents/back.jpg',
    'id_document_type' => 'NIN',
    'date_of_birth' => '1990-01-15'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cartevo.co/api/v1/customers/enroll"

	payload := strings.NewReader("{\n  \"first_name\": \"John\",\n  \"last_name\": \"Doe\",\n  \"country\": \"Nigeria\",\n  \"email\": \"john.doe@example.com\",\n  \"street\": \"123 Main Street\",\n  \"city\": \"Lagos\",\n  \"state\": \"Lagos State\",\n  \"postal_code\": \"100001\",\n  \"country_iso_code\": \"CM\",\n  \"country_phone_code\": \"+234\",\n  \"phone_number\": \"8012345678\",\n  \"identification_number\": \"12345678901\",\n  \"id_document_front_url\": \"https://example.com/documents/front.jpg\",\n  \"id_document_back_url\": \"https://example.com/documents/back.jpg\",\n  \"id_document_type\": \"NIN\",\n  \"date_of_birth\": \"1990-01-15\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.cartevo.co/api/v1/customers/enroll")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"first_name\": \"John\",\n  \"last_name\": \"Doe\",\n  \"country\": \"Nigeria\",\n  \"email\": \"john.doe@example.com\",\n  \"street\": \"123 Main Street\",\n  \"city\": \"Lagos\",\n  \"state\": \"Lagos State\",\n  \"postal_code\": \"100001\",\n  \"country_iso_code\": \"CM\",\n  \"country_phone_code\": \"+234\",\n  \"phone_number\": \"8012345678\",\n  \"identification_number\": \"12345678901\",\n  \"id_document_front_url\": \"https://example.com/documents/front.jpg\",\n  \"id_document_back_url\": \"https://example.com/documents/back.jpg\",\n  \"id_document_type\": \"NIN\",\n  \"date_of_birth\": \"1990-01-15\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cartevo.co/api/v1/customers/enroll")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"first_name\": \"John\",\n  \"last_name\": \"Doe\",\n  \"country\": \"Nigeria\",\n  \"email\": \"john.doe@example.com\",\n  \"street\": \"123 Main Street\",\n  \"city\": \"Lagos\",\n  \"state\": \"Lagos State\",\n  \"postal_code\": \"100001\",\n  \"country_iso_code\": \"CM\",\n  \"country_phone_code\": \"+234\",\n  \"phone_number\": \"8012345678\",\n  \"identification_number\": \"12345678901\",\n  \"id_document_front_url\": \"https://example.com/documents/front.jpg\",\n  \"id_document_back_url\": \"https://example.com/documents/back.jpg\",\n  \"id_document_type\": \"NIN\",\n  \"date_of_birth\": \"1990-01-15\"\n}"

response = http.request(request)
puts response.read_body

{
  "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"
  }
}

{
  "success": false,
  "statusCode": 409,
  "message": "Customer with this email or ID already exists",
  "error": "Conflict"
}

POST

customers

enroll

Enroll new customer

curl --request POST \
  --url https://api.cartevo.co/api/v1/customers/enroll \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "first_name": "John",
  "last_name": "Doe",
  "country": "Nigeria",
  "email": "john.doe@example.com",
  "street": "123 Main Street",
  "city": "Lagos",
  "state": "Lagos State",
  "postal_code": "100001",
  "country_iso_code": "CM",
  "country_phone_code": "+234",
  "phone_number": "8012345678",
  "identification_number": "12345678901",
  "id_document_front_url": "https://example.com/documents/front.jpg",
  "id_document_back_url": "https://example.com/documents/back.jpg",
  "id_document_type": "NIN",
  "date_of_birth": "1990-01-15"
}
'

import requests

url = "https://api.cartevo.co/api/v1/customers/enroll"

payload = {
    "first_name": "John",
    "last_name": "Doe",
    "country": "Nigeria",
    "email": "john.doe@example.com",
    "street": "123 Main Street",
    "city": "Lagos",
    "state": "Lagos State",
    "postal_code": "100001",
    "country_iso_code": "CM",
    "country_phone_code": "+234",
    "phone_number": "8012345678",
    "identification_number": "12345678901",
    "id_document_front_url": "https://example.com/documents/front.jpg",
    "id_document_back_url": "https://example.com/documents/back.jpg",
    "id_document_type": "NIN",
    "date_of_birth": "1990-01-15"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    first_name: 'John',
    last_name: 'Doe',
    country: 'Nigeria',
    email: 'john.doe@example.com',
    street: '123 Main Street',
    city: 'Lagos',
    state: 'Lagos State',
    postal_code: '100001',
    country_iso_code: 'CM',
    country_phone_code: '+234',
    phone_number: '8012345678',
    identification_number: '12345678901',
    id_document_front_url: 'https://example.com/documents/front.jpg',
    id_document_back_url: 'https://example.com/documents/back.jpg',
    id_document_type: 'NIN',
    date_of_birth: '1990-01-15'
  })
};

fetch('https://api.cartevo.co/api/v1/customers/enroll', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cartevo.co/api/v1/customers/enroll",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'first_name' => 'John',
    'last_name' => 'Doe',
    'country' => 'Nigeria',
    'email' => 'john.doe@example.com',
    'street' => '123 Main Street',
    'city' => 'Lagos',
    'state' => 'Lagos State',
    'postal_code' => '100001',
    'country_iso_code' => 'CM',
    'country_phone_code' => '+234',
    'phone_number' => '8012345678',
    'identification_number' => '12345678901',
    'id_document_front_url' => 'https://example.com/documents/front.jpg',
    'id_document_back_url' => 'https://example.com/documents/back.jpg',
    'id_document_type' => 'NIN',
    'date_of_birth' => '1990-01-15'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cartevo.co/api/v1/customers/enroll"

	payload := strings.NewReader("{\n  \"first_name\": \"John\",\n  \"last_name\": \"Doe\",\n  \"country\": \"Nigeria\",\n  \"email\": \"john.doe@example.com\",\n  \"street\": \"123 Main Street\",\n  \"city\": \"Lagos\",\n  \"state\": \"Lagos State\",\n  \"postal_code\": \"100001\",\n  \"country_iso_code\": \"CM\",\n  \"country_phone_code\": \"+234\",\n  \"phone_number\": \"8012345678\",\n  \"identification_number\": \"12345678901\",\n  \"id_document_front_url\": \"https://example.com/documents/front.jpg\",\n  \"id_document_back_url\": \"https://example.com/documents/back.jpg\",\n  \"id_document_type\": \"NIN\",\n  \"date_of_birth\": \"1990-01-15\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.cartevo.co/api/v1/customers/enroll")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"first_name\": \"John\",\n  \"last_name\": \"Doe\",\n  \"country\": \"Nigeria\",\n  \"email\": \"john.doe@example.com\",\n  \"street\": \"123 Main Street\",\n  \"city\": \"Lagos\",\n  \"state\": \"Lagos State\",\n  \"postal_code\": \"100001\",\n  \"country_iso_code\": \"CM\",\n  \"country_phone_code\": \"+234\",\n  \"phone_number\": \"8012345678\",\n  \"identification_number\": \"12345678901\",\n  \"id_document_front_url\": \"https://example.com/documents/front.jpg\",\n  \"id_document_back_url\": \"https://example.com/documents/back.jpg\",\n  \"id_document_type\": \"NIN\",\n  \"date_of_birth\": \"1990-01-15\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cartevo.co/api/v1/customers/enroll")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"first_name\": \"John\",\n  \"last_name\": \"Doe\",\n  \"country\": \"Nigeria\",\n  \"email\": \"john.doe@example.com\",\n  \"street\": \"123 Main Street\",\n  \"city\": \"Lagos\",\n  \"state\": \"Lagos State\",\n  \"postal_code\": \"100001\",\n  \"country_iso_code\": \"CM\",\n  \"country_phone_code\": \"+234\",\n  \"phone_number\": \"8012345678\",\n  \"identification_number\": \"12345678901\",\n  \"id_document_front_url\": \"https://example.com/documents/front.jpg\",\n  \"id_document_back_url\": \"https://example.com/documents/back.jpg\",\n  \"id_document_type\": \"NIN\",\n  \"date_of_birth\": \"1990-01-15\"\n}"

response = http.request(request)
puts response.read_body

{
  "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"
  }
}

{
  "success": false,
  "statusCode": 409,
  "message": "Customer with this email or ID already exists",
  "error": "Conflict"
}

Overview

POST /customers/enroll registers a new customer in your company using publicly accessible URLs to the KYC documents instead of uploading the files directly. This is useful when documents are already hosted in your own object storage (S3, GCS, etc.). For local file uploads, use POST /customers instead. The customer is enrolled with the upstream card issuer in the same call, so they become eligible for card issuance immediately on success (subject to KYC outcome).

When to use it

Use this endpoint when…	Use `POST /customers` when…
Documents are already hosted at public HTTPS URLs (S3, GCS, etc.).	Documents are local files in your server.
You prefer JSON-only requests (easier to log, audit, and replay).	You want a single round-trip without first uploading.

Prerequisites

Your company has completed KYB and is in APPROVED status.
The document URLs must be reachable over HTTPS by the upstream verifier (which may fetch them more than once).

Request

Headers

Name	Required	Description
`Authorization`	Yes	`Bearer <access_token>`
`Content-Type`	Yes	`application/json`

Body fields

Field	Type	Required	Constraints / notes
`first_name`	string	Yes	3–255 chars
`last_name`	string	Yes	3–255 chars
`email`	string	Yes	Valid email
`country`	string	Yes	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)
`identification_number`	string	Yes	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_url`	string (URL)	Yes	Publicly fetchable HTTPS URL to the front of the ID
`id_document_back_url`	string (URL)	Yes	Publicly fetchable HTTPS URL to the back of the ID

URL requirements

HTTPS only. Plain HTTP URLs are rejected.
Reachable by the upstream verifier. If the URL is gated (Basic Auth, IP allowlist, signed URL), the verifier will fail to fetch it.
Stable. The verifier may fetch the URL multiple times during processing. Signed URLs with very short expiry windows are not recommended; use a TTL of at least 30 minutes.
Direct file URLs, not landing pages. The response should be the image/PDF bytes with a correct Content-Type header.

Example

{
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "country": "Cameroon",
  "country_iso_code": "CM",
  "country_phone_code": "+237",
  "phone_number": "600000000",
  "street": "123 Main Street",
  "city": "Yaoundé",
  "state": "Centre",
  "postal_code": "00237",
  "identification_number": "12345678901",
  "id_document_type": "NIN",
  "date_of_birth": "1990-01-15",
  "id_document_front_url": "https://cdn.your-app.com/kyc/abc123/front.jpg",
  "id_document_back_url": "https://cdn.your-app.com/kyc/abc123/back.jpg"
}

Response

201 — Customer enrolled

{
  "success": true,
  "statusCode": 201,
  "message": "Customer enrolled 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.your-app.com/kyc/abc123/front.jpg",
    "photo": "https://cdn.your-app.com/kyc/abc123/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"
  }
}

See the POST /customers field reference for descriptions — the response shape is identical.

Error responses

Status	`message` example	Trigger
`400`	`"id_document_front_url must be HTTPS"`	A document URL uses `http://` instead of `https://`.
`400`	`"Customer must be 18 or older"`	`date_of_birth` is less than 18 years ago.
`409`	`"Customer with this email or ID already exists"`	Duplicate `email` or `identification_number` in your company.
`422`	`"Could not fetch id_document_front_url"`	The verifier couldn’t reach or download the URL.
`422`	`"KYC document unreadable"`	The verifier rejected the document quality.

Webhooks fired

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

POST /customers — file-upload variant (multipart/form-data).
GET /customers/{id} — check the resulting customer record.

Authorizations

Authorization

string

header

required

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

Body

application/json

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"

string<email>

required

Example:

"john.doe@example.com"

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_front_url

string

required

Example:

"https://example.com/documents/front.jpg"

id_document_back_url

string

required

Example:

"https://example.com/documents/back.jpg"

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"

Response

Customer enrolled successfully

success

boolean

Example:

true

statusCode

integer

Example:

200

message

string

Example:

"Data retrieved successfully"

data

object

Show child attributes

List Customers Get Customer by ID

API documentation

Auth

Cards

Customers

Wallets

Payment Collection

Webhook

Overview

When to use it

Prerequisites

Request

Headers

Body fields

URL requirements

Example

Response

201 — Customer enrolled

Error responses

Webhooks fired

Authorizations

Body

Response

​Overview

​When to use it

​Prerequisites

​Request

​Headers

​Body fields

​URL requirements

​Example

​Response

​201 — Customer enrolled

​Error responses

​Webhooks fired

​Related

Authorizations

Body

Response

Overview

When to use it

Prerequisites

Request

Headers

Body fields

URL requirements

Example

Response

201 — Customer enrolled

Error responses

Webhooks fired

Related