> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.paywithatoa.co.uk/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.

<Note>
  For high-value card payment, we might collect customer details in the UI for a high success rate.
</Note>

### Authorization

Bearer `<accessSecret>`

**Request Body Schema**

<ParamField body="fullName" type="string" required>
  Customer's full name. Must be 2-30 characters and not blank.
</ParamField>

<ParamField body="email" type="string">
  Customer's email address. Must be a valid email format. Either email or phone number is required.
</ParamField>

<ParamField body="type" type="string" default="INDIVIDUAL">
  Customer type.

  <Accordion title="Possible values">
    * `INDIVIDUAL` - Individual customer (default)
    * `BUSINESS` - Business customer
  </Accordion>
</ParamField>

<ParamField body="phoneCountryCode" type="string">
  Phone country code, digits only. Max 5 characters. Example: `44` for UK.
</ParamField>

<ParamField body="phoneNumber" type="string">
  Phone number without country code, digits only. Max 15 characters.
</ParamField>

<ParamField body="address" type="string">
  Customer's address. Max 100 characters.
</ParamField>

<ParamField body="city" type="string">
  Customer's city. Max 30 characters.
</ParamField>

<ParamField body="postcode" type="string">
  Customer's postcode. 4-8 characters, letters, numbers and spaces only. Example: `SW1A 1AA`.
</ParamField>

<ParamField body="vatNumber" type="string">
  VAT number for business customers. Must be 9 digits, optionally prefixed with `GB`. Example: `123456789` or `GB123456789`.
</ParamField>

**Response**

<ResponseField name="id" type="string">
  Unique identifier for the customer (UUID).
</ResponseField>

<ResponseField name="fullName" type="string">
  Customer's full name.
</ResponseField>

<ResponseField name="email" type="string">
  Customer's email address.
</ResponseField>

<ResponseField name="type" type="string">
  Customer type (`INDIVIDUAL` or `BUSINESS`).
</ResponseField>

<ResponseField name="phoneCountryCode" type="string">
  Phone country code.
</ResponseField>

<ResponseField name="phoneNumber" type="string">
  Phone number.
</ResponseField>

<ResponseField name="address" type="string">
  Customer's address.
</ResponseField>

<ResponseField name="city" type="string">
  Customer's city.
</ResponseField>

<ResponseField name="postcode" type="string">
  Customer's postcode.
</ResponseField>

<ResponseField name="vatNumber" type="string">
  VAT number (business customers only).
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 creation timestamp.
</ResponseField>

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

  ```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"
  }
  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",
    }),
  });

  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"
    ]),
    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"
    }`)

    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\"}")
    .asString();
  ```
</RequestExample>

<ResponseExample>
  ```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",
    "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": []
  }
  ```

  ```json 409 theme={null}
  {
    "name": "CONFLICT",
    "message": "Customer with this email already exists",
    "status": 409,
    "errors": []
  }
  ```
</ResponseExample>