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

# Create Customer | Customers API

> Create customer via the Atoa Customers API, request parameters, response schema and code samples in cURL, Python, JavaScript, PHP, Go and Java.

Create a customer if you want to save card details and make future payments. Guest checkout or one-off payment doesn't mandate you to create a customer.

### Authorization

Bearer `<accessSecret>`

**Request Body Schema**

**fullName** `string` *required*

Customer's full name. Must be 2-30 characters and not blank.

**email** `string`

Customer's email address. Must be a valid email format. Either email or phone number is required.

**type** `string` (default: INDIVIDUAL)

Customer type.

> **Possible values**
>
> * `INDIVIDUAL` - Individual customer (default)
> * `BUSINESS` - Business customer

**phoneCountryCode** `string`

Phone country code, digits only. Max 5 characters. Example: `44` for UK.

**phoneNumber** `string`

Phone number without country code, digits only. Max 15 characters.

**address** `string`

Customer's address. Max 100 characters.

**city** `string`

Customer's city. Max 30 characters.

**postcode** `string`

Customer's postcode. 4-8 characters, letters, numbers and spaces only. Example: `SW1A 1AA`.

**vatNumber** `string`

VAT number for business customers. Must be 9 digits, optionally prefixed with `GB`. Example: `123456789` or `GB123456789`.

**metadata** `object`

Set of key-value pairs that you can attach to a customer. This can be useful for storing additional information about the customer in a structured format.

* Up to **50** key-value pairs.
* Each key must be **1-40** characters, must not contain `[` or `]`, and must not be blank or have leading or trailing whitespace.
* Each value must be a **string** of at most **500** characters.
* A key sent with an empty-string value (`""`) is dropped.

Once set, metadata is returned in the **Get Customer**, **List Customers**, and **Update Customer** responses.

**Response**

**id** `string`

Unique identifier for the customer (UUID).

**fullName** `string`

Customer's full name.

**email** `string`

Customer's email address.

**type** `string`

Customer type (`INDIVIDUAL` or `BUSINESS`).

**phoneCountryCode** `string`

Phone country code.

**phoneNumber** `string`

Phone number.

**address** `string`

Customer's address.

**city** `string`

Customer's city.

**postcode** `string`

Customer's postcode.

**vatNumber** `string`

VAT number (business customers only).

**metadata** `object`

Key/value string pairs attached to the customer.

**createdAt** `string`

ISO 8601 creation timestamp.

```bash curl theme={null}
curl --request POST \
  --url https://api.atoa.me/api/customers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "fullName": "John Doe",
  "email": "john.doe@example.com",
  "type": "INDIVIDUAL",
  "phoneCountryCode": "44",
  "phoneNumber": "7911123456",
  "address": "123 High Street",
  "city": "London",
  "postcode": "SW1A 1AA",
  "metadata": {
    "crmId": "CRM-8842",
    "loyaltyTier": "gold"
  }
}'
```

```python Python theme={null}
import requests

url = "https://api.atoa.me/api/customers"

payload = {
    "fullName": "John Doe",
    "email": "john.doe@example.com",
    "type": "INDIVIDUAL",
    "phoneCountryCode": "44",
    "phoneNumber": "7911123456",
    "address": "123 High Street",
    "city": "London",
    "postcode": "SW1A 1AA",
    "metadata": {
        "crmId": "CRM-8842",
        "loyaltyTier": "gold"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

```javascript JavaScript theme={null}
const response = await fetch("https://api.atoa.me/api/customers", {
  method: "POST",
  headers: {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    fullName: "John Doe",
    email: "john.doe@example.com",
    type: "INDIVIDUAL",
    phoneCountryCode: "44",
    phoneNumber: "7911123456",
    address: "123 High Street",
    city: "London",
    postcode: "SW1A 1AA",
    metadata: {
      crmId: "CRM-8842",
      loyaltyTier: "gold",
    },
  }),
});

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

```php PHP theme={null}
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.atoa.me/api/customers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    "fullName" => "John Doe",
    "email" => "john.doe@example.com",
    "type" => "INDIVIDUAL",
    "phoneCountryCode" => "44",
    "phoneNumber" => "7911123456",
    "address" => "123 High Street",
    "city" => "London",
    "postcode" => "SW1A 1AA",
    "metadata" => [
      "crmId" => "CRM-8842",
      "loyaltyTier" => "gold"
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
curl_close($curl);
echo $response;
```

```go Go theme={null}
package main

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

func main() {
  url := "https://api.atoa.me/api/customers"
  payload := strings.NewReader(`{
    "fullName": "John Doe",
    "email": "john.doe@example.com",
    "type": "INDIVIDUAL",
    "phoneCountryCode": "44",
    "phoneNumber": "7911123456",
    "address": "123 High Street",
    "city": "London",
    "postcode": "SW1A 1AA",
    "metadata": {
      "crmId": "CRM-8842",
      "loyaltyTier": "gold"
    }
  }`)

  req, _ := http.NewRequest("POST", url, payload)
  req.Header.Add("Authorization", "Bearer <token>")
  req.Header.Add("Content-Type", "application/json")

  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)
  fmt.Println(string(body))
}
```

```java Java theme={null}
HttpResponse<String> response = Unirest.post("https://api.atoa.me/api/customers")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\"fullName\":\"John Doe\",\"email\":\"john.doe@example.com\",\"type\":\"INDIVIDUAL\",\"phoneCountryCode\":\"44\",\"phoneNumber\":\"7911123456\",\"address\":\"123 High Street\",\"city\":\"London\",\"postcode\":\"SW1A 1AA\",\"metadata\":{\"crmId\":\"CRM-8842\",\"loyaltyTier\":\"gold\"}}")
  .asString();
```

```json 201 theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "fullName": "John Doe",
  "email": "john.doe@example.com",
  "type": "INDIVIDUAL",
  "phoneCountryCode": "44",
  "phoneNumber": "7911123456",
  "address": "123 High Street",
  "city": "London",
  "postcode": "SW1A 1AA",
  "metadata": {
    "crmId": "CRM-8842",
    "loyaltyTier": "gold"
  },
  "createdAt": "2025-06-15T10:30:00.000Z"
}
```

```json 400 theme={null}
{
  "name": "BAD_REQUEST",
  "message": "Full name must be at least 2 characters.",
  "status": 400,
  "errors": []
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.