Create Customer

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"
  }
}
'

import requests

url = "https://api.platnova.com/v1/customers"

payload = {
    "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"
    }
}
headers = {
    "X-API-KEY": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'
    }
  })
};

fetch('https://api.platnova.com/v1/customers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.platnova.com/v1/customers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.platnova.com/v1/customers"

	payload := strings.NewReader("{\n  \"first_name\": \"John\",\n  \"last_name\": \"Doe\",\n  \"email\": \"[email protected]\",\n  \"phone\": \"+23490123456789\",\n  \"country_code\": \"NG\",\n  \"date_of_birth\": \"1970-12-28\",\n  \"gender\": \"male\",\n  \"documents\": [\n    {\n      \"id_type\": \"national_id\",\n      \"id_number\": \"1096277890\",\n      \"front_doc\": \"<base64-encoded image>\"\n    }\n  ],\n  \"address\": {\n    \"street\": \"12 Lekki Lane\",\n    \"city\": \"Lekki\",\n    \"state\": \"Lagos\",\n    \"postal_code\": \"200123\",\n    \"country\": \"Nigeria\",\n    \"document\": \"<base64-encoded proof of address>\"\n  },\n  \"proof_of_funds\": {\n    \"employment_status\": \"employed\",\n    \"occupation\": \"151252\",\n    \"primary_purpose\": \"payments_to_friends_or_family_abroad\",\n    \"source_of_funds\": \"salary\",\n    \"expected_monthly_pay\": \"0_4999\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-KEY", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.platnova.com/v1/customers")
  .header("X-API-KEY", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"first_name\": \"John\",\n  \"last_name\": \"Doe\",\n  \"email\": \"[email protected]\",\n  \"phone\": \"+23490123456789\",\n  \"country_code\": \"NG\",\n  \"date_of_birth\": \"1970-12-28\",\n  \"gender\": \"male\",\n  \"documents\": [\n    {\n      \"id_type\": \"national_id\",\n      \"id_number\": \"1096277890\",\n      \"front_doc\": \"<base64-encoded image>\"\n    }\n  ],\n  \"address\": {\n    \"street\": \"12 Lekki Lane\",\n    \"city\": \"Lekki\",\n    \"state\": \"Lagos\",\n    \"postal_code\": \"200123\",\n    \"country\": \"Nigeria\",\n    \"document\": \"<base64-encoded proof of address>\"\n  },\n  \"proof_of_funds\": {\n    \"employment_status\": \"employed\",\n    \"occupation\": \"151252\",\n    \"primary_purpose\": \"payments_to_friends_or_family_abroad\",\n    \"source_of_funds\": \"salary\",\n    \"expected_monthly_pay\": \"0_4999\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.platnova.com/v1/customers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"first_name\": \"John\",\n  \"last_name\": \"Doe\",\n  \"email\": \"[email protected]\",\n  \"phone\": \"+23490123456789\",\n  \"country_code\": \"NG\",\n  \"date_of_birth\": \"1970-12-28\",\n  \"gender\": \"male\",\n  \"documents\": [\n    {\n      \"id_type\": \"national_id\",\n      \"id_number\": \"1096277890\",\n      \"front_doc\": \"<base64-encoded image>\"\n    }\n  ],\n  \"address\": {\n    \"street\": \"12 Lekki Lane\",\n    \"city\": \"Lekki\",\n    \"state\": \"Lagos\",\n    \"postal_code\": \"200123\",\n    \"country\": \"Nigeria\",\n    \"document\": \"<base64-encoded proof of address>\"\n  },\n  \"proof_of_funds\": {\n    \"employment_status\": \"employed\",\n    \"occupation\": \"151252\",\n    \"primary_purpose\": \"payments_to_friends_or_family_abroad\",\n    \"source_of_funds\": \"salary\",\n    \"expected_monthly_pay\": \"0_4999\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "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"
}

{
  "status": false,
  "data": {},
  "error": [],
  "message": "customer already exists"
}

{
  "error": {
    "first_name": [
      "This field is required"
    ],
    "last_name": [
      "This field is required"
    ],
    "email": [
      "This field is required"
    ]
  }
}

POST

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"
  }
}
'

import requests

url = "https://api.platnova.com/v1/customers"

payload = {
    "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"
    }
}
headers = {
    "X-API-KEY": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'
    }
  })
};

fetch('https://api.platnova.com/v1/customers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.platnova.com/v1/customers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.platnova.com/v1/customers"

	payload := strings.NewReader("{\n  \"first_name\": \"John\",\n  \"last_name\": \"Doe\",\n  \"email\": \"[email protected]\",\n  \"phone\": \"+23490123456789\",\n  \"country_code\": \"NG\",\n  \"date_of_birth\": \"1970-12-28\",\n  \"gender\": \"male\",\n  \"documents\": [\n    {\n      \"id_type\": \"national_id\",\n      \"id_number\": \"1096277890\",\n      \"front_doc\": \"<base64-encoded image>\"\n    }\n  ],\n  \"address\": {\n    \"street\": \"12 Lekki Lane\",\n    \"city\": \"Lekki\",\n    \"state\": \"Lagos\",\n    \"postal_code\": \"200123\",\n    \"country\": \"Nigeria\",\n    \"document\": \"<base64-encoded proof of address>\"\n  },\n  \"proof_of_funds\": {\n    \"employment_status\": \"employed\",\n    \"occupation\": \"151252\",\n    \"primary_purpose\": \"payments_to_friends_or_family_abroad\",\n    \"source_of_funds\": \"salary\",\n    \"expected_monthly_pay\": \"0_4999\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-KEY", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.platnova.com/v1/customers")
  .header("X-API-KEY", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"first_name\": \"John\",\n  \"last_name\": \"Doe\",\n  \"email\": \"[email protected]\",\n  \"phone\": \"+23490123456789\",\n  \"country_code\": \"NG\",\n  \"date_of_birth\": \"1970-12-28\",\n  \"gender\": \"male\",\n  \"documents\": [\n    {\n      \"id_type\": \"national_id\",\n      \"id_number\": \"1096277890\",\n      \"front_doc\": \"<base64-encoded image>\"\n    }\n  ],\n  \"address\": {\n    \"street\": \"12 Lekki Lane\",\n    \"city\": \"Lekki\",\n    \"state\": \"Lagos\",\n    \"postal_code\": \"200123\",\n    \"country\": \"Nigeria\",\n    \"document\": \"<base64-encoded proof of address>\"\n  },\n  \"proof_of_funds\": {\n    \"employment_status\": \"employed\",\n    \"occupation\": \"151252\",\n    \"primary_purpose\": \"payments_to_friends_or_family_abroad\",\n    \"source_of_funds\": \"salary\",\n    \"expected_monthly_pay\": \"0_4999\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.platnova.com/v1/customers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"first_name\": \"John\",\n  \"last_name\": \"Doe\",\n  \"email\": \"[email protected]\",\n  \"phone\": \"+23490123456789\",\n  \"country_code\": \"NG\",\n  \"date_of_birth\": \"1970-12-28\",\n  \"gender\": \"male\",\n  \"documents\": [\n    {\n      \"id_type\": \"national_id\",\n      \"id_number\": \"1096277890\",\n      \"front_doc\": \"<base64-encoded image>\"\n    }\n  ],\n  \"address\": {\n    \"street\": \"12 Lekki Lane\",\n    \"city\": \"Lekki\",\n    \"state\": \"Lagos\",\n    \"postal_code\": \"200123\",\n    \"country\": \"Nigeria\",\n    \"document\": \"<base64-encoded proof of address>\"\n  },\n  \"proof_of_funds\": {\n    \"employment_status\": \"employed\",\n    \"occupation\": \"151252\",\n    \"primary_purpose\": \"payments_to_friends_or_family_abroad\",\n    \"source_of_funds\": \"salary\",\n    \"expected_monthly_pay\": \"0_4999\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "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"
}

{
  "status": false,
  "data": {},
  "error": [],
  "message": "customer already exists"
}

{
  "error": {
    "first_name": [
      "This field is required"
    ],
    "last_name": [
      "This field is required"
    ],
    "email": [
      "This field is required"
    ]
  }
}

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)
`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.

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:

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".

Authorizations

X-API-KEY

string

header

required

API key for authentication.

Body

application/json

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.

Show child attributes

document

object

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

Show child attributes

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.

Show child attributes

address

object

Show child attributes

proof_of_funds

object

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

Show child attributes

Response

Customer created successfully

status

boolean

data

object

Show child attributes

error

any[]

message

string

API Documentation

Customers

Cards

Virtual Accounts

Payments

Transactions

Payment Links

Checkout

Invoices

Wallets

Overview

Required fields

Optional fields

Identity documents

Tax ID document

Authorizations

Body

Response

​Overview

​Required fields

​Optional fields

​Identity documents

​Tax ID document

Authorizations

Body

Response

Overview

Required fields

Optional fields

Identity documents

Tax ID document