> For the complete documentation index, see [llms.txt](https://docs.verifone.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verifone.com/api-reference/open-api-references/customer/list-create-customers.md).

# List\Create Customers

The **List Customers** endpoint retrieves customer records matching an [RSQL](https://aboullaite.me/rsql/) filter query, with support for pagination and sorting. The **Create Customer** endpoint creates a new shopper record and returns a UUID for use in downstream payment requests.

## List Customers

## GET /v2/customer

> List Customers

```json
{"openapi":"3.0.1","info":{"title":"Customer API","version":"1.17.0"},"tags":[{"name":"Customer","description":"Operations for creating, retrieving, updating, and deleting customer records."}],"servers":[{"url":"https://emea.gsc.verifone.cloud/oidc/customer-service","description":"EMEA Production"},{"url":"https://us.gsc.verifone.cloud/oidc/customer-service","description":"Americas Production"},{"url":"https://nz.gsc.verifone.cloud/oidc/customer-service","description":"New Zealand Production"},{"url":"https://cst.test-gsc.vfims.com/oidc/customer-service","description":"Global Sandbox"},{"url":"https://uscst-gb.gsc.vficloud.net/oidc/customer-service","description":"US Sandbox"}],"security":[{"BearerAuth":[]},{"BasicAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"BasicAuth":{"type":"http","scheme":"basic"}},"schemas":{"CustomerListResponse":{"type":"array","items":{"$ref":"#/components/schemas/CustomerResponse"}},"CustomerResponse":{"required":["created_at","entity_id","id","updated_at"],"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Customer UUID."},"billing":{"$ref":"#/components/schemas/Billing"},"company_name":{"maxLength":100,"type":"string","description":"Company name of the customer. **Required** when `billing.first_name` and `billing.last_name` are not provided."},"company_registration_number":{"maxLength":24,"type":"string","description":"Unique identifier of the company recognised by the government. Known as CoC (Chamber of Commerce) number in some countries."},"email_address":{"maxLength":255,"type":"string","format":"email","description":"Consumer's email address.\n\n**Note:** Required for 3DS. Please refer to the 3D Secure API specification for format requirements."},"entity_id":{"type":"string","description":"Entity ID on which the customer is created."},"phone_number":{"maxLength":25,"pattern":"^[0-9\\s\\-+().-]+$","type":"string","description":"Cardholder's phone number."},"shipping":{"$ref":"#/components/schemas/Shipping"},"title":{"pattern":"^[a-zA-Z\\-\\s.]+$","maxLength":120,"type":"string","description":"Customer's title (e.g. `Mr`, `Mrs`, `Dr`)."},"work_phone":{"maxLength":25,"pattern":"^[0-9\\s\\-+().-]+$","type":"string","description":"Consumer's work phone number."},"tax":{"$ref":"#/components/schemas/Tax"},"language":{"type":"string","description":"Customer language preference for Invoice documents. See [Localisation](https://docs.verifone.com/online-payments/checkout/localization) for details."},"created_at":{"type":"string","format":"date-time","description":"Timestamp when this customer was created."},"updated_at":{"type":"string","format":"date-time","description":"Timestamp when this customer was last updated."}}},"Billing":{"type":"object","properties":{"address_1":{"maxLength":40,"type":"string","description":"Customer's primary billing address information.\n\n**Note:** Required for 3DS. Please refer to the 3D Secure API specification for format requirements."},"address_2":{"maxLength":40,"type":"string","description":"Customer's secondary billing address information."},"address_3":{"maxLength":40,"type":"string","description":"Customer's third billing address information."},"city":{"maxLength":28,"type":"string","description":"Customer's city on their billing address.\n\n**Note:** Required for 3DS. Please refer to the 3D Secure API specification for format requirements."},"country_code":{"type":"string","description":"Customer's alpha-2 ISO 3166 country code (e.g. `US` for United States).\n\n**Note:** Required for 3DS. Please refer to the 3D Secure API specification for format requirements."},"first_name":{"maxLength":22,"type":"string","description":"Customer's first name. **Required** when `company_name` is not provided.\n\n**Note:** Required for 3DS. Please refer to the 3D Secure API specification for format requirements."},"middle_name":{"maxLength":22,"type":"string","description":"Customer's middle name."},"last_name":{"maxLength":22,"type":"string","description":"Customer's last name. **Required** when `company_name` is not provided.\n\n**Note:** Required for 3DS. Please refer to the 3D Secure API specification for format requirements."},"phone":{"maxLength":25,"pattern":"^[0-9\\s\\-+().-]+$","type":"string","description":"Customer's phone number for the billing address."},"postal_code":{"maxLength":10,"type":"string","description":"Customer's postal code for their billing address.\n\n**Note:** Required for 3DS unless a market or regional mandate restricts sending this information."},"state":{"maxLength":35,"type":"string","description":"Customer's state or province for their billing address (e.g. `OH` for Ohio, `TX` for Texas)."}}},"Shipping":{"type":"object","properties":{"address_1":{"maxLength":40,"type":"string","description":"Consumer's primary shipping address information.\n\n**Field required for:** Klarna, PayPal, Vipps, MobilePay, Google Pay, Apple Pay, Affirm, Swish"},"address_2":{"maxLength":40,"type":"string","description":"Consumer's secondary shipping address information.\n\n**Field required for:** PayPal"},"address_3":{"maxLength":40,"type":"string","description":"Consumer's third shipping address information."},"city":{"maxLength":28,"type":"string","description":"Consumer's city on their shipping address.\n\n**Field required for:** Klarna, PayPal, Vipps, MobilePay, Google Pay, Apple Pay, Affirm, Swish"},"first_name":{"maxLength":22,"type":"string","description":"Consumer's first name.\n\n**Field required for:** Klarna, Vipps, MobilePay"},"middle_name":{"maxLength":22,"type":"string","description":"Consumer's middle name."},"last_name":{"maxLength":22,"type":"string","description":"Consumer's last name.\n\n**Field required for:** Klarna, Vipps, MobilePay"},"phone":{"maxLength":25,"pattern":"^[0-9\\s\\-+().-]+$","type":"string","description":"Consumer's phone number for the shipping address.\n\n**Field required for:** Klarna, PayPal, Vipps, MobilePay"},"country_code":{"type":"string","description":"Consumer's alpha-2 ISO 3166 country code (e.g. `US` for United States).\n\n**Field required for:** Klarna, PayPal, Vipps, MobilePay, Google Pay, Apple Pay, Affirm, Swish"},"postal_code":{"maxLength":10,"type":"string","description":"Consumer's postal code for their shipping address.\n\n**Field required for:** Klarna, PayPal, Vipps, MobilePay, Google Pay, Apple Pay, Affirm, Swish"},"state":{"maxLength":35,"type":"string","description":"Consumer's state or province for their shipping address (e.g. `OH` for Ohio, `TX` for Texas).\n\n**Field required for:** Klarna, PayPal"}}},"Tax":{"type":"object","properties":{"identifier":{"pattern":"^[0-9]+$","type":"string","maxLength":9,"description":"An optional identifier of the document recipient:\n\n- Personal ID (for individuals)\n- Tax identification number (for businesses)"}}},"ErrorResponse":{"type":"object","properties":{"code":{"type":"integer","description":"A 3-digit code that uniquely identifies the error."},"details":{"type":"object","description":"Additional error details."},"message":{"type":"string","description":"A human-readable description of the error."},"timestamp":{"type":"integer","description":"Unix timestamp of when the error occurred."}}}}},"paths":{"/v2/customer":{"get":{"tags":["Customer"],"summary":"List Customers","operationId":"getV2Customer","parameters":[{"name":"search","in":"query","required":true,"description":"A filter query in [RSQL format](https://aboullaite.me/rsql/) to retrieve customers. The returned\ncustomers are limited to those that can be retrieved by the user.\n\n**Filterable fields:**\n\n| Criteria | Type | Operators |\n|---|---|---|\n| billing.address_1 | string | ==, !=, =in=, =out=, =regex= |\n| billing.address_2 | string | ==, !=, =in=, =out=, =regex= |\n| billing.address_3 | string | ==, !=, =in=, =out=, =regex= |\n| billing.city | string | ==, !=, =in=, =out=, =regex= |\n| billing.country_code | string | ==, !=, =in=, =out=, =regex= |\n| billing.first_name | string | ==, !=, =in=, =out=, =regex= |\n| billing.middle_name | string | ==, !=, =in=, =out=, =regex= |\n| billing.last_name | string | ==, !=, =in=, =out=, =regex= |\n| billing.phone | string | ==, !=, =in=, =out=, =regex= |\n| billing.postal_code | string | ==, !=, =in=, =out=, =regex= |\n| billing.state | string | ==, !=, =in=, =out=, =regex= |\n| company_name | string | ==, !=, =in=, =out=, =regex= |\n| company_registration_number | string | ==, !=, =in=, =out=, =regex= |\n| email_address | string | ==, !=, =in=, =out=, =regex= |\n| entity_id | string | ==, !=, =in=, =out=, =regex= |\n| id | string | ==, !=, =in=, =out=, =regex= |\n| phone_number | string | ==, !=, =in=, =out=, =regex= |\n| shipping.address_1 | string | ==, !=, =in=, =out=, =regex= |\n| shipping.address_2 | string | ==, !=, =in=, =out=, =regex= |\n| shipping.address_3 | string | ==, !=, =in=, =out=, =regex= |\n| shipping.city | string | ==, !=, =in=, =out=, =regex= |\n| shipping.country_code | string | ==, !=, =in=, =out=, =regex= |\n| shipping.first_name | string | ==, !=, =in=, =out=, =regex= |\n| shipping.middle_name | string | ==, !=, =in=, =out=, =regex= |\n| shipping.last_name | string | ==, !=, =in=, =out=, =regex= |\n| shipping.phone | number | ==, !=, =in=, =out=, =gt=, =ge=, =lt=, =le= |\n| shipping.postal_code | string | ==, !=, =in=, =out=, =regex= |\n| shipping.state | string | ==, !=, =in=, =out=, =regex= |\n| title | string | ==, !=, =in=, =out=, =regex= |\n| work_phone | string | ==, !=, =in=, =out=, =regex= |\n| tax.identifier | string | ==, !=, =in=, =out=, =regex= |\n| created_at | date | ==, !=, =in=, =out=, =gt=, =ge=, =lt=, =le= |\n| updated_at | date | ==, !=, =in=, =out=, =gt=, =ge=, =lt=, =le= |\n| language | string | ==, !=, =in=, =out=, =regex= |\n\n**Operators:**\n\n| Operator | Description |\n|---|---|\n| == | equal |\n| != | not equal |\n| =lt= | less than |\n| =le= | less than and equal to |\n| =gt= | greater than |\n| =ge= | greater than and equal to |\n| =regex= | pattern matching |\n| =in= | multiple arguments search |\n| =out= | exclude |\n| **;** | Logical AND |\n| **,** | Logical OR |\n\n**Note:** Logical AND (`;`) has higher precedence than Logical OR (`,`). Use parentheses `()` to\noverride operator precedence.\n\n**Examples:**\n\n    /v2/customer?search=id==123&order_by=ASC&order_criteria=email_address&page_size=1&page_number=2\n\n    /v2/customer?search=id==123435&order_by=DESC&order_criteria=billing.address_1&page_size=10&page_number=1\n\n    /v2/customer?search=id==dg373&order_by=ASC&order_criteria=company_name&page_size=1&page_number=2","schema":{"type":"string"}},{"name":"order_criteria","in":"query","description":"The field to order results by. If not specified, results are ordered by created date.\n\nAllowed values: `billing.address_1`, `billing.address_2`, `billing.address_3`, `billing.city`,\n`billing.country_code`, `billing.first_name`, `billing.middle_name`, `billing.last_name`,\n`billing.phone`, `billing.postal_code`, `billing.state`, `company_name`,\n`company_registration_number`, `email_address`, `entity_id`, `id`, `phone_number`,\n`shipping.address_1`, `shipping.address_2`, `shipping.address_3`, `shipping.city`,\n`shipping.country_code`, `shipping.first_name`, `shipping.last_name`, `shipping.phone`,\n`shipping.postal_code`, `shipping.state`, `title`, `work_phone`, `tax.identifier`, `created_at`","schema":{"type":"string"}},{"name":"order_by","in":"query","description":"The sort direction. Defaults to `DESC` if not specified.","schema":{"type":"string","enum":["ASC","DESC"]}},{"name":"page_number","in":"query","description":"Page number to retrieve. Defaults to `1` if not specified.","schema":{"minimum":1,"type":"integer"}},{"name":"page_size","in":"query","description":"Number of results per page. Defaults to `50` if not specified.","schema":{"minimum":1,"type":"integer"}}],"responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerListResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

### RSQL Filter Reference

The `search` parameter is required and accepts an [RSQL](https://aboullaite.me/rsql/) query string. Results are limited to customers accessible to the authenticated user.

{% tabs %}
{% tab title="String operators" %}
Use these with text fields such as `email_address`, `billing.first_name`, `billing.country_code`, and most others:

| Operator     | Description                  |
| ------------ | ---------------------------- |
| `==`         | Equal                        |
| `!=`         | Not equal                    |
| `=in=`       | Match any of multiple values |
| `=out=`      | Exclude multiple values      |
| `=regex=`    | Pattern match                |
| {% endtab %} |                              |

{% tab title="Numeric / date operators" %}
Use these with `created_at`, `updated_at`, and `shipping.phone`:

| Operator     | Description           |
| ------------ | --------------------- |
| `=gt=`       | Greater than          |
| `=ge=`       | Greater than or equal |
| `=lt=`       | Less than             |
| `=le=`       | Less than or equal    |
| `==`         | Equal                 |
| `!=`         | Not equal             |
| {% endtab %} |                       |

{% tab title="Logical operators" %}

| Operator | Description | Precedence |
| -------- | ----------- | ---------- |
| `;`      | Logical AND | Higher     |
| `,`      | Logical OR  | Lower      |

Use parentheses `()` to override default precedence.
{% endtab %}
{% endtabs %}

**Example queries:**

```http
# Find by ID, sort ascending by email, page 2 of 1-record pages
GET /v2/customer?search=id==123&order_by=ASC&order_criteria=email_address&page_size=1&page_number=2

# Find by ID, sort descending by billing address
GET /v2/customer?search=id==123435&order_by=DESC&order_criteria=billing.address_1&page_size=10&page_number=1

# Combine filters: email AND country
GET /v2/customer?search=email_address==shopper@example.com;billing.country_code==GB&order_by=DESC
```

{% hint style="info" %}
If `order_criteria` is not specified, results are ordered by `created_at`. If `order_by` is not specified, the default sort direction is `DESC`. `page_size` defaults to `50` and `page_number` defaults to `1`.
{% endhint %}

## Create Customer

## POST /v2/customer

> Create Customer

```json
{"openapi":"3.0.1","info":{"title":"Customer API","version":"1.17.0"},"tags":[{"name":"Customer","description":"Operations for creating, retrieving, updating, and deleting customer records."}],"servers":[{"url":"https://emea.gsc.verifone.cloud/oidc/customer-service","description":"EMEA Production"},{"url":"https://us.gsc.verifone.cloud/oidc/customer-service","description":"Americas Production"},{"url":"https://nz.gsc.verifone.cloud/oidc/customer-service","description":"New Zealand Production"},{"url":"https://cst.test-gsc.vfims.com/oidc/customer-service","description":"Global Sandbox"},{"url":"https://uscst-gb.gsc.vficloud.net/oidc/customer-service","description":"US Sandbox"}],"security":[{"BearerAuth":[]},{"BasicAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"BasicAuth":{"type":"http","scheme":"basic"}},"schemas":{"CustomerRequest":{"required":["entity_id"],"type":"object","properties":{"billing":{"$ref":"#/components/schemas/Billing"},"company_name":{"maxLength":100,"type":"string","description":"Company name of the customer. **Required** when `billing.first_name` and `billing.last_name` are not provided."},"company_registration_number":{"maxLength":24,"type":"string","description":"Unique identifier of the company recognised by the government. Known as CoC (Chamber of Commerce) number in some countries."},"email_address":{"maxLength":255,"type":"string","format":"email","description":"Consumer's email address.\n\n**Field required for:** Klarna, PayPal\n\n**Note:** Required for 3DS. Please refer to the 3D Secure API specification for format requirements."},"entity_id":{"type":"string","description":"Entity ID on which the customer is created. The Entity ID can be found at the organisation level as Organisation ID (`Administration > Organizations > [Organization] > Organisation ID`)."},"phone_number":{"maxLength":25,"pattern":"^[0-9\\s\\-+().-]+$","type":"string","description":"Cardholder's phone number."},"shipping":{"$ref":"#/components/schemas/Shipping"},"title":{"pattern":"^[a-zA-Z\\-\\s.]+$","maxLength":120,"type":"string","description":"Customer's title (e.g. `Mr`, `Mrs`, `Dr`)."},"work_phone":{"maxLength":25,"pattern":"^[0-9\\s\\-+().-]+$","type":"string","description":"Consumer's work phone number."},"tax":{"$ref":"#/components/schemas/Tax"},"language":{"type":"string","description":"Customer language preference for Invoice documents. See [Localisation](https://docs.verifone.com/online-payments/checkout/localization) for details."}}},"Billing":{"type":"object","properties":{"address_1":{"maxLength":40,"type":"string","description":"Customer's primary billing address information.\n\n**Note:** Required for 3DS. Please refer to the 3D Secure API specification for format requirements."},"address_2":{"maxLength":40,"type":"string","description":"Customer's secondary billing address information."},"address_3":{"maxLength":40,"type":"string","description":"Customer's third billing address information."},"city":{"maxLength":28,"type":"string","description":"Customer's city on their billing address.\n\n**Note:** Required for 3DS. Please refer to the 3D Secure API specification for format requirements."},"country_code":{"type":"string","description":"Customer's alpha-2 ISO 3166 country code (e.g. `US` for United States).\n\n**Note:** Required for 3DS. Please refer to the 3D Secure API specification for format requirements."},"first_name":{"maxLength":22,"type":"string","description":"Customer's first name. **Required** when `company_name` is not provided.\n\n**Note:** Required for 3DS. Please refer to the 3D Secure API specification for format requirements."},"middle_name":{"maxLength":22,"type":"string","description":"Customer's middle name."},"last_name":{"maxLength":22,"type":"string","description":"Customer's last name. **Required** when `company_name` is not provided.\n\n**Note:** Required for 3DS. Please refer to the 3D Secure API specification for format requirements."},"phone":{"maxLength":25,"pattern":"^[0-9\\s\\-+().-]+$","type":"string","description":"Customer's phone number for the billing address."},"postal_code":{"maxLength":10,"type":"string","description":"Customer's postal code for their billing address.\n\n**Note:** Required for 3DS unless a market or regional mandate restricts sending this information."},"state":{"maxLength":35,"type":"string","description":"Customer's state or province for their billing address (e.g. `OH` for Ohio, `TX` for Texas)."}}},"Shipping":{"type":"object","properties":{"address_1":{"maxLength":40,"type":"string","description":"Consumer's primary shipping address information.\n\n**Field required for:** Klarna, PayPal, Vipps, MobilePay, Google Pay, Apple Pay, Affirm, Swish"},"address_2":{"maxLength":40,"type":"string","description":"Consumer's secondary shipping address information.\n\n**Field required for:** PayPal"},"address_3":{"maxLength":40,"type":"string","description":"Consumer's third shipping address information."},"city":{"maxLength":28,"type":"string","description":"Consumer's city on their shipping address.\n\n**Field required for:** Klarna, PayPal, Vipps, MobilePay, Google Pay, Apple Pay, Affirm, Swish"},"first_name":{"maxLength":22,"type":"string","description":"Consumer's first name.\n\n**Field required for:** Klarna, Vipps, MobilePay"},"middle_name":{"maxLength":22,"type":"string","description":"Consumer's middle name."},"last_name":{"maxLength":22,"type":"string","description":"Consumer's last name.\n\n**Field required for:** Klarna, Vipps, MobilePay"},"phone":{"maxLength":25,"pattern":"^[0-9\\s\\-+().-]+$","type":"string","description":"Consumer's phone number for the shipping address.\n\n**Field required for:** Klarna, PayPal, Vipps, MobilePay"},"country_code":{"type":"string","description":"Consumer's alpha-2 ISO 3166 country code (e.g. `US` for United States).\n\n**Field required for:** Klarna, PayPal, Vipps, MobilePay, Google Pay, Apple Pay, Affirm, Swish"},"postal_code":{"maxLength":10,"type":"string","description":"Consumer's postal code for their shipping address.\n\n**Field required for:** Klarna, PayPal, Vipps, MobilePay, Google Pay, Apple Pay, Affirm, Swish"},"state":{"maxLength":35,"type":"string","description":"Consumer's state or province for their shipping address (e.g. `OH` for Ohio, `TX` for Texas).\n\n**Field required for:** Klarna, PayPal"}}},"Tax":{"type":"object","properties":{"identifier":{"pattern":"^[0-9]+$","type":"string","maxLength":9,"description":"An optional identifier of the document recipient:\n\n- Personal ID (for individuals)\n- Tax identification number (for businesses)"}}},"CustomerResponse":{"required":["created_at","entity_id","id","updated_at"],"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Customer UUID."},"billing":{"$ref":"#/components/schemas/Billing"},"company_name":{"maxLength":100,"type":"string","description":"Company name of the customer. **Required** when `billing.first_name` and `billing.last_name` are not provided."},"company_registration_number":{"maxLength":24,"type":"string","description":"Unique identifier of the company recognised by the government. Known as CoC (Chamber of Commerce) number in some countries."},"email_address":{"maxLength":255,"type":"string","format":"email","description":"Consumer's email address.\n\n**Note:** Required for 3DS. Please refer to the 3D Secure API specification for format requirements."},"entity_id":{"type":"string","description":"Entity ID on which the customer is created."},"phone_number":{"maxLength":25,"pattern":"^[0-9\\s\\-+().-]+$","type":"string","description":"Cardholder's phone number."},"shipping":{"$ref":"#/components/schemas/Shipping"},"title":{"pattern":"^[a-zA-Z\\-\\s.]+$","maxLength":120,"type":"string","description":"Customer's title (e.g. `Mr`, `Mrs`, `Dr`)."},"work_phone":{"maxLength":25,"pattern":"^[0-9\\s\\-+().-]+$","type":"string","description":"Consumer's work phone number."},"tax":{"$ref":"#/components/schemas/Tax"},"language":{"type":"string","description":"Customer language preference for Invoice documents. See [Localisation](https://docs.verifone.com/online-payments/checkout/localization) for details."},"created_at":{"type":"string","format":"date-time","description":"Timestamp when this customer was created."},"updated_at":{"type":"string","format":"date-time","description":"Timestamp when this customer was last updated."}}},"ErrorResponse":{"type":"object","properties":{"code":{"type":"integer","description":"A 3-digit code that uniquely identifies the error."},"details":{"type":"object","description":"Additional error details."},"message":{"type":"string","description":"A human-readable description of the error."},"timestamp":{"type":"integer","description":"Unix timestamp of when the error occurred."}}}}},"paths":{"/v2/customer":{"post":{"tags":["Customer"],"summary":"Create Customer","operationId":"postV2Customer","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerRequest"}}},"required":true},"responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

### Request field reference

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

| Field                                    | Type   | Notes                                                                                                                        |
| ---------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `entity_id` ✅                            | string | Entity ID on which the customer is created. Found under `Administration > Organizations > [Organization] > Organisation ID`. |
| `billing.first_name` or `company_name` ✅ | string | One of these is required. Use `company_name` for business customers.                                                         |
| `billing.last_name` ✅                    | string | Required when `company_name` is not provided.                                                                                |
| {% endtab %}                             |        |                                                                                                                              |

{% tab title="Optional" %}

| Field                         | Type           | Max length | Notes                                                                                                                                    |
| ----------------------------- | -------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `email_address`               | string (email) | 255        | Required for Klarna, PayPal, and 3DS flows.                                                                                              |
| `phone_number`                | string         | 25         | Pattern: digits, spaces, `- + ( ) .`                                                                                                     |
| `work_phone`                  | string         | 25         | Pattern: digits, spaces, `- + ( ) .`                                                                                                     |
| `title`                       | string         | 120        | e.g. `Mr`, `Mrs`, `Dr`. Letters, hyphens, spaces, periods.                                                                               |
| `company_name`                | string         | 100        | Required when `billing.first_name` / `billing.last_name` are omitted.                                                                    |
| `company_registration_number` | string         | 24         | CoC (Chamber of Commerce) number.                                                                                                        |
| `language`                    | string         | —          | Customer language preference for invoice documents. See [Localisation](https://docs.verifone.com/online-payments/checkout/localization). |
| `billing`                     | object         | —          | See Billing object below.                                                                                                                |
| `shipping`                    | object         | —          | See Shipping object below.                                                                                                               |
| `tax`                         | object         | —          | Tax identifier for the document recipient.                                                                                               |
| {% endtab %}                  |                |            |                                                                                                                                          |

{% tab title="Billing object" %}

| Field                  | Type   | Max length | 3DS required?                                |
| ---------------------- | ------ | ---------- | -------------------------------------------- |
| `billing.first_name`   | string | 22         | ✅ Yes                                        |
| `billing.last_name`    | string | 22         | ✅ Yes                                        |
| `billing.middle_name`  | string | 22         | —                                            |
| `billing.address_1`    | string | 40         | ✅ Yes                                        |
| `billing.address_2`    | string | 40         | —                                            |
| `billing.address_3`    | string | 40         | —                                            |
| `billing.city`         | string | 28         | ✅ Yes                                        |
| `billing.postal_code`  | string | 10         | ✅ Yes (unless regional mandate restricts it) |
| `billing.country_code` | string | —          | ✅ Yes — ISO 3166 alpha-2 (e.g. `US`, `GB`)   |
| `billing.state`        | string | 35         | — e.g. `OH`, `TX`                            |
| `billing.phone`        | string | 25         | —                                            |
| {% endtab %}           |        |            |                                              |

{% tab title="Shipping object" %}

| Field                   | Required for                                                           | Max length |
| ----------------------- | ---------------------------------------------------------------------- | ---------- |
| `shipping.address_1`    | Klarna, PayPal, Vipps, MobilePay, Google Pay, Apple Pay, Affirm, Swish | 40         |
| `shipping.address_2`    | PayPal                                                                 | 40         |
| `shipping.address_3`    | —                                                                      | 40         |
| `shipping.city`         | Klarna, PayPal, Vipps, MobilePay, Google Pay, Apple Pay, Affirm, Swish | 28         |
| `shipping.first_name`   | Klarna, Vipps, MobilePay                                               | 22         |
| `shipping.middle_name`  | —                                                                      | 22         |
| `shipping.last_name`    | Klarna, Vipps, MobilePay                                               | 22         |
| `shipping.phone`        | Klarna, PayPal, Vipps, MobilePay                                       | 25         |
| `shipping.country_code` | Klarna, PayPal, Vipps, MobilePay, Google Pay, Apple Pay, Affirm, Swish | —          |
| `shipping.postal_code`  | Klarna, PayPal, Vipps, MobilePay, Google Pay, Apple Pay, Affirm, Swish | 10         |
| `shipping.state`        | Klarna, PayPal                                                         | 35         |
| {% endtab %}            |                                                                        |            |
| {% endtabs %}           |                                                                        |            |

### Response — capturing the customer UUID

A successful `200` response returns a `CustomerResponse` object. The most important field is `id`:

```
CustomerResponse
  └── id   ← Customer UUID (store this)
  └── entity_id
  └── billing { ... }
  └── shipping { ... }
  └── created_at
  └── updated_at
```

{% hint style="warning" %}
Store the returned `id` (Customer UUID) immediately. You will need it to pass the customer record to Checkout, Ecom, or 3DS requests, and to retrieve, update, or delete the record later.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.verifone.com/api-reference/open-api-references/customer/list-create-customers.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.