> ## Documentation Index
> Fetch the complete documentation index at: https://docs.partnero.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create customer

> Create a customer and attribute them to an affiliate partner for commission tracking

## Endpoint

```
POST https://api.partnero.com/v1/customers
```

## Request body

| Parameter              | Type   | Required | Description                                                    |
| ---------------------- | ------ | -------- | -------------------------------------------------------------- |
| `key`                  | string | Yes      | Unique customer identifier (use account ID or email)           |
| `email`                | string | No       | Customer's email address                                       |
| `name`                 | string | No       | Customer's first name                                          |
| `surname`              | string | No       | Customer's last name                                           |
| `tags`                 | array  | No       | Tags to associate with the customer                            |
| `partner.key`          | string | Yes\*    | Partner's referral key (from `partnero_partner` cookie or URL) |
| `partner.id`           | string | Yes\*    | Partner's ID (alternative to key)                              |
| `partner.email`        | string | Yes\*    | Partner's email (alternative to key)                           |
| `options.referral_url` | string | No       | Referral URL for custom link attribution                       |

\*Provide at least one: `partner.key`, `partner.id`, or `partner.email`.

## Request

```bash cURL theme={null}
curl --location 'https://api.partnero.com/v1/customers' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "partner": {
      "key": "ref_123"
    },
    "key": "customer_123",
    "email": "alice.brown@example.com",
    "name": "Alice",
    "surname": "Brown",
    "tags": ["new"]
  }'
```

## Response

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "data": {
      "key": "customer_123",
      "partner": "partner_123",
      "deleted": false,
      "name": "Alice",
      "surname": "Brown",
      "email": "alice.brown@example.com",
      "status": "active",
      "created_at": "2025-05-02T16:12:39.000000Z",
      "updated_at": "2025-05-02T16:12:39.000000Z",
      "deleted_at": null,
      "tags": [
        {
          "value": "new"
        }
      ]
    },
    "status": 1
  }
  ```
</ResponseExample>

<Tip>
  The `partner.key` is stored in the `partnero_partner` cookie when a visitor clicks a referral link. Use the PartneroJS script to automatically capture this.
</Tip>

## Error responses

| Status | Error               | Solution                                              |
| ------ | ------------------- | ----------------------------------------------------- |
| 400    | Invalid partner key | Verify the partner exists in your program             |
| 422    | Validation error    | Check required fields (`key`, partner identification) |
| 422    | Duplicate key       | Customer with this key already exists                 |