• Example searches: “transaction”, “CreateOrder”, “/v2/locations”, “inventory”, “delete customer”

You are viewing an old version of the API
Create customer

POST /v2/customers

Creates a new customer for a business.

You must provide at least one of the following values in your request to this endpoint:

  • given_name
  • family_name
  • company_name
  • email_address
  • phone_number
Permissions
CUSTOMERS_WRITE
Guide
Create a customer profile Try in API Explorer

Request Body

Example code
Name Description
idempotency_key
string

The idempotency key for the request. For more information, see Idempotency.
given_name
string

The given name (that is, the first name) associated with the customer profile.

The maximum length for this value is 300 characters.
family_name
string

The family name (that is, the last name) associated with the customer profile.

The maximum length for this value is 300 characters.
company_name
string

A business name associated with the customer profile.

The maximum length for this value is 500 characters.
nickname
string

A nickname for the customer profile.

The maximum length for this value is 100 characters.
email_address
string

The email address associated with the customer profile.

The maximum length for this value is 254 characters.
address
Address

The physical address associated with the customer profile. For maximum length constraints, see Customer addresses. The first_name and last_name fields are ignored if they are present in the request.
phone_number
string

The phone number associated with the customer profile. The phone number must be valid and can contain 9–16 digits, with an optional + prefix and country code. For more information, see Customer phone numbers.
reference_id
string

An optional second ID used to associate the customer profile with an entity in another system.

The maximum length for this value is 100 characters.
note
string

A custom note associated with the customer profile.
birthday
string

The birthday associated with the customer profile, in YYYY-MM-DD or MM-DD format. For example, specify 1998-09-21 for September 21, 1998, or 09-21 for September 21. Birthdays are returned in YYYY-MM-DD format, where YYYY is the specified birth year or 0000 if a birth year is not specified.
tax_ids
CustomerTaxIds

The tax ID associated with the customer profile. This field is available only for customers of sellers in EU countries or the United Kingdom. In other countries, this field is ignored when included in a CreateCustomer request. For more information, see Customer tax IDs.

Response Fields
Name Description
errors
Error [ ]

Any errors that occurred during the request.
customer
Customer

The created customer.

Examples

You are viewing an old version of the API
POST /v2/customers
cURL
  • cURL
  • Ruby
  • Python
  • C#
  • Java
  • PHP
  • Node.js 
curl https://connect.squareup.com/v2/customers \
  -X POST \
  -H 'Square-Version: 2023-01-19' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "given_name": "Amelia",
    "family_name": "Earhart",
    "email_address": "Amelia.Earhart@example.com",
    "address": {
      "address_line_1": "500 Electric Ave",
      "address_line_2": "Suite 600",
      "locality": "New York",
      "administrative_district_level_1": "NY",
      "postal_code": "10003",
      "country": "US"
    },
    "phone_number": "+1-212-555-4240",
    "reference_id": "YOUR_REFERENCE_ID",
    "note": "a customer"
  }'
Response JSON 
{
  "customer": {
    "id": "JDKYHBWT1D4F8MFH63DBMEN8Y4",
    "created_at": "2016-03-23T20:21:54.859Z",
    "updated_at": "2016-03-23T20:21:54.859Z",
    "given_name": "Amelia",
    "family_name": "Earhart",
    "email_address": "Amelia.Earhart@example.com",
    "address": {
      "address_line_1": "500 Electric Ave",
      "address_line_2": "Suite 600",
      "locality": "New York",
      "administrative_district_level_1": "NY",
      "postal_code": "10003",
      "country": "US"
    },
    "phone_number": "+1-212-555-4240",
    "reference_id": "YOUR_REFERENCE_ID",
    "note": "a customer",
    "preferences": {
      "email_unsubscribed": false
    },
    "creation_source": "THIRD_PARTY",
    "version": 0
  }
}

Error Descriptions
400 Bad request INVALID_EMAIL_ADDRESS

The provided email address is invalid.

 >
400 Bad request INVALID_PHONE_NUMBER

The provided phone number is invalid.

 >
400 Bad request 
{
  "errors": [
    {
      "code": "INVALID_EMAIL_ADDRESS",
      "category": "INVALID_REQUEST_ERROR"
    }
  ]
}