> ## Documentation Index > Fetch the complete documentation index at: https://docs.platnova.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Customer > Create a new individual customer profile with identification details, address information, and KYC compliance data. ## Overview Create a new individual customer profile. This endpoint allows you to onboard customers with identification details, address information, and KYC (Know Your Customer) compliance data. The response confirms successful creation or returns relevant validation errors. ## Required fields | Field | Description | | --------------- | ------------------- | | `email` | Valid email address | | `first_name` | Customer first name | | `last_name` | Customer last name | | `phone` | Phone number | | `date_of_birth` | `YYYY-MM-DD` | | `country_code` | ISO country code | ## Optional fields | Field | Description | | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `gender` | Customer gender | | `documents` | Array of identity documents (recommended; see [Identity documents](#identity-documents)) | | `address` | Residential or mailing address: `street`, `city`, `state`, `postal_code`, `country`, optional `document` (base64-encoded proof-of-address file) | | `proof_of_funds` | Employment and source-of-funds object (`employment_status`, `occupation`, `primary_purpose`, `source_of_funds`, `expected_monthly_pay`). Allowed **field** values and meanings are in [Proof of funds options](/customers/proof-of-funds-options). | ## Identity documents Each entry in the `documents` array uses the same shape: * **`id_type`** — Any of: `passport`, `resident_id`, `drivers_license`, `national_id`, `voters_card`, `nin`, `bvn`, or a tax ID type (see [Tax ID document](#tax-id-document)) * **`id_number`** — The number on the document * **`front_doc`** — Base64-encoded image of the front * **`back_doc`** — Base64-encoded image of the back when applicable For `passport`, `resident_id`, `drivers_license`, `national_id`, `voters_card`, and `nin`, you need **at most** `front_doc` (base64); `back_doc` is not required for those types. To change documents or proof-of-funds after creation, use [Update customer](/api-reference/customers/update). ### Tax ID document A tax ID document is required when creating virtual accounts for a customer. Submit it as an entry in the `documents` array. The tax ID value is always passed in `id_number`; the `id_type` depends on the customer's country: | Country | Country Code | `id_type` | | ------------------- | ------------ | --------- | | Algeria | `DZ` | `nif` | | Angola | `AO` | `nif` | | Canada | `CA` | `sin` | | France | `FR` | `spi` | | Indonesia | `ID` | `npwp` | | Italy | `IT` | `cf` | | Kenya | `KE` | `pin` | | Mexico | `MX` | `rfc` | | Nepal | `NP` | `pan` | | Nigeria | `NG` | `bvn` | | Pakistan | `PK` | `ntn` | | Romania | `RO` | `cnp` | | Tunisia | `TN` | `mf` | | Turkey | `TR` | `tckn` | | United Kingdom | `GB` | `nino` | | United States | `US` | `ssn` | | All other countries | — | `tin` | For any country not listed above, use `id_type: "tin"`. ## OpenAPI ````yaml POST /v1/customers openapi: 3.1.0 info: title: API version: 1.0.0 description: >- Platnova's Business API allows businesses to issue virtual accounts and cards to their employees, vendors, or retail customers. It allows businesses to streamline the process of issuing cards, manage spending, and track transactions. The API documentation provides information on how to integrate our virtual card issuing system into a business's existing systems and outlines the features and functionalities of the API, including card and account creation, management, and reporting. It also provides technical specifications, such as API requests, responses, and authentication processes. The API documentation is intended for developers and IT teams to use in order to effectively implement Platnova solutions into their business processes. # Authentication/Authorization To access any of the resources on the `{BaseUrl}/v1/`, the client has to pass pre-defined headers for authentication and authorization. The API is secure and only authorized clients can consume the service. There are API keys assigned to every business and JWT tokens assigned to every account for authentication/authorization. ## Bearer Token Requests may accept jwt tokens as below. ``` json Authorization: Bearer ``` ## API Key Requests may acccept an api key either in the request headers or as a query parameter. Some requests cannot be authorized using an API key. ``` json X-API-KEY: ``` OR ``` json ?api-key= ``` # Base URL [https://sandbox.api.platnova.co](https://sandbox.api.platnova.co) # Errors Unauthorized API key ``` json { "status": false, "data": {}, "error": [], "message": "unauthorized access" } ``` Permission Denied ``` json { "status": false, "data": {}, "error": [], "message": "unauthorized access: permission denied" } ``` servers: - url: https://api.platnova.com description: Production server - url: https://sandbox.api.platnova.co description: Development server security: - apiKeyAuth: [] tags: - name: Customer description: Create and manage customers - name: Virtual Account description: Create and manage virtual accounts - name: Card description: Create and manage cards - name: Wallet description: List and manage wallets - name: Payment description: Send and verify payments - name: Transaction description: List transactions and generate receipts - name: Checkout description: Create and retrieve checkout sessions - name: Payment Link description: Create and manage payment links - name: Invoice description: Create and manage invoices paths: /v1/customers: post: tags: - Customer summary: Create customer description: >- Create a new individual customer profile with identification details, address information, and KYC compliance data. operationId: createCustomer requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateCustomerRequest' example: first_name: John last_name: Doe email: johndoe06@email.com phone: '+23490123456789' country_code: NG date_of_birth: '1970-12-28' gender: male documents: - id_type: national_id id_number: '1096277890' front_doc: address: street: 12 Lekki Lane city: Lekki state: Lagos postal_code: '200123' country: Nigeria document: proof_of_funds: employment_status: employed occupation: '151252' primary_purpose: payments_to_friends_or_family_abroad source_of_funds: salary expected_monthly_pay: '0_4999' responses: '200': description: Customer created successfully content: application/json: schema: type: object properties: status: type: boolean data: type: object properties: id: type: string first_name: type: string last_name: type: string email: type: string format: email phone: type: string country_code: type: string status: type: string error: type: array items: {} message: type: string example: status: true data: id: 3be6624b-81a4-40d9-bfa9-c4dd8e4f7c18 first_name: John last_name: Doe email: johndoe04@email.com phone: '90123456789' country_code: NGA status: APPROVAL_PENDING error: [] message: operation was successful '400': description: Customer already exists content: application/json: schema: $ref: '#/components/schemas/Error' example: status: false data: {} error: [] message: customer already exists '422': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError422' example: error: first_name: - This field is required last_name: - This field is required email: - This field is required components: schemas: CreateCustomerRequest: type: object required: - email - first_name - last_name - phone - date_of_birth - country_code properties: email: type: string format: email description: Customer email first_name: type: string description: Customer first name last_name: type: string description: Customer last name phone: type: string description: Customer phone number date_of_birth: type: string format: date description: Date of birth (YYYY-MM-DD) gender: type: string description: Customer gender country_code: type: string description: ISO country code documents: type: array items: $ref: '#/components/schemas/DocumentInput' description: >- Identity documents (see DocumentInput). Preferred way to send one or more IDs on create. document: description: >- Legacy single primary identity document. Same shape and id_type values as each item in documents. Prefer documents when starting new integrations. allOf: - $ref: '#/components/schemas/DocumentInput' additional_documents: type: array items: $ref: '#/components/schemas/DocumentInput' description: >- Legacy extra identity documents. Same id_type options and front/back rules as documents. The API merges these with documents server-side; prefer a single documents array when possible. address: $ref: '#/components/schemas/CustomerAddress' proof_of_funds: $ref: '#/components/schemas/ProofOfFunds' Error: type: object properties: status: type: boolean data: type: object error: type: array items: {} message: type: string description: Error message ValidationError422: type: object description: Validation error response (422). Keys are request body field names. properties: error: type: object additionalProperties: type: array items: type: string description: Field name to list of error messages DocumentInput: type: object description: >- Identity document fields. Supported id_type values: passport, resident_id, drivers_license, national_id, voters_card, nin, bvn. For passport, resident_id, drivers_license, national_id, voters_card, and nin, provide at most front_doc as a base64-encoded image; back_doc is not required. These rules apply to each item in documents, to legacy document and additional_documents on create, and to each item in documents on update. properties: id_type: type: string enum: - passport - resident_id - drivers_license - national_id - voters_card - nin - bvn description: Identity document type id_number: type: string description: Document number front_doc: type: string description: Base64-encoded image of the document front back_doc: type: string description: Base64-encoded image of the document back (when applicable) CustomerAddress: type: object properties: street: type: string city: type: string state: type: string postal_code: type: string country: type: string document: type: string description: >- Base64-encoded proof-of-address file (e.g. utility bill or bank statement image) ProofOfFunds: type: object description: >- Proof-of-funds / source-of-wealth fields. Use allowed field values from Proof of funds options in the Customers guides. properties: employment_status: type: string description: Employment status code enum: - employed - homemaker - retired - self_employed - student - unemployed occupation: type: string description: Occupation field value (SOC-style); see Proof of funds options guide enum: - '151252' - '291141' - 2912XX - 21109X - '151299' - '434051' - 1320XX - '131082' - '151255' - '273099' - '119111' - '231011' - '232099' - '119199' - '131161' - '112021' - 17302X - '132011' - '151211' - '999999' primary_purpose: type: string description: Primary purpose code enum: - charitable_donations - ecommerce_retail_payments - investment_purposes - operating_a_company - payments_to_friends_or_family_abroad - personal_or_living_expenses - protect_wealth - purchase_goods_and_services - receive_payment_for_freelancing source_of_funds: type: string description: Source of funds code enum: - company_funds - gifts - government_benefits - inheritance - pension_retirement - salary - sale_of_assets_real_estate - savings expected_monthly_pay: type: string description: Expected monthly payments / income band code enum: - '0_4999' - '5000_9999' securitySchemes: apiKeyAuth: type: apiKey in: header name: X-API-KEY description: API key for authentication. ````