--- title: "CreateCustomer" method: POST path: "/v2/customers" tags: ["Customers"] --- # CreateCustomer `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` ## Request body - CreateCustomerRequest — Defines the body parameters that can be included in a request to the `CreateCustomer` endpoint. - `address` Address — Represents a postal address in a country. The address format is based on an [open-source library from Google](https://github.com/google/libaddressinput). For more information, see [AddressValidationMetadata](https://github.com/google/libaddressinput/wiki/AddressValidationMetadata). This format has dedicated fields for four address components: postal code, locality (city), administrative district (state, prefecture, or province), and sublocality (town or village). These components have dedicated fields in the `Address` object because software sometimes behaves differently based on them. For example, sales tax software may charge different amounts of sales tax based on the postal code, and some software is only available in certain states due to compliance reasons. For the remaining address components, the `Address` type provides the `address_line_1` and `address_line_2` fields for free-form data entry. These fields are free-form because the remaining address components have too many variations around the world and typical software does not parse these components. These fields enable users to enter anything they want. Note that, in the current implementation, all other `Address` type fields are blank. These include `address_line_3`, `sublocality_2`, `sublocality_3`, `administrative_district_level_2`, `administrative_district_level_3`, `first_name`, `last_name`, and `organization`. When it comes to localization, the seller's language preferences (see [Language preferences](https://developer.squareup.com/docs/locations-api#location-specific-and-seller-level-language-preferences)) are ignored for addresses. Even though Square products (such as Square Point of Sale and the Seller Dashboard) mostly use a seller's language preference in communication, when it comes to addresses, they will use English for a US address, Japanese for an address in Japan, and so on. - `address_line_1` string — The first line of the address. Fields that start with `address_line` provide the address's most specific details, like street number, street name, and building name. They do *not* provide less specific details like city, state/province, or country (these details are provided in other fields). - `address_line_2` string — The second line of the address, if any. - `address_line_3` string — The third line of the address, if any. - `administrative_district_level_1` string — A civil entity within the address's country. In the US, this is the state. - `administrative_district_level_2` string — A civil entity within the address's `administrative_district_level_1`. In the US, this is the county. - `administrative_district_level_3` string — A civil entity within the address's `administrative_district_level_2`, if any. - `country` string — The address's country, in ISO 3166-1-alpha-2 format. - `first_name` string — Optional first name when it's representing recipient. - `last_name` string — Optional last name when it's representing recipient. - `locality` string — The city or town of the address. - `organization` string — Optional organization name when it's representing recipient. - `postal_code` string — The address's postal code. - `sublocality` string — A civil region within the address's `locality`, if any. - `sublocality_2` string — A civil region within the address's `sublocality`, if any. - `sublocality_3` string — A civil region within the address's `sublocality_2`, if any. - `birthday` string — The birthday associated with the customer profile, in RFC 3339 format. The year is optional. The timezone and time are not allowed. For example, `0000-09-21T00:00:00-00:00` represents a birthday on September 21 and `1998-09-21T00:00:00-00:00` represents a birthday on September 21, 1998. You can also specify this value in `YYYY-MM-DD` format. - `company_name` string — A business name associated with the customer profile. - `email_address` string — The email address associated with the customer profile. - `family_name` string — The family name (that is, the last name) associated with the customer profile. - `given_name` string — The given name (that is, the first name) associated with the customer profile. - `idempotency_key` string — The idempotency key for the request. For more information, see [Idempotency](https://developer.squareup.com/docs/working-with-apis/idempotency). - `nickname` string — A nickname for the customer profile. - `note` string — A custom note associated with the customer profile. - `phone_number` string — The 11-digit phone number associated with the customer profile. - `reference_id` string — An optional second ID used to associate the customer profile with an entity in another system. ## Response `200` Success - CreateCustomerResponse — Defines the fields that are included in the response body of a request to the `CreateCustomer` endpoint. Either `errors` or `customer` is present in a given response (never both). - `customer` Customer — Represents a Square customer profile in the Customer Directory of a Square seller. - `address` Address — Represents a postal address in a country. The address format is based on an [open-source library from Google](https://github.com/google/libaddressinput). For more information, see [AddressValidationMetadata](https://github.com/google/libaddressinput/wiki/AddressValidationMetadata). This format has dedicated fields for four address components: postal code, locality (city), administrative district (state, prefecture, or province), and sublocality (town or village). These components have dedicated fields in the `Address` object because software sometimes behaves differently based on them. For example, sales tax software may charge different amounts of sales tax based on the postal code, and some software is only available in certain states due to compliance reasons. For the remaining address components, the `Address` type provides the `address_line_1` and `address_line_2` fields for free-form data entry. These fields are free-form because the remaining address components have too many variations around the world and typical software does not parse these components. These fields enable users to enter anything they want. Note that, in the current implementation, all other `Address` type fields are blank. These include `address_line_3`, `sublocality_2`, `sublocality_3`, `administrative_district_level_2`, `administrative_district_level_3`, `first_name`, `last_name`, and `organization`. When it comes to localization, the seller's language preferences (see [Language preferences](https://developer.squareup.com/docs/locations-api#location-specific-and-seller-level-language-preferences)) are ignored for addresses. Even though Square products (such as Square Point of Sale and the Seller Dashboard) mostly use a seller's language preference in communication, when it comes to addresses, they will use English for a US address, Japanese for an address in Japan, and so on. - `address_line_1` string — The first line of the address. Fields that start with `address_line` provide the address's most specific details, like street number, street name, and building name. They do *not* provide less specific details like city, state/province, or country (these details are provided in other fields). - `address_line_2` string — The second line of the address, if any. - `address_line_3` string — The third line of the address, if any. - `administrative_district_level_1` string — A civil entity within the address's country. In the US, this is the state. - `administrative_district_level_2` string — A civil entity within the address's `administrative_district_level_1`. In the US, this is the county. - `administrative_district_level_3` string — A civil entity within the address's `administrative_district_level_2`, if any. - `country` string — The address's country, in ISO 3166-1-alpha-2 format. - `first_name` string — Optional first name when it's representing recipient. - `last_name` string — Optional last name when it's representing recipient. - `locality` string — The city or town of the address. - `organization` string — Optional organization name when it's representing recipient. - `postal_code` string — The address's postal code. - `sublocality` string — A civil region within the address's `locality`, if any. - `sublocality_2` string — A civil region within the address's `sublocality`, if any. - `sublocality_3` string — A civil region within the address's `sublocality_2`, if any. - `birthday` string — The birthday associated with the customer profile, in RFC 3339 format. The year is optional. The timezone and time are not allowed. For example, `0000-09-21T00:00:00-00:00` represents a birthday on September 21 and `1998-09-21T00:00:00-00:00` represents a birthday on September 21, 1998. - `cards` Card[] — Payment details of the credit, debit, and gift cards stored on file for the customer profile. DEPRECATED at version 2021-06-16. Replaced by calling [ListCards](https://developer.squareup.com/reference/square_2021-08-18/cards-api/list-cards) (for credit and debit cards on file) or [ListGiftCards](https://developer.squareup.com/reference/square_2021-08-18/gift-cards-api/list-gift-cards) (for gift cards on file) and including the `customer_id` query parameter. For more information, see [Migrate to the Cards API and Gift Cards API](https://developer.squareup.com/docs/customers-api/use-the-api/integrate-with-other-services#migrate-customer-cards). - `billing_address` Address — Represents a postal address in a country. The address format is based on an [open-source library from Google](https://github.com/google/libaddressinput). For more information, see [AddressValidationMetadata](https://github.com/google/libaddressinput/wiki/AddressValidationMetadata). This format has dedicated fields for four address components: postal code, locality (city), administrative district (state, prefecture, or province), and sublocality (town or village). These components have dedicated fields in the `Address` object because software sometimes behaves differently based on them. For example, sales tax software may charge different amounts of sales tax based on the postal code, and some software is only available in certain states due to compliance reasons. For the remaining address components, the `Address` type provides the `address_line_1` and `address_line_2` fields for free-form data entry. These fields are free-form because the remaining address components have too many variations around the world and typical software does not parse these components. These fields enable users to enter anything they want. Note that, in the current implementation, all other `Address` type fields are blank. These include `address_line_3`, `sublocality_2`, `sublocality_3`, `administrative_district_level_2`, `administrative_district_level_3`, `first_name`, `last_name`, and `organization`. When it comes to localization, the seller's language preferences (see [Language preferences](https://developer.squareup.com/docs/locations-api#location-specific-and-seller-level-language-preferences)) are ignored for addresses. Even though Square products (such as Square Point of Sale and the Seller Dashboard) mostly use a seller's language preference in communication, when it comes to addresses, they will use English for a US address, Japanese for an address in Japan, and so on. - `address_line_1` string — The first line of the address. Fields that start with `address_line` provide the address's most specific details, like street number, street name, and building name. They do *not* provide less specific details like city, state/province, or country (these details are provided in other fields). - `address_line_2` string — The second line of the address, if any. - `address_line_3` string — The third line of the address, if any. - `administrative_district_level_1` string — A civil entity within the address's country. In the US, this is the state. - `administrative_district_level_2` string — A civil entity within the address's `administrative_district_level_1`. In the US, this is the county. - `administrative_district_level_3` string — A civil entity within the address's `administrative_district_level_2`, if any. - `country` string — The address's country, in ISO 3166-1-alpha-2 format. - `first_name` string — Optional first name when it's representing recipient. - `last_name` string — Optional last name when it's representing recipient. - `locality` string — The city or town of the address. - `organization` string — Optional organization name when it's representing recipient. - `postal_code` string — The address's postal code. - `sublocality` string — A civil region within the address's `locality`, if any. - `sublocality_2` string — A civil region within the address's `sublocality`, if any. - `sublocality_3` string — A civil region within the address's `sublocality_2`, if any. - `bin` string — The first six digits of the card number, known as the Bank Identification Number (BIN). Only the Payments API returns this field. - `card_brand` string — The card's brand. - `card_type` string — The type of the card. The Card object includes this field only in response to Payments API calls. - `cardholder_name` string — The name of the cardholder. - `customer_id` string — The ID of a customer created using the Customers API to be associated with the card. - `enabled` boolean — Indicates whether or not a card can be used for payments. - `exp_month` integer — The expiration month of the associated card as an integer between 1 and 12. - `exp_year` integer — The four-digit year of the card's expiration date. - `fingerprint` string — __Not currently set.__ Intended as a Square-assigned identifier, based on the card number, to identify the card across multiple locations within a single application. - `id` string — Unique ID for this card. Generated by Square. - `last_4` string — The last 4 digits of the card number. - `prepaid_type` string — Indicates whether the Card is prepaid or not. The Card object includes this field only in response to Payments API calls. - `reference_id` string — An optional user-defined reference ID that associates this card with another entity in an external system. For example, a customer ID from an external customer management system. - `version` integer — Current version number of the card. Increments with each card update. Requests to update an existing Card object will be rejected unless the version in the request matches the current version for the Card. - `company_name` string — A business name associated with the customer profile. - `created_at` string — The timestamp when the customer profile was created, in RFC 3339 format. - `creation_source` string — A creation source represents the method used to create the customer profile. - `email_address` string — The email address associated with the customer profile. - `family_name` string — The family (i.e., last) name associated with the customer profile. - `given_name` string — The given (i.e., first) name associated with the customer profile. - `group_ids` string[] — The IDs of customer groups the customer belongs to. - `id` string — A unique Square-assigned ID for the customer profile. - `nickname` string — A nickname for the customer profile. - `note` string — A custom note associated with the customer profile. - `phone_number` string — The 11-digit phone number associated with the customer profile. - `preferences` CustomerPreferences — Represents communication preferences for the customer profile. - `email_unsubscribed` boolean — Indicates whether the customer has unsubscribed from marketing campaign emails. A value of `true` means that the customer chose to opt out of email marketing from the current Square seller or from all Square sellers. This value is read-only from the Customers API. - `reference_id` string — An optional second ID used to associate the customer profile with an entity in another system. - `segment_ids` string[] — The IDs of segments the customer belongs to. - `updated_at` string — The timestamp when the customer profile was last updated, in RFC 3339 format. - `version` integer — The Square-assigned version number of the customer profile. The version number is incremented each time an update is committed to the customer profile, except for changes to customer segment membership and cards on file. - `errors` Error[] — Any errors that occurred during the request. - `category` string, required — The high-level category for the error. - `code` string, required — The specific code of the error. - `detail` string — A human-readable description of the error for debugging purposes. - `field` string — The name of the field provided in the original request (if any) that the error pertains to. --- [API](https://skmtc.net/square/apis/squareup.md) · [All operations](https://skmtc.net/square/apis/squareup/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/square/squareup/revisions/8d95e3639487/schema)