> For the complete documentation index, see [llms.txt](https://ivorypay.gitbook.io/ivorypay-on-off-ramp-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ivorypay.gitbook.io/ivorypay-on-off-ramp-documentation/api-reference-customers/create.md).

# Create Customer

Create a new customer for your business.

Creates a new customer record associated with your business. Customers are used to track transactions and manage user data.

{% hint style="info" %}
You can also create customers implicitly by using the "with customer" variants of the on-ramp and off-ramp endpoints.
{% endhint %}

## Endpoint

```
POST /v1/customers
```

## Authentication

Accepts either a merchant API key or a business-user JWT.

| Header          | Value                             |
| --------------- | --------------------------------- |
| `Authorization` | `<api_key>` **or** `Bearer <jwt>` |

## Request body

| Field         | Type   | Required | Description                                               |
| ------------- | ------ | -------- | --------------------------------------------------------- |
| `firstName`   | string | No       | Customer's first name                                     |
| `lastName`    | string | No       | Customer's last name                                      |
| `email`       | string | Yes      | Customer's email address (must be unique per environment) |
| `phoneNumber` | string | Yes      | Customer's phone number (E.164 format)                    |

## Example request

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST https://ramp-api.ivorypay.io/api/v1/customers \
  -H "Authorization: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Amina",
    "lastName": "Okafor",
    "email": "amina@example.com",
    "phoneNumber": "+2348012345678"
  }'
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
const response = await fetch("https://ramp-api.ivorypay.io/api/v1/customers", {
  method: "POST",
  headers: {
    "Authorization": "your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    firstName: "Amina",
    lastName: "Okafor",
    email: "amina@example.com",
    phoneNumber: "+2348012345678",
  }),
});

const data = await response.json();
console.log(data);
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

response = requests.post(
    "https://ramp-api.ivorypay.io/api/v1/customers",
    headers={
        "Authorization": "your_api_key",
        "Content-Type": "application/json",
    },
    json={
        "firstName": "Amina",
        "lastName": "Okafor",
        "email": "amina@example.com",
        "phoneNumber": "+2348012345678",
    },
)

print(response.json())
```

{% endtab %}

{% tab title="Go" %}

```go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	body, _ := json.Marshal(map[string]string{
		"firstName":   "Amina",
		"lastName":    "Okafor",
		"email":       "amina@example.com",
		"phoneNumber": "+2348012345678",
	})

	req, _ := http.NewRequest("POST", "https://ramp-api.ivorypay.io/api/v1/customers", bytes.NewBuffer(body))
	req.Header.Set("Authorization", "your_api_key")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	respBody, _ := io.ReadAll(resp.Body)
	fmt.Println(string(respBody))
}
```

{% endtab %}
{% endtabs %}

## Example response

```json
{
  "success": true,
  "message": "Customer was created successfully",
  "data": {
    "id": "c3d4e5f6-a7b8-9012-cdef-a12345678901",
    "refCode": "abc123def4",
    "firstName": "Amina",
    "lastName": "Okafor",
    "email": "amina@example.com",
    "phoneNumber": "+2348012345678",
    "context": "LIVE",
    "createdAt": "2026-03-26T12:00:00.000Z"
  }
}
```

## Response fields

| Field         | Type   | Description                                        |
| ------------- | ------ | -------------------------------------------------- |
| `id`          | string | Unique customer UUID                               |
| `refCode`     | string | IvoryPay-generated 10-character customer reference |
| `firstName`   | string | Customer's first name                              |
| `lastName`    | string | Customer's last name                               |
| `email`       | string | Customer's email                                   |
| `phoneNumber` | string | Customer's phone number                            |
| `context`     | string | Environment (`TEST` or `LIVE`)                     |
| `createdAt`   | string | ISO 8601 creation timestamp                        |

## Error cases

| Scenario        | Description                                                   |
| --------------- | ------------------------------------------------------------- |
| Duplicate email | A customer with this email already exists in this environment |