--- 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. - `idempotency_key` string — The idempotency key for the request. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/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 — Represents a postal address in a country. For more information, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses). - `address_line_1` string, nullable — 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, nullable — The second line of the address, if any. - `address_line_3` string, nullable — The third line of the address, if any. - `locality` string, nullable — The city or town of the address. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses). - `sublocality` string, nullable — A civil region within the address's `locality`, if any. - `sublocality_2` string, nullable — A civil region within the address's `sublocality`, if any. - `sublocality_3` string, nullable — A civil region within the address's `sublocality_2`, if any. - `administrative_district_level_1` string, nullable — A civil entity within the address's country. In the US, this is the state. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses). - `administrative_district_level_2` string, nullable — A civil entity within the address's `administrative_district_level_1`. In the US, this is the county. - `administrative_district_level_3` string, nullable — A civil entity within the address's `administrative_district_level_2`, if any. - `postal_code` string, nullable — The address's postal code. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses). - `country` 'ZZ' | 'AD' | 'AE' | 'AF' | 'AG' | 'AI' | 'AL' | 'AM' | 'AO' | 'AQ' | 'AR' | 'AS' | 'AT' | 'AU' | 'AW' | 'AX' | 'AZ' | 'BA' | 'BB' | 'BD' | 'BE' | 'BF' | 'BG' | 'BH' | 'BI' | 'BJ' | 'BL' | 'BM' | 'BN' | 'BO' | 'BQ' | 'BR' | 'BS' | 'BT' | 'BV' | 'BW' | 'BY' | 'BZ' | 'CA' | 'CC' | 'CD' | 'CF' | 'CG' | 'CH' | 'CI' | 'CK' | 'CL' | 'CM' | 'CN' | 'CO' | 'CR' | 'CU' | 'CV' | 'CW' | 'CX' | 'CY' | 'CZ' | 'DE' | 'DJ' | 'DK' | 'DM' | 'DO' | 'DZ' | 'EC' | 'EE' | 'EG' | 'EH' | 'ER' | 'ES' | 'ET' | 'FI' | 'FJ' | 'FK' | 'FM' | 'FO' | 'FR' | 'GA' | 'GB' | 'GD' | 'GE' | 'GF' | 'GG' | 'GH' | 'GI' | 'GL' | 'GM' | 'GN' | 'GP' | 'GQ' | 'GR' | 'GS' | 'GT' | 'GU' | 'GW' | 'GY' | 'HK' | 'HM' | 'HN' | 'HR' | 'HT' | 'HU' | 'ID' | 'IE' | 'IL' | 'IM' | 'IN' | 'IO' | 'IQ' | 'IR' | 'IS' | 'IT' | 'JE' | 'JM' | 'JO' | 'JP' | 'KE' | 'KG' | 'KH' | 'KI' | 'KM' | 'KN' | 'KP' | 'KR' | 'KW' | 'KY' | 'KZ' | 'LA' | 'LB' | 'LC' | 'LI' | 'LK' | 'LR' | 'LS' | 'LT' | 'LU' | 'LV' | 'LY' | 'MA' | 'MC' | 'MD' | 'ME' | 'MF' | 'MG' | 'MH' | 'MK' | 'ML' | 'MM' | 'MN' | 'MO' | 'MP' | 'MQ' | 'MR' | 'MS' | 'MT' | 'MU' | 'MV' | 'MW' | 'MX' | 'MY' | 'MZ' | 'NA' | 'NC' | 'NE' | 'NF' | 'NG' | 'NI' | 'NL' | 'NO' | 'NP' | 'NR' | 'NU' | 'NZ' | 'OM' | 'PA' | 'PE' | 'PF' | 'PG' | 'PH' | 'PK' | 'PL' | 'PM' | 'PN' | 'PR' | 'PS' | 'PT' | 'PW' | 'PY' | 'QA' | 'RE' | 'RO' | 'RS' | 'RU' | 'RW' | 'SA' | 'SB' | 'SC' | 'SD' | 'SE' | 'SG' | 'SH' | 'SI' | 'SJ' | 'SK' | 'SL' | 'SM' | 'SN' | 'SO' | 'SR' | 'SS' | 'ST' | 'SV' | 'SX' | 'SY' | 'SZ' | 'TC' | 'TD' | 'TF' | 'TG' | 'TH' | 'TJ' | 'TK' | 'TL' | 'TM' | 'TN' | 'TO' | 'TR' | 'TT' | 'TV' | 'TW' | 'TZ' | 'UA' | 'UG' | 'UM' | 'US' | 'UY' | 'UZ' | 'VA' | 'VC' | 'VE' | 'VG' | 'VI' | 'VN' | 'VU' | 'WF' | 'WS' | 'YE' | 'YT' | 'ZA' | 'ZM' | 'ZW' — Indicates the country associated with another entity, such as a business. Values are in [ISO 3166-1-alpha-2 format](http://www.iso.org/iso/home/standards/country_codes.htm). - `first_name` string, nullable — Optional first name when it's representing recipient. - `last_name` string, nullable — Optional last name when it's representing recipient. - `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](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#phone-number). - `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 — Represents the tax ID associated with a [customer profile](entity:Customer). The corresponding `tax_ids` field is available only for customers of sellers in EU countries or the United Kingdom. For more information, see [Customer tax IDs](https://developer.squareup.com/docs/customers-api/what-it-does#customer-tax-ids). - `eu_vat` string, nullable — The EU VAT identification number for the customer. For example, `IE3426675K`. The ID can contain alphanumeric characters only. ## Response `200` Success - CreateCustomerResponse — Defines the fields that are included in the response body of a request to the [CreateCustomer](api-endpoint:Customers-CreateCustomer) or [BulkCreateCustomers](api-endpoint:Customers-BulkCreateCustomers) endpoint. Either `errors` or `customer` is present in a given response (never both). - `errors` Error[] — Any errors that occurred during the request. - `category` 'API_ERROR' | 'AUTHENTICATION_ERROR' | 'INVALID_REQUEST_ERROR' | 'RATE_LIMIT_ERROR' | 'PAYMENT_METHOD_ERROR' | 'REFUND_ERROR' | 'MERCHANT_SUBSCRIPTION_ERROR' | 'EXTERNAL_VENDOR_ERROR', required — Indicates which high-level category of error has occurred during a request to the Connect API. - `code` 'INTERNAL_SERVER_ERROR' | 'UNAUTHORIZED' | 'ACCESS_TOKEN_EXPIRED' | 'ACCESS_TOKEN_REVOKED' | 'CLIENT_DISABLED' | 'FORBIDDEN' | 'INSUFFICIENT_SCOPES' | 'APPLICATION_DISABLED' | 'V1_APPLICATION' | 'V1_ACCESS_TOKEN' | 'CARD_PROCESSING_NOT_ENABLED' | 'MERCHANT_SUBSCRIPTION_NOT_FOUND' | 'BAD_REQUEST' | 'MISSING_REQUIRED_PARAMETER' | 'INCORRECT_TYPE' | 'INVALID_TIME' | 'INVALID_TIME_RANGE' | 'INVALID_VALUE' | 'INVALID_CURSOR' | 'UNKNOWN_QUERY_PARAMETER' | 'CONFLICTING_PARAMETERS' | 'EXPECTED_JSON_BODY' | 'INVALID_SORT_ORDER' | 'VALUE_REGEX_MISMATCH' | 'VALUE_TOO_SHORT' | 'VALUE_TOO_LONG' | 'VALUE_TOO_LOW' | 'VALUE_TOO_HIGH' | 'VALUE_EMPTY' | 'ARRAY_LENGTH_TOO_LONG' | 'ARRAY_LENGTH_TOO_SHORT' | 'ARRAY_EMPTY' | 'EXPECTED_BOOLEAN' | 'EXPECTED_INTEGER' | 'EXPECTED_FLOAT' | 'EXPECTED_STRING' | 'EXPECTED_OBJECT' | 'EXPECTED_ARRAY' | 'EXPECTED_MAP' | 'EXPECTED_BASE64_ENCODED_BYTE_ARRAY' | 'INVALID_ARRAY_VALUE' | 'INVALID_ENUM_VALUE' | 'INVALID_CONTENT_TYPE' | 'INVALID_FORM_VALUE' | 'CUSTOMER_NOT_FOUND' | 'ONE_INSTRUMENT_EXPECTED' | 'NO_FIELDS_SET' | 'TOO_MANY_MAP_ENTRIES' | 'MAP_KEY_LENGTH_TOO_SHORT' | 'MAP_KEY_LENGTH_TOO_LONG' | 'CUSTOMER_MISSING_NAME' | 'CUSTOMER_MISSING_EMAIL' | 'INVALID_PAUSE_LENGTH' | 'INVALID_DATE' | 'UNSUPPORTED_COUNTRY' | 'UNSUPPORTED_CURRENCY' | 'APPLE_TTP_PIN_TOKEN' | 'CARD_EXPIRED' | 'INVALID_EXPIRATION' | 'INVALID_EXPIRATION_YEAR' | 'INVALID_EXPIRATION_DATE' | 'UNSUPPORTED_CARD_BRAND' | 'UNSUPPORTED_ENTRY_METHOD' | 'INVALID_ENCRYPTED_CARD' | 'INVALID_CARD' | 'PAYMENT_AMOUNT_MISMATCH' | 'GENERIC_DECLINE' | 'CVV_FAILURE' | 'ADDRESS_VERIFICATION_FAILURE' | 'INVALID_ACCOUNT' | 'CURRENCY_MISMATCH' | 'INSUFFICIENT_FUNDS' | 'INSUFFICIENT_PERMISSIONS' | 'CARDHOLDER_INSUFFICIENT_PERMISSIONS' | 'INVALID_LOCATION' | 'TRANSACTION_LIMIT' | 'VOICE_FAILURE' | 'PAN_FAILURE' | 'EXPIRATION_FAILURE' | 'CARD_NOT_SUPPORTED' | 'READER_DECLINED' | 'INVALID_PIN' | 'MISSING_PIN' | 'MISSING_ACCOUNT_TYPE' | 'INVALID_POSTAL_CODE' | 'INVALID_FEES' | 'MANUALLY_ENTERED_PAYMENT_NOT_SUPPORTED' | 'PAYMENT_LIMIT_EXCEEDED' | 'GIFT_CARD_AVAILABLE_AMOUNT' | 'ACCOUNT_UNUSABLE' | 'BUYER_REFUSED_PAYMENT' | 'DELAYED_TRANSACTION_EXPIRED' | 'DELAYED_TRANSACTION_CANCELED' | 'DELAYED_TRANSACTION_CAPTURED' | 'DELAYED_TRANSACTION_FAILED' | 'CARD_TOKEN_EXPIRED' | 'CARD_TOKEN_USED' | 'AMOUNT_TOO_HIGH' | 'UNSUPPORTED_INSTRUMENT_TYPE' | 'REFUND_AMOUNT_INVALID' | 'REFUND_ALREADY_PENDING' | 'PAYMENT_NOT_REFUNDABLE' | 'PAYMENT_NOT_REFUNDABLE_DUE_TO_DISPUTE' | 'REFUND_ERROR_PAYMENT_NEEDS_COMPLETION' | 'REFUND_DECLINED' | 'INSUFFICIENT_PERMISSIONS_FOR_REFUND' | 'INVALID_CARD_DATA' | 'SOURCE_USED' | 'SOURCE_EXPIRED' | 'UNSUPPORTED_LOYALTY_REWARD_TIER' | 'LOCATION_MISMATCH' | 'ORDER_UNPAID_NOT_RETURNABLE' | 'PARTIAL_PAYMENT_DELAY_CAPTURE_NOT_SUPPORTED' | 'IDEMPOTENCY_KEY_REUSED' | 'UNEXPECTED_VALUE' | 'SANDBOX_NOT_SUPPORTED' | 'INVALID_EMAIL_ADDRESS' | 'INVALID_PHONE_NUMBER' | 'CHECKOUT_EXPIRED' | 'BAD_CERTIFICATE' | 'INVALID_SQUARE_VERSION_FORMAT' | 'API_VERSION_INCOMPATIBLE' | 'CARD_PRESENCE_REQUIRED' | 'UNSUPPORTED_SOURCE_TYPE' | 'CARD_MISMATCH' | 'PLAID_ERROR' | 'PLAID_ERROR_ITEM_LOGIN_REQUIRED' | 'PLAID_ERROR_RATE_LIMIT' | 'PAYMENT_SOURCE_NOT_ENABLED_FOR_TARGET' | 'CARD_DECLINED' | 'VERIFY_CVV_FAILURE' | 'VERIFY_AVS_FAILURE' | 'CARD_DECLINED_CALL_ISSUER' | 'CARD_DECLINED_VERIFICATION_REQUIRED' | 'BAD_EXPIRATION' | 'CHIP_INSERTION_REQUIRED' | 'ALLOWABLE_PIN_TRIES_EXCEEDED' | 'RESERVATION_DECLINED' | 'UNKNOWN_BODY_PARAMETER' | 'NOT_FOUND' | 'APPLE_PAYMENT_PROCESSING_CERTIFICATE_HASH_NOT_FOUND' | 'METHOD_NOT_ALLOWED' | 'NOT_ACCEPTABLE' | 'REQUEST_TIMEOUT' | 'CONFLICT' | 'GONE' | 'REQUEST_ENTITY_TOO_LARGE' | 'UNSUPPORTED_MEDIA_TYPE' | 'UNPROCESSABLE_ENTITY' | 'RATE_LIMITED' | 'NOT_IMPLEMENTED' | 'BAD_GATEWAY' | 'SERVICE_UNAVAILABLE' | 'TEMPORARY_ERROR' | 'GATEWAY_TIMEOUT', required — Indicates the specific error that occurred during a request to a Square API. - `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. - `customer` Customer — Represents a Square customer profile in the Customer Directory of a Square seller. - `id` string — A unique Square-assigned ID for the customer profile. If you need this ID for an API request, use the ID returned when you created the customer profile or call the [SearchCustomers](api-endpoint:Customers-SearchCustomers) or [ListCustomers](api-endpoint:Customers-ListCustomers) endpoint. - `created_at` string — The timestamp when the customer profile was created, in RFC 3339 format. - `updated_at` string — The timestamp when the customer profile was last updated, in RFC 3339 format. - `given_name` string, nullable — The given name (that is, the first name) associated with the customer profile. - `family_name` string, nullable — The family name (that is, the last name) associated with the customer profile. - `nickname` string, nullable — A nickname for the customer profile. - `company_name` string, nullable — A business name associated with the customer profile. - `email_address` string, nullable — The email address associated with the customer profile. - `address` Address — Represents a postal address in a country. For more information, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses). - `address_line_1` string, nullable — 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, nullable — The second line of the address, if any. - `address_line_3` string, nullable — The third line of the address, if any. - `locality` string, nullable — The city or town of the address. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses). - `sublocality` string, nullable — A civil region within the address's `locality`, if any. - `sublocality_2` string, nullable — A civil region within the address's `sublocality`, if any. - `sublocality_3` string, nullable — A civil region within the address's `sublocality_2`, if any. - `administrative_district_level_1` string, nullable — A civil entity within the address's country. In the US, this is the state. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses). - `administrative_district_level_2` string, nullable — A civil entity within the address's `administrative_district_level_1`. In the US, this is the county. - `administrative_district_level_3` string, nullable — A civil entity within the address's `administrative_district_level_2`, if any. - `postal_code` string, nullable — The address's postal code. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses). - `country` 'ZZ' | 'AD' | 'AE' | 'AF' | 'AG' | 'AI' | 'AL' | 'AM' | 'AO' | 'AQ' | 'AR' | 'AS' | 'AT' | 'AU' | 'AW' | 'AX' | 'AZ' | 'BA' | 'BB' | 'BD' | 'BE' | 'BF' | 'BG' | 'BH' | 'BI' | 'BJ' | 'BL' | 'BM' | 'BN' | 'BO' | 'BQ' | 'BR' | 'BS' | 'BT' | 'BV' | 'BW' | 'BY' | 'BZ' | 'CA' | 'CC' | 'CD' | 'CF' | 'CG' | 'CH' | 'CI' | 'CK' | 'CL' | 'CM' | 'CN' | 'CO' | 'CR' | 'CU' | 'CV' | 'CW' | 'CX' | 'CY' | 'CZ' | 'DE' | 'DJ' | 'DK' | 'DM' | 'DO' | 'DZ' | 'EC' | 'EE' | 'EG' | 'EH' | 'ER' | 'ES' | 'ET' | 'FI' | 'FJ' | 'FK' | 'FM' | 'FO' | 'FR' | 'GA' | 'GB' | 'GD' | 'GE' | 'GF' | 'GG' | 'GH' | 'GI' | 'GL' | 'GM' | 'GN' | 'GP' | 'GQ' | 'GR' | 'GS' | 'GT' | 'GU' | 'GW' | 'GY' | 'HK' | 'HM' | 'HN' | 'HR' | 'HT' | 'HU' | 'ID' | 'IE' | 'IL' | 'IM' | 'IN' | 'IO' | 'IQ' | 'IR' | 'IS' | 'IT' | 'JE' | 'JM' | 'JO' | 'JP' | 'KE' | 'KG' | 'KH' | 'KI' | 'KM' | 'KN' | 'KP' | 'KR' | 'KW' | 'KY' | 'KZ' | 'LA' | 'LB' | 'LC' | 'LI' | 'LK' | 'LR' | 'LS' | 'LT' | 'LU' | 'LV' | 'LY' | 'MA' | 'MC' | 'MD' | 'ME' | 'MF' | 'MG' | 'MH' | 'MK' | 'ML' | 'MM' | 'MN' | 'MO' | 'MP' | 'MQ' | 'MR' | 'MS' | 'MT' | 'MU' | 'MV' | 'MW' | 'MX' | 'MY' | 'MZ' | 'NA' | 'NC' | 'NE' | 'NF' | 'NG' | 'NI' | 'NL' | 'NO' | 'NP' | 'NR' | 'NU' | 'NZ' | 'OM' | 'PA' | 'PE' | 'PF' | 'PG' | 'PH' | 'PK' | 'PL' | 'PM' | 'PN' | 'PR' | 'PS' | 'PT' | 'PW' | 'PY' | 'QA' | 'RE' | 'RO' | 'RS' | 'RU' | 'RW' | 'SA' | 'SB' | 'SC' | 'SD' | 'SE' | 'SG' | 'SH' | 'SI' | 'SJ' | 'SK' | 'SL' | 'SM' | 'SN' | 'SO' | 'SR' | 'SS' | 'ST' | 'SV' | 'SX' | 'SY' | 'SZ' | 'TC' | 'TD' | 'TF' | 'TG' | 'TH' | 'TJ' | 'TK' | 'TL' | 'TM' | 'TN' | 'TO' | 'TR' | 'TT' | 'TV' | 'TW' | 'TZ' | 'UA' | 'UG' | 'UM' | 'US' | 'UY' | 'UZ' | 'VA' | 'VC' | 'VE' | 'VG' | 'VI' | 'VN' | 'VU' | 'WF' | 'WS' | 'YE' | 'YT' | 'ZA' | 'ZM' | 'ZW' — Indicates the country associated with another entity, such as a business. Values are in [ISO 3166-1-alpha-2 format](http://www.iso.org/iso/home/standards/country_codes.htm). - `first_name` string, nullable — Optional first name when it's representing recipient. - `last_name` string, nullable — Optional last name when it's representing recipient. - `phone_number` string, nullable — The phone number associated with the customer profile. - `birthday` string, nullable — The birthday associated with the customer profile, in `YYYY-MM-DD` format. For example, `1998-09-21` represents September 21, 1998, and `0000-09-21` represents September 21 (without a birth year). - `reference_id` string, nullable — An optional second ID used to associate the customer profile with an entity in another system. - `note` string, nullable — A custom note associated with the customer profile. - `preferences` CustomerPreferences — Represents communication preferences for the customer profile. - `email_unsubscribed` boolean, nullable — 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. - `creation_source` 'OTHER' | 'APPOINTMENTS' | 'COUPON' | 'DELETION_RECOVERY' | 'DIRECTORY' | 'EGIFTING' | 'EMAIL_COLLECTION' | 'FEEDBACK' | 'IMPORT' | 'INVOICES' | 'LOYALTY' | 'MARKETING' | 'MERGE' | 'ONLINE_STORE' | 'INSTANT_PROFILE' | 'TERMINAL' | 'THIRD_PARTY' | 'THIRD_PARTY_IMPORT' | 'UNMERGE_RECOVERY' — Indicates the method used to create the customer profile. - `group_ids` string[], nullable — The IDs of [customer groups](entity:CustomerGroup) the customer belongs to. - `segment_ids` string[], nullable — The IDs of [customer segments](entity:CustomerSegment) the customer belongs to. - `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. - `tax_ids` CustomerTaxIds — Represents the tax ID associated with a [customer profile](entity:Customer). The corresponding `tax_ids` field is available only for customers of sellers in EU countries or the United Kingdom. For more information, see [Customer tax IDs](https://developer.squareup.com/docs/customers-api/what-it-does#customer-tax-ids). - `eu_vat` string, nullable — The EU VAT identification number for the customer. For example, `IE3426675K`. The ID can contain alphanumeric characters only. --- [API](https://skmtc.net/square/apis/connect-api.md) · [All operations](https://skmtc.net/square/apis/connect-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/square/connect-api/revisions/6a5164284e41/schema)