> ## Documentation Index > Fetch the complete documentation index at: https://docs.getcarbon.co/llms.txt > Use this file to discover all available pages before exploring further. # Create Customer > Create a new customer with detailed information. ## Overview This endpoint allows you to create a new customer by providing their details such as name, email, phone, and more. ### Request **Method:** `POST`\ **URL:** `/v1/customers` #### Parameters | Name | In | Type | Required | Description | | -------------- | ------ | -------- | -------- | --------------------------- | | `x-carbon-key` | Header | `string` | Yes | API key for authentication. | #### Request Body ```json theme={null} { "first_name": "Provide first name", "last_name": "Provide last name", "email": "Provide email", "phone": "Provide phone number", "dob": "Provide date of birth", "gender": "Provide gender", "street": "Provide street address", "city": "Provide city", "state": "Provide state", "country": "Provide country", "bvn": "Provide BVN", "nin": "Provide NIN" } ``` ### Response **Status Code:** `200 OK`\ **Content-Type:** `application/json` #### Example Response ```json theme={null} { "status": "success", "message": "Customer created successfully", "data": { "id": "e128cc08-a43a-4db3-a27d-64bbcba0a0f2", "first_name": "Ola", "last_name": "Ajayi", "email": "ola@yahoo.com", "phone": "08071000030", "gender": "MALE", "dob": "1990-01-01T00:00:00.000Z", "nin": "11111111111", "bvn": "11111111111", "address": { "street": "NO 1 LAGOS ROAD", "city": "Lagos", "state": "Lagos", "country": "Nigeria" }, "is_business": false, "business_name": null, "mode": "sandbox", "created_at": "2024-03-07T10:12:34.000Z", "updated_at": "2024-03-07T10:12:34.000Z" } } ``` ## OpenAPI ````yaml POST /v1/customers openapi: 3.0.0 info: title: Carbon Business API description: >- ## Welcome to our API Developer Documentation Carbon aims to unlock the full potential of your business with a feature-rich account designed for growth. ## Integrations We aim to provide our APIs for developers and businesses to offer financial services to their existing customer base through REST APIs without doing the heavy lifting. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. ### Authentication `Authorization : API Key` Header `x-carbon-key : value` `x-carbon-key` can be generated via developer page on Carbon Business | Environment | URL | | --- | --- | | Live | | | Sandbox | [https://carbonapistagingsecure.getcarbon.co/baas/api](https://carbonapistagingsecure.getcarbon.co/baas/api) | ### **Handling Errors** We use the conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, etc.). Codes in the 5xx range indicate an error with our servers. | Error | Description | | --- | --- | | 400 - Bad Request | The request was unacceptable, often due to missing a required parameter. | | 401 - Unauthorized | Not a valid API key was provided. | | 402 - Request Failed | The parameters were valid but the request failed. | | 403 - Forbidden | The API key doesn't have permission to perform the request. | | 404 - Not Found | The requested resource doesn't exist. | | 429 - Too Many Requests | Too many requests hit the API | | 500, 502, 503, 504 - Server Errors | System Error | version: 1.0.0 servers: - url: https://carbonapistagingsecure.getcarbon.co/baas/api description: >- Replace {{base_url}} with your API base URL (e.g., https://api.example.com) security: - apikeyAuth: [] tags: - name: Accounts description: >- Virtual accounts are generated account details (account number and bank) that allow Carbon Business merchants to receive payments from customers via NGN bank transfer. This is currently only available in naira (NGN). Virtual accounts are either dynamic (temporary) or static (permanent). A dynamic account number expires after handling a transaction, while a static account number doesn't expire. **Static Account** Creating static accounts can be useful when receiving recurring payments through bank transfers. The process involves generating a static virtual account with customer information. Once payment is made, we will send you a webhook notification, which you can then manage. **Dynamic Account** Creating dynamic accounts can be useful when receiving one-time payments through bank transfers. The process involves generating a dynamic virtual account with a set amount for the customer during checkout. Once payment is made, we will send you a webhook notification, which you can then manage. Key things you can do with these endpoints: - Create an account - Retreive an account - Verify Transaction - Retreive a list of transactions - name: Accounts > Transactions - name: Banks description: |- - Get a list of banks and financial institutions - Verify/resolve account details - name: Customers description: >- This collection contains a set of API endpoints to manage customer-related operations for an application. The endpoints allow for creating a new customer, retrieving a list of all customers, and fetching details of a single customer. - Create Customer - Fetch Customer/Customers - name: Payout description: |- - Make Transfer - Verify Transfer - name: Status description: '- Service Health check' - name: Verification - name: Webhook description: |- ## EVENTS `account.incoming-transaction` ``` json { "event": "account.incoming-transaction", "data": { "id": "string", "amount": "float", "currency": "string", "transactionType": "string", "entryDate": "datetime", "uniqueRef": "string", "account": { "id": "string", "bankAccount": { "accountName": "string", "accountNumber": "string", "bank": { "code": "string", "name": "string" } }, "static": boolean, "currency": "string", "clientId": "string" } } } ``` `account.outgoing-transaction` ``` json { "event": "account.outgoing-transaction", "data": { "id": "string", "amount": "float", "currency": "string", "transactionType": "string", "entryDate": "datetime", "uniqueRef": "string", "account": { "id": "string", "bankAccount": { "accountName": "string", "accountNumber": "string", "bank": { "code": "string", "name": "string" } }, "static": boolean, "currency": "string", "clientId": "string" } } } ``` - name: Loans description: >- Partner lending API. Enables fintech partners to originate business loans for their end-customers. - Enroll customers for lending and trigger KYC - Submit loan applications and supporting documents - Manage offer acceptance, disbursement account, and post-offer steps - Charge repayments and retrieve repayment schedules paths: /v1/customers: post: tags: - Customers summary: Create Customer description: >- ## Create a Customer This endpoint allows you to create a new customer. ### Request Body - `first_name` (string, required): The first name of the customer. - `last_name` (string, required): The last name of the customer. - `email` (string, required): The email address of the customer. - `phone` (string, required): The phone number of the customer. - `dob` (string, required): The date of birth of the customer. - `gender` (string, required): The gender of the customer. - `street` (string, required): The street address of the customer. - `city` (string, required): The city of the customer. - `state` (string, required): The state of the customer. - `country` (string, required): The country of the customer. - `bvn` (string, required): The Bank Verification Number of the customer. - `nin` (string, required): The National Identification Number of the customer. ### Response - `status` (string): The status of the request. - `message` (string): A message related to the request. - `data` (object): The customer data. - `id` (string): The unique identifier of the customer. - `first_name` (string): The first name of the customer. - `last_name` (string): The last name of the customer. - `email` (string): The email address of the customer. - `phone` (string): The phone number of the customer. - `gender` (string): The gender of the customer. - `dob` (string): The date of birth of the customer. - `nin` (string): The National Identification Number of the customer. - `bvn` (string): The Bank Verification Number of the customer. - `address` (object): The address details of the customer. - `street` (string): The street address of the customer. - `city` (string): The city of the customer. - `state` (string): The state of the customer. - `country` (string): The country of the customer. - `is_business` (boolean): Indicates if the customer is a business entity. - `business_name` (string): The name of the business if the customer is a business entity. - `mode` (string): The mode of the request. - `created_at` (string): The date and time when the customer was created. - `updated_at` (string): The date and time when the customer was last updated. ### Example ``` json { "status": "", "message": "", "data": { "id": "", "first_name": "", "last_name": "", "email": "", "phone": "", "gender": "", "dob": "", "nin": "", "bvn": "", "address": { "street": "", "city": "", "state": "", "country": "" }, "is_business": true, "business_name": null, "mode": "", "created_at": "", "updated_at": "" } } ``` parameters: - name: x-carbon-key in: header schema: type: string required: true example: '{{access_token}}' requestBody: description: Provide the required values for the request body. required: true content: application/json: schema: type: object required: - first_name - last_name - email - phone - dob - gender - street - city - state - country - bvn properties: first_name: type: string description: Provide first name last_name: type: string description: Provide last name email: type: string description: Provide email phone: type: string description: Provide phone number dob: type: string description: Provide date of birth gender: type: string description: Provide gender street: type: string description: Provide street address city: type: string description: Provide city state: type: string description: Provide state country: type: string description: Provide country bvn: type: string description: Provide BVN nin: type: string description: Provide NIN example: first_name: Provide first name last_name: Provide last name email: Provide email phone: Provide phone number dob: Provide date of birth gender: Provide gender street: Provide street address city: Provide city state: Provide state country: Provide country bvn: Provide BVN nin: Provide NIN responses: '200': description: OK headers: Content-Security-Policy: schema: type: string example: >- default-src 'self';base-uri 'self';font-src 'self' https: data:;form-action 'self';frame-ancestors 'self';img-src 'self' data:;object-src 'none';script-src 'self';script-src-attr 'none';style-src 'self' https: 'unsafe-inline';upgrade-insecure-requests Cross-Origin-Opener-Policy: schema: type: string example: same-origin Cross-Origin-Resource-Policy: schema: type: string example: same-origin Origin-Agent-Cluster: schema: type: string example: '?1' Referrer-Policy: schema: type: string example: no-referrer Strict-Transport-Security: schema: type: string example: max-age=15552000; includeSubDomains X-Content-Type-Options: schema: type: string example: nosniff X-DNS-Prefetch-Control: schema: type: string example: 'off' X-Download-Options: schema: type: string example: noopen X-Frame-Options: schema: type: string example: SAMEORIGIN X-Permitted-Cross-Domain-Policies: schema: type: string example: none X-XSS-Protection: schema: type: integer example: '0' RateLimit-Policy: schema: type: string example: 100;w=900 RateLimit-Limit: schema: type: integer example: '100' RateLimit-Remaining: schema: type: integer example: '98' RateLimit-Reset: schema: type: integer example: '888' Content-Type: schema: type: string example: application/json; charset=utf-8 Content-Length: schema: type: integer example: '523' ETag: schema: type: string example: W/"20b-dLRktdNMXwb5aTszNJJIJ+0073I" Date: schema: type: string example: Thu, 07 Mar 2024 10:13:03 GMT Connection: schema: type: string example: keep-alive Keep-Alive: schema: type: string example: timeout=5 content: application/json: schema: type: object example: status: success message: Customer created successfully data: id: e128cc08-a43a-4db3-a27d-64bbcba0a0f2 first_name: ola last_name: ajayi email: ola@yahoo.com phone: '08071000030' gender: MALE dob: '1990-01-01T00:00:00.000Z' nin: '11111111111' bvn: '11111111111' address: street: NO 1 LAGOS ROAD city: IKEJA state: LAGOS STATE country: NIGERIA is_business: false business_name: null mode: sandbox created_at: '2024-03-07T10:12:34.000Z' updated_at: '2024-03-07T10:12:34.000Z' '400': description: Bad Request headers: Content-Security-Policy: schema: type: string example: >- default-src 'self';base-uri 'self';font-src 'self' https: data:;form-action 'self';frame-ancestors 'self';img-src 'self' data:;object-src 'none';script-src 'self';script-src-attr 'none';style-src 'self' https: 'unsafe-inline';upgrade-insecure-requests Cross-Origin-Opener-Policy: schema: type: string example: same-origin Cross-Origin-Resource-Policy: schema: type: string example: same-origin Origin-Agent-Cluster: schema: type: string example: '?1' Referrer-Policy: schema: type: string example: no-referrer Strict-Transport-Security: schema: type: string example: max-age=15552000; includeSubDomains X-Content-Type-Options: schema: type: string example: nosniff X-DNS-Prefetch-Control: schema: type: string example: 'off' X-Download-Options: schema: type: string example: noopen X-Frame-Options: schema: type: string example: SAMEORIGIN X-Permitted-Cross-Domain-Policies: schema: type: string example: none X-XSS-Protection: schema: type: integer example: '0' RateLimit-Policy: schema: type: string example: 100;w=900 RateLimit-Limit: schema: type: integer example: '100' RateLimit-Remaining: schema: type: integer example: '99' RateLimit-Reset: schema: type: integer example: '900' Content-Type: schema: type: string example: application/json; charset=utf-8 Content-Length: schema: type: integer example: '93' ETag: schema: type: string example: W/"5d-6CLsV5rNV8sx2+Tu+vrbCTSt+fE" Date: schema: type: string example: Wed, 28 Feb 2024 12:40:49 GMT Connection: schema: type: string example: keep-alive Keep-Alive: schema: type: string example: timeout=5 content: application/json: schema: type: object example: status: failed message: bad request errors: - msg: Request body cannot be empty components: securitySchemes: apikeyAuth: type: apiKey in: header name: apikey description: Provide your API key in the 'apikey' header. ````