Create a new customer on our platform
POST/v1/customers
Create a new customer
Creates a new customer. You can then use this customer to place an order for a product. Insurance regulation requires KYC, so some fields are mandatory.
Customer types
- Individual (default): omit
customer_type, or set it toindividual. - Business: set
customer_typetobusiness.
Optional KYC parameters
You can omit these parameters:
- bvn
- proof_of_address
Request
- application/json
- multipart/form-data
Body
required
Details of the customer to create
- Individual
- Business
Possible values: [individual]
Default value: individual
Omit this field, or set it to individual, to create an individual customer.
Possible values: <= 150 characters
Your unique identifier for the customer as it exists on your database. It must be unique for your account. If you omit it, Curacel generates one. This would be used to identify this customer in all other operations.
Letters, numbers, dashes and underscores only. Spaces are not allowed.
Letters, numbers, dashes and underscores only. Spaces are not allowed.
Possible values: [M, F]
Must be either M or F
Customer's date of birth in YYYY-MM-DD format. The customer must be at least 18 years old. Required for partners onboarded on or after 1 August 2023.
Customer's email address. It must be unique for your account when you do not send ref.
Customer's phone number. Required for partners onboarded on or after 1 August 2023.
The specialty of the policy holder
Customer's home address. Required for partners onboarded on or after 1 August 2023. Also required to buy credit life products.
Possible values: Value must match regular expression ^[0-9]+$
Bank Verification Number. Digits only. This KYC field is optional.
proof_of_address objectnullable
The proof of the customer's address. This KYC field is optional. When you send it, both type and url are required. The type can be any string that describes the document. The url must be publicly accessible when you make this request, because Curacel copies and stores the file for insurers to view.
The type of proof of address e.g Electricity bill
A publicly available URL to the customer's proof of address file
The name of the customer's next of kin. Required to buy credit life products.
Phone number of the customer's next of kin. Required to buy credit life products.
ID card of the customer. To upload it, send the request as multipart/form-data. When you upload it, id_number and id_expiry are required.
Possible values: [driversLicense, internationalPassport, votersCard, nimc]
Type of ID
Number of the ID. Required when you upload id_card.
Expiry date of the ID in YYYY-MM-DD format. It must be today or a later date. Required when you upload id_card.
Possible values: [business]
Must be business to create a business customer.
Possible values: <= 150 characters
Your unique identifier for the customer as it exists on your database. It must be unique for your account. If you omit it, Curacel generates one. This would be used to identify this customer in all other operations.
Business email address. It must be unique for your account when you do not send ref.
Business phone number. Required for partners onboarded on or after 1 August 2023.
Description of the business.
Address of the business
ISO 3166-1 alpha-2 code of the business country, for example NG, KE or GH.
State of the business address
City of the business address
Business registration number
Tax Identification Number (TIN) of the business
Proof of business registration (file)
Memorandum and Articles of Association (file). Required when country is NG.
Date of birth of the director whose ID you upload, in YYYY-MM-DD format. The director must be at least 18 years old.
ID card of one director (file)
Possible values: [driversLicense, internationalPassport, votersCard, nimc]
Type of ID
Number of the ID
Expiry date of the ID in YYYY-MM-DD format. It must be today or a later date.
Body
required
Details of the customer to create
- Individual
- Business
Possible values: [individual]
Default value: individual
Omit this field, or set it to individual, to create an individual customer.
Possible values: <= 150 characters
Your unique identifier for the customer as it exists on your database. It must be unique for your account. If you omit it, Curacel generates one. This would be used to identify this customer in all other operations.
Letters, numbers, dashes and underscores only. Spaces are not allowed.
Letters, numbers, dashes and underscores only. Spaces are not allowed.
Possible values: [M, F]
Must be either M or F
Customer's date of birth in YYYY-MM-DD format. The customer must be at least 18 years old. Required for partners onboarded on or after 1 August 2023.
Customer's email address. It must be unique for your account when you do not send ref.
Customer's phone number. Required for partners onboarded on or after 1 August 2023.
The specialty of the policy holder
Customer's home address. Required for partners onboarded on or after 1 August 2023. Also required to buy credit life products.
Possible values: Value must match regular expression ^[0-9]+$
Bank Verification Number. Digits only. This KYC field is optional.
proof_of_address objectnullable
The proof of the customer's address. This KYC field is optional. When you send it, both type and url are required. The type can be any string that describes the document. The url must be publicly accessible when you make this request, because Curacel copies and stores the file for insurers to view.
The type of proof of address e.g Electricity bill
A publicly available URL to the customer's proof of address file
The name of the customer's next of kin. Required to buy credit life products.
Phone number of the customer's next of kin. Required to buy credit life products.
ID card of the customer. To upload it, send the request as multipart/form-data. When you upload it, id_number and id_expiry are required.
Possible values: [driversLicense, internationalPassport, votersCard, nimc]
Type of ID
Number of the ID. Required when you upload id_card.
Expiry date of the ID in YYYY-MM-DD format. It must be today or a later date. Required when you upload id_card.
Possible values: [business]
Must be business to create a business customer.
Possible values: <= 150 characters
Your unique identifier for the customer as it exists on your database. It must be unique for your account. If you omit it, Curacel generates one. This would be used to identify this customer in all other operations.
Business email address. It must be unique for your account when you do not send ref.
Business phone number. Required for partners onboarded on or after 1 August 2023.
Description of the business.
Address of the business
ISO 3166-1 alpha-2 code of the business country, for example NG, KE or GH.
State of the business address
City of the business address
Business registration number
Tax Identification Number (TIN) of the business
Proof of business registration (file)
Memorandum and Articles of Association (file). Required when country is NG.
Date of birth of the director whose ID you upload, in YYYY-MM-DD format. The director must be at least 18 years old.
ID card of one director (file)
Possible values: [driversLicense, internationalPassport, votersCard, nimc]
Type of ID
Number of the ID
Expiry date of the ID in YYYY-MM-DD format. It must be today or a later date.
Responses
- 201
- 401
- 404
- 422
Created
- application/json
- Schema
- Example (from schema)
Schema
Unique identifier for the customer. This is the ref you sent, or the one that Curacel generated.
First and last name for an individual. Business name for a business.
Possible values: [individual, business]
The value you sent in customer_type. It is null when you omit it.
URL of the uploaded ID card
The sales channel of the customer, when set.
Only present when you send specialty.
Only present for business customers.
Only present for business customers.
Only present for business customers.
{
"id": 1024,
"ref": "189jwsp9",
"email": "john.doe@example.com",
"full_name": "John Doe",
"first_name": "John",
"last_name": "Doe",
"phone": "+2348123456789",
"sex": "M",
"birth_date": "1990-10-10",
"next_of_kin_name": "Jane Doe",
"next_of_kin_phone": "+2348123456780",
"residential_address": "6, some street",
"country": "Nigeria",
"state": "Lagos",
"city": "Ikeja",
"customer_type": "individual",
"created_at": "2026-10-23T10:15:30.000000Z",
"id_card": "https://example.com/customers/attachments/id-card.jpg",
"id_type": "nimc",
"id_number": "32wef0erwr",
"channel": "string",
"specialty": "Cardiologist",
"business_name": "ACME Corp",
"description": "Logistics and haulage company",
"tin": "12345678-0001"
}
Unauthenticated
- application/json
- Schema
- Example (from schema)
Schema
{
"message": "Unauthenticated."
}
Curacel could not download the file at proof_of_address.url
- application/json
- Schema
- Example (from schema)
Schema
{
"message": "Could not load proof of address url"
}
Unprocessable Content
- application/json
- Schema
- Example (from schema)
Schema
- Array [
- ]
errors object
Validation errors. Each key is a request field and each value is a list of error messages for that field.
property name* string[]
string
{
"message": "The email address is already registered.",
"errors": {
"email": [
"The email address is already registered."
],
"id_number": [
"The id number field is required."
]
}
}