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

# Customer Onboarding

Onboard customers quickly and efficiently with our streamlined customer creation process. This guide covers the essential steps for creating customer profiles and preparing them for service.

## Creating a Customer

Create a new customer with basic information:

```bash theme={null}
curl -X POST https://api.platnova.com/v1/customers \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1234567890",
    "date_of_birth": "1990-05-15",
    "country_code": "US"
  }'
```

## Required Information

### Basic Details

* **First Name** - Customer's first name
* **Last Name** - Customer's last name
* **Email** - Valid email address
* **Phone** - Phone number with country code
* **Date of Birth** - `YYYY-MM-DD` for age verification
* **Country Code** - ISO country code (e.g., US, NG, GB)

### Optional Information

* **Gender** - Customer gender
* **Documents** - Identity documents including tax ID, passed as the `documents` array (see [Create Customer](/api-reference/customers/create)). See [Tax ID document](#tax-id-document) below.
* **Address** - Billing or residential address
* **Proof of funds** - Employment and source-of-funds fields (see below)

### Tax ID document

A tax ID is required when creating virtual accounts for a customer. Pass it as an entry in the `documents` array with the `id_type` that matches the customer's country, and the tax ID number in `id_number`.

The `id_type` varies by country — for example `ssn` for US customers, `nino` for UK customers, and `bvn` for Nigerian customers. Countries not covered by a specific type use `tin` as the default.

See the full country-to-type mapping in [Create Customer — Tax ID document](/api-reference/customers/create#tax-id-document).

**Example** — adding a tax ID for a US customer:

```json theme={null}
{
  "documents": [
    {
      "id_type": "ssn",
      "id_number": "123-45-6789"
    }
  ]
}
```

### Proof of funds values

Each `proof_of_funds` property must use an exact **field value** from the reference (for example `employment_status`: `employed`). Occupation uses identifiers such as `151252` for software developer.

See the full reference: **[Proof of funds options](/customers/proof-of-funds-options)**.

## Customer Response

```json theme={null}
{
  "status": true,
  "data": {
    "id": "customer_123",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1234567890",
    "country_code": "US",
    "status": "approval_pending",
    "created_at": "2025-01-30T10:00:00Z"
  },
  "message": "Customer created successfully"
}
```

## Customer Status

After creation, customers typically start with "approval\_pending" status. This means they're created but may need KYC verification before they can receive services.

### Status Flow

1. **Approval Pending** - Customer created, awaiting verification
2. **Active** - Customer verified and can receive services
3. **Locked** - Customer account is locked
4. **Restricted** - Customer has restrictions on their account

## Next Steps After Creation

Once a customer is created, you can:

* Issue cards to the customer
* Create virtual accounts for the customer
* Send payments to the customer
* Track customer transactions

## Retrieving Customer Information

Get customer details at any time:

```bash theme={null}
curl -X GET https://api.platnova.com/v1/customers/{customer_id} \
  -H "X-API-KEY: YOUR_API_KEY"
```

## Listing Customers

View all your customers:

```bash theme={null}
curl -X GET https://api.platnova.com/v1/customers \
  -H "X-API-KEY: YOUR_API_KEY"
```

## Best Practices

* Collect all required information during onboarding
* Verify email addresses and phone numbers
* Keep customer data up to date
* Monitor customer status for compliance

## Next Steps

* Use [Proof of funds options](/customers/proof-of-funds-options) when collecting `proof_of_funds` field values
* Learn about [KYC & Verification](/customers/kyc) for compliance requirements
* Explore the [Customers API Reference](/api-reference/customers/create) for detailed documentation