Skip to main content
POST
/
v1
/
loans
/
customers
/
enroll
Enroll Customer
curl --request POST \
  --url https://carbonapistagingsecure.getcarbon.co/baas/api/v1/loans/customers/enroll \
  --header 'Content-Type: application/json' \
  --header 'apikey: <api-key>' \
  --header 'x-carbon-key: <x-carbon-key>' \
  --data '
{
  "customer_id": "1732ca47-42b2-4990-a65d-c369e934eed3"
}
'
{
  "status": "success",
  "data": {
    "customer_id": "1732ca47-42b2-4990-a65d-c369e934eed3",
    "account_identifier": "PC_abc123xyz456",
    "customer_type": "INDIVIDUAL",
    "kyc_status": "PENDING",
    "enrolled_at": "2024-05-15T10:00:00Z"
  }
}

​
Overview

Registers an existing customer with the Carbon lending engine. The customer must already exist (created via POST /v1/customers) and must have a BVN and an active wallet account. This call is idempotent — sending the same customer_id twice returns the existing enrollment with 200 OK instead of creating a duplicate.

​
Request

Method: POST
URL: /v1/loans/customers/enroll

​
Parameters

NameInTypeRequiredDescription
x-carbon-keyHeaderstringYesAPI key for authentication.

​
Request Body

{
  "customer_id": "1732ca47-42b2-4990-a65d-c369e934eed3"
}
FieldTypeRequiredDescription
customer_idstringYesUUID of the customer from POST /v1/customers

​
Response

​
201 — New Enrollment

{
  "status": "success",
  "message": "Customer enrolled for lending",
  "data": {
    "customer_id": "1732ca47-42b2-4990-a65d-c369e934eed3",
    "customer_type": "INDIVIDUAL",
    "kyc_status": "PENDING",
    "enrolled_at": "2025-01-15T10:05:00.000Z"
  }
}

​
200 — Already Enrolled

{
  "status": "success",
  "message": "Customer already enrolled",
  "data": {
    "customer_id": "1732ca47-42b2-4990-a65d-c369e934eed3",
    "account_identifier": "PC_abc123xyz456def78901",
    "customer_type": "INDIVIDUAL",
    "kyc_status": "PENDING"
  }
}
FieldTypeDescription
customer_idstringThe customer UUID
account_identifierstringLending engine identifier. Present only on repeat calls.
customer_typestringINDIVIDUAL or BUSINESS
kyc_statusstringInitial status is always PENDING
enrolled_atstringUTC ISO-8601 timestamp

​
Error Responses

StatusMessageCause
400customer_id is requiredField missing from request body
400Customer not foundcustomer_id not found under this merchant
422Customer must have a BVN to enroll for lendingCustomer record has no BVN
422Customer must have an account before enrolling for lendingCustomer has no active wallet/account

Authorizations

​
apikey
string
header
required

Provide your API key in the 'apikey' header.

Headers

​
x-carbon-key
string
required

Body

application/json

Provide the required values for the request body.

​
customer_id
string
required

UUID of the customer to enroll

Example:

"1732ca47-42b2-4990-a65d-c369e934eed3"

Response

200 - application/json

Successful response

The response is of type object.