Skip to main content
POST
/
v1
/
customers
Create customer
curl --request POST \
  --url https://api.platnova.com/v1/customers \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "phone": "+23490123456789",
  "country_code": "NG",
  "date_of_birth": "1970-12-28",
  "gender": "male",
  "documents": [
    {
      "id_type": "national_id",
      "id_number": "1096277890",
      "front_doc": "<base64-encoded image>"
    }
  ],
  "address": {
    "street": "12 Lekki Lane",
    "city": "Lekki",
    "state": "Lagos",
    "postal_code": "200123",
    "country": "Nigeria",
    "document": "<base64-encoded proof of address>"
  },
  "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"
  }
}
'
{
  "status": true,
  "data": {
    "id": "3be6624b-81a4-40d9-bfa9-c4dd8e4f7c18",
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone": "90123456789",
    "country_code": "NGA",
    "status": "APPROVAL_PENDING"
  },
  "error": [],
  "message": "operation was successful"
}

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.

​
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

FieldDescription
emailValid email address
first_nameCustomer first name
last_nameCustomer last name
phonePhone number
date_of_birthYYYY-MM-DD
country_codeISO country code

​
Optional fields

FieldDescription
genderCustomer gender
documentsArray of identity documents (recommended; see Identity documents)
addressResidential or mailing address: street, city, state, postal_code, country, optional document (base64-encoded proof-of-address file)
proof_of_fundsEmployment 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.

​
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)
  • 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.

​
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:
CountryCountry Codeid_type
AlgeriaDZnif
AngolaAOnif
CanadaCAsin
FranceFRspi
IndonesiaIDnpwp
ItalyITcf
KenyaKEpin
MexicoMXrfc
NepalNPpan
NigeriaNGbvn
PakistanPKntn
RomaniaROcnp
TunisiaTNmf
TurkeyTRtckn
United KingdomGBnino
United StatesUSssn
All other countries—tin
For any country not listed above, use id_type: "tin".

Authorizations

​
X-API-KEY
string
header
required

API key for authentication.

Body

application/json
​
email
string<email>
required

Customer email

​
first_name
string
required

Customer first name

​
last_name
string
required

Customer last name

​
phone
string
required

Customer phone number

​
date_of_birth
string<date>
required

Date of birth (YYYY-MM-DD)

​
country_code
string
required

ISO country code

​
gender
string

Customer gender

​
documents
object[]

Identity documents (see DocumentInput). Preferred way to send one or more IDs on create.

​
document
object

Legacy single primary identity document. Same shape and id_type values as each item in documents. Prefer documents when starting new integrations.

​
additional_documents
object[]

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
object
​
proof_of_funds
object

Proof-of-funds / source-of-wealth fields. Use allowed field values from Proof of funds options in the Customers guides.

Response

Customer created successfully

​
status
boolean
​
data
object
​
error
any[]
​
message
string