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": "[email protected]",
  "street": "123 Main Street",
  "city": "Lagos",
  "state": "Lagos State",
  "postal_code": "100001",
  "country_iso_code": "+234",
  "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"
}
'

{
  "success": true,
  "statusCode": 200,
  "message": "Data retrieved successfully",
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "first_name": "<string>",
    "last_name": "<string>",
    "country": "<string>",
    "email": "[email protected]",
    "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

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": "[email protected]",
  "street": "123 Main Street",
  "city": "Lagos",
  "state": "Lagos State",
  "postal_code": "100001",
  "country_iso_code": "+234",
  "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"
}
'

{
  "success": true,
  "statusCode": 200,
  "message": "Data retrieved successfully",
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "first_name": "<string>",
    "last_name": "<string>",
    "country": "<string>",
    "email": "[email protected]",
    "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"
  }
}

Description

Register a new customer using ID document URLs instead of file uploads. This endpoint enrolls the customer on the provider platform, making them eligible for card issuance.

Request

Endpoint

POST /api/v1/customers/enroll

Headers

Authorization: Bearer {access_token}
Content-Type: application/json

Request Body

{
  "first_name": "John",
  "last_name": "Doe",
  "country": "Nigeria",
  "email": "[email protected]",
  "street": "123 Main Street",
  "city": "Lagos",
  "state": "Lagos State",
  "postal_code": "100001",
  "country_iso_code": "+234",
  "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"
}

Parameters

Parameter	Type	Required	Description
`first_name`	string	Yes	Customer first name (3-255 characters)
`last_name`	string	Yes	Customer last name (3-255 characters)
`country`	string	Yes	Customer country (2-255 characters)
`email`	string	Yes	Customer email address (valid email format)
`street`	string	Yes	Street address (2-255 characters)
`city`	string	Yes	City (2-255 characters)
`state`	string	Yes	State or province (2-255 characters)
`postal_code`	string	Yes	Postal code (3-255 characters)
`country_iso_code`	string	Yes	Country ISO code (e.g., “+234”)
`country_phone_code`	string	Yes	Country phone code (e.g., “+234”)
`phone_number`	string	Yes	Phone number (3-255 characters)
`identification_number`	string	Yes	Identification number (1-255 characters)
`id_document_front_url`	string	Yes	URL to the front of the ID document
`id_document_back_url`	string	Yes	URL to the back of the ID document
`id_document_type`	string	Yes	Type of ID document. Must be one of: `NIN`, `PASSPORT`, `VOTERS_CARD`, `DRIVERS_LICENSE`
`date_of_birth`	string	Yes	Date of birth in format YYYY-MM-DD

Response

Success Response (201)

{
  "success": true,
  "statusCode": 201,
  "message": "Customer enrolled successfully",
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "first_name": "John",
    "last_name": "Doe",
    "country": "Nigeria",
    "email": "[email protected]",
    "street": "123 Main Street",
    "city": "Lagos",
    "state": "Lagos State",
    "postal_code": "100001",
    "phone_country_code": "+234",
    "phone_number": "8012345678",
    "identification_number": "12345678901",
    "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"
  }
}

Error Response (409)

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

Example

cURL

curl -X POST "https://api.cartevo.co/api/v1/customers/enroll" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "country": "Nigeria",
    "email": "[email protected]",
    "street": "123 Main Street",
    "city": "Lagos",
    "state": "Lagos State",
    "postal_code": "100001",
    "country_iso_code": "+234",
    "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"
  }'

Notes

The customer will be automatically enrolled on the provider platform upon successful registration
Both id_document_front_url and id_document_back_url must be publicly accessible URLs
The email and identification number must be unique within your company
Once enrolled, the customer becomes eligible for card issuance

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:

"[email protected]"

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:

"+234"

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

data.id

string<uuid>

data.first_name

string

data.last_name

string

data.country

string

data.email

string<email>

data.street

string

data.city

string

data.state

string

data.postal_code

string

data.phone_country_code

string

data.phone_number

string

data.identification_number

string

data.type

string

data.image

string | null

data.photo

string | null

data.number

string

data.date_of_birth

string<date-time>

data.is_active

boolean

data.created_at

string<date-time>

data.updated_at

string<date-time>

Customer Transactions Payment guide lines

⌘I

API documentation

Auth

Cards

Customers

Payment Collection

Webhook

Description

Request

Endpoint

Headers

Request Body

Parameters

Response

Success Response (201)

Error Response (409)

Example

cURL

Notes

Authorizations

Body

Response

API documentation

Auth

Cards

Customers

Payment Collection

Webhook

​Description

​Request

​Endpoint

​Headers

​Request Body

​Parameters

​Response

​Success Response (201)

​Error Response (409)

​Example

​cURL

​Notes

Authorizations

Body

Response

Description

Request

Endpoint

Headers

Request Body

Parameters

Response

Success Response (201)

Error Response (409)

Example

cURL

Notes