{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/api-evangelist/square/main/json-schema/square-create-customer-request-schema.json", "title": "CreateCustomerRequest", "description": "Defines the body parameters that can be included in a request to the\n`CreateCustomer` endpoint.", "x-generated": "2026-10-12", "x-method": "derived", "x-generator": "derive-json-schema.py", "x-source": "openapi/square-customers-api-openapi.yml#/components/schemas/CreateCustomerRequest", "type": "object", "x-release-status": "PUBLIC", "properties": { "idempotency_key": { "type": "string", "description": "The idempotency key for the request.\tFor more information, see\n[Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)." }, "given_name": { "type": "string", "description": "The given name (that is, the first name) associated with the customer profile.\n\nThe maximum length for this value is 300 characters." }, "family_name": { "type": "string", "description": "The family name (that is, the last name) associated with the customer profile.\n\nThe maximum length for this value is 300 characters." }, "company_name": { "type": "string", "description": "A business name associated with the customer profile.\n\nThe maximum length for this value is 500 characters." }, "nickname": { "type": "string", "description": "A nickname for the customer profile.\n\nThe maximum length for this value is 100 characters." }, "email_address": { "type": "string", "description": "The email address associated with the customer profile.\n\nThe maximum length for this value is 254 characters." }, "address": { "$ref": "#/$defs/Address", "description": "The physical address associated with the customer profile. For maximum length constraints, see \n[Customer addresses](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#address).\nThe `first_name` and `last_name` fields are ignored if they are present in the request." }, "phone_number": { "type": "string", "description": "The phone number associated with the customer profile. The phone number must be valid and can contain\n9–16 digits, with an optional `+` prefix and country code. For more information, see\n[Customer phone numbers](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#phone-number)." }, "reference_id": { "type": "string", "description": "An optional second ID used to associate the customer profile with an\nentity in another system.\n\nThe maximum length for this value is 100 characters." }, "note": { "type": "string", "description": "A custom note associated with the customer profile." }, "birthday": { "type": "string", "description": "The birthday associated with the customer profile, in `YYYY-MM-DD` or `MM-DD` format. For example,\nspecify `1998-09-21` for September 21, 1998, or `09-21` for September 21. Birthdays are returned in `YYYY-MM-DD`\nformat, where `YYYY` is the specified birth year or `0000` if a birth year is not specified." }, "tax_ids": { "$ref": "#/$defs/CustomerTaxIds", "description": "The tax ID associated with the customer profile. This field is available only for customers of sellers\nin EU countries or the United Kingdom. For more information,\nsee [Customer tax IDs](https://developer.squareup.com/docs/customers-api/what-it-does#customer-tax-ids)." } }, "x-sq-sdk-sample-code": { "csharp": "/sdk_samples/CreateCustomer/CreateCustomerRequest.csharp", "java": "/sdk_samples/CreateCustomer/CreateCustomerRequest.java", "javascript": "/sdk_samples/CreateCustomer/CreateCustomerRequest.javascript", "php": "/sdk_samples/CreateCustomer/CreateCustomerRequest.php", "python": "/sdk_samples/CreateCustomer/CreateCustomerRequest.python", "ruby": "/sdk_samples/CreateCustomer/CreateCustomerRequest.ruby" }, "$defs": { "Address": { "type": "object", "description": "Represents a postal address in a country. \nFor more information, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).", "x-release-status": "PUBLIC", "properties": { "address_line_1": { "type": [ "string", "null" ], "description": "The first line of the address.\n\nFields that start with `address_line` provide the address's most specific\ndetails, like street number, street name, and building name. They do *not*\nprovide less specific details like city, state/province, or country (these\ndetails are provided in other fields)." }, "address_line_2": { "type": [ "string", "null" ], "description": "The second line of the address, if any." }, "address_line_3": { "type": [ "string", "null" ], "description": "The third line of the address, if any." }, "locality": { "type": [ "string", "null" ], "description": "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": { "type": [ "string", "null" ], "description": "A civil region within the address's `locality`, if any." }, "sublocality_2": { "type": [ "string", "null" ], "description": "A civil region within the address's `sublocality`, if any." }, "sublocality_3": { "type": [ "string", "null" ], "description": "A civil region within the address's `sublocality_2`, if any." }, "administrative_district_level_1": { "type": [ "string", "null" ], "description": "A civil entity within the address's country. In the US, this\nis 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": { "type": [ "string", "null" ], "description": "A civil entity within the address's `administrative_district_level_1`.\nIn the US, this is the county." }, "administrative_district_level_3": { "type": [ "string", "null" ], "description": "A civil entity within the address's `administrative_district_level_2`,\nif any." }, "postal_code": { "type": [ "string", "null" ], "description": "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": { "$ref": "#/$defs/Country", "description": "The address's country, in the two-letter format of ISO 3166. For example, `US` or `FR`.\nSee [Country](#type-country) for possible values" }, "first_name": { "type": [ "string", "null" ], "description": "Optional first name when it's representing recipient." }, "last_name": { "type": [ "string", "null" ], "description": "Optional last name when it's representing recipient." } } }, "Country": { "type": "string", "enum": [ "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" ], "x-enum-elements": [ { "name": "ZZ", "description": "Unknown" }, { "name": "AD", "description": "Andorra" }, { "name": "AE", "description": "United Arab Emirates" }, { "name": "AF", "description": "Afghanistan" }, { "name": "AG", "description": "Antigua and Barbuda" }, { "name": "AI", "description": "Anguilla" }, { "name": "AL", "description": "Albania" }, { "name": "AM", "description": "Armenia" }, { "name": "AO", "description": "Angola" }, { "name": "AQ", "description": "Antartica" }, { "name": "AR", "description": "Argentina" }, { "name": "AS", "description": "American Samoa" }, { "name": "AT", "description": "Austria" }, { "name": "AU", "description": "Australia" }, { "name": "AW", "description": "Aruba" }, { "name": "AX", "description": "Åland Islands" }, { "name": "AZ", "description": "Azerbaijan" }, { "name": "BA", "description": "Bosnia and Herzegovina" }, { "name": "BB", "description": "Barbados" }, { "name": "BD", "description": "Bangladesh" }, { "name": "BE", "description": "Belgium" }, { "name": "BF", "description": "Burkina Faso" }, { "name": "BG", "description": "Bulgaria" }, { "name": "BH", "description": "Bahrain" }, { "name": "BI", "description": "Burundi" }, { "name": "BJ", "description": "Benin" }, { "name": "BL", "description": "Saint Barthélemy" }, { "name": "BM", "description": "Bermuda" }, { "name": "BN", "description": "Brunei" }, { "name": "BO", "description": "Bolivia" }, { "name": "BQ", "description": "Bonaire" }, { "name": "BR", "description": "Brazil" }, { "name": "BS", "description": "Bahamas" }, { "name": "BT", "description": "Bhutan" }, { "name": "BV", "description": "Bouvet Island" }, { "name": "BW", "description": "Botswana" }, { "name": "BY", "description": "Belarus" }, { "name": "BZ", "description": "Belize" }, { "name": "CA", "description": "Canada" }, { "name": "CC", "description": "Cocos Islands" }, { "name": "CD", "description": "Democratic Republic of the Congo" }, { "name": "CF", "description": "Central African Republic" }, { "name": "CG", "description": "Congo" }, { "name": "CH", "description": "Switzerland" }, { "name": "CI", "description": "Ivory Coast" }, { "name": "CK", "description": "Cook Islands" }, { "name": "CL", "description": "Chile" }, { "name": "CM", "description": "Cameroon" }, { "name": "CN", "description": "China" }, { "name": "CO", "description": "Colombia" }, { "name": "CR", "description": "Costa Rica" }, { "name": "CU", "description": "Cuba" }, { "name": "CV", "description": "Cabo Verde" }, { "name": "CW", "description": "Curaçao" }, { "name": "CX", "description": "Christmas Island" }, { "name": "CY", "description": "Cyprus" }, { "name": "CZ", "description": "Czechia" }, { "name": "DE", "description": "Germany" }, { "name": "DJ", "description": "Djibouti" }, { "name": "DK", "description": "Denmark" }, { "name": "DM", "description": "Dominica" }, { "name": "DO", "description": "Dominican Republic" }, { "name": "DZ", "description": "Algeria" }, { "name": "EC", "description": "Ecuador" }, { "name": "EE", "description": "Estonia" }, { "name": "EG", "description": "Egypt" }, { "name": "EH", "description": "Western Sahara" }, { "name": "ER", "description": "Eritrea" }, { "name": "ES", "description": "Spain" }, { "name": "ET", "description": "Ethiopia" }, { "name": "FI", "description": "Finland" }, { "name": "FJ", "description": "Fiji" }, { "name": "FK", "description": "Falkland Islands" }, { "name": "FM", "description": "Federated States of Micronesia" }, { "name": "FO", "description": "Faroe Islands" }, { "name": "FR", "description": "France" }, { "name": "GA", "description": "Gabon" }, { "name": "GB", "description": "United Kingdom" }, { "name": "GD", "description": "Grenada" }, { "name": "GE", "description": "Georgia" }, { "name": "GF", "description": "French Guiana" }, { "name": "GG", "description": "Guernsey" }, { "name": "GH", "description": "Ghana" }, { "name": "GI", "description": "Gibraltar" }, { "name": "GL", "description": "Greenland" }, { "name": "GM", "description": "Gambia" }, { "name": "GN", "description": "Guinea" }, { "name": "GP", "description": "Guadeloupe" }, { "name": "GQ", "description": "Equatorial Guinea" }, { "name": "GR", "description": "Greece" }, { "name": "GS", "description": "South Georgia and the South Sandwich Islands" }, { "name": "GT", "description": "Guatemala" }, { "name": "GU", "description": "Guam" }, { "name": "GW", "description": "Guinea-Bissau" }, { "name": "GY", "description": "Guyana" }, { "name": "HK", "description": "Hong Kong" }, { "name": "HM", "description": "Heard Island and McDonald Islands" }, { "name": "HN", "description": "Honduras" }, { "name": "HR", "description": "Croatia" }, { "name": "HT", "description": "Haiti" }, { "name": "HU", "description": "Hungary" }, { "name": "ID", "description": "Indonesia" }, { "name": "IE", "description": "Ireland" }, { "name": "IL", "description": "Israel" }, { "name": "IM", "description": "Isle of Man" }, { "name": "IN", "description": "India" }, { "name": "IO", "description": "British Indian Ocean Territory" }, { "name": "IQ", "description": "Iraq" }, { "name": "IR", "description": "Iran" }, { "name": "IS", "description": "Iceland" }, { "name": "IT", "description": "Italy" }, { "name": "JE", "description": "Jersey" }, { "name": "JM", "description": "Jamaica" }, { "name": "JO", "description": "Jordan" }, { "name": "JP", "description": "Japan" }, { "name": "KE", "description": "Kenya" }, { "name": "KG", "description": "Kyrgyzstan" }, { "name": "KH", "description": "Cambodia" }, { "name": "KI", "description": "Kiribati" }, { "name": "KM", "description": "Comoros" }, { "name": "KN", "description": "Saint Kitts and Nevis" }, { "name": "KP", "description": "Democratic People's Republic of Korea" }, { "name": "KR", "description": "Republic of Korea" }, { "name": "KW", "description": "Kuwait" }, { "name": "KY", "description": "Cayman Islands" }, { "name": "KZ", "description": "Kazakhstan" }, { "name": "LA", "description": "Lao People's Democratic Republic" }, { "name": "LB", "description": "Lebanon" }, { "name": "LC", "description": "Saint Lucia" }, { "name": "LI", "description": "Liechtenstein" }, { "name": "LK", "description": "Sri Lanka" }, { "name": "LR", "description": "Liberia" }, { "name": "LS", "description": "Lesotho" }, { "name": "LT", "description": "Lithuania" }, { "name": "LU", "description": "Luxembourg" }, { "name": "LV", "description": "Latvia" }, { "name": "LY", "description": "Libya" }, { "name": "MA", "description": "Morocco" }, { "name": "MC", "description": "Monaco" }, { "name": "MD", "description": "Moldova" }, { "name": "ME", "description": "Montenegro" }, { "name": "MF", "description": "Saint Martin" }, { "name": "MG", "description": "Madagascar" }, { "name": "MH", "description": "Marshall Islands" }, { "name": "MK", "description": "North Macedonia" }, { "name": "ML", "description": "Mali" }, { "name": "MM", "description": "Myanmar" }, { "name": "MN", "description": "Mongolia" }, { "name": "MO", "description": "Macao" }, { "name": "MP", "description": "Northern Mariana Islands" }, { "name": "MQ", "description": "Martinique" }, { "name": "MR", "description": "Mauritania" }, { "name": "MS", "description": "Montserrat" }, { "name": "MT", "description": "Malta" }, { "name": "MU", "description": "Mauritius" }, { "name": "MV", "description": "Maldives" }, { "name": "MW", "description": "Malawi" }, { "name": "MX", "description": "Mexico" }, { "name": "MY", "description": "Malaysia" }, { "name": "MZ", "description": "Mozambique" }, { "name": "NA", "description": "Namibia" }, { "name": "NC", "description": "New Caledonia" }, { "name": "NE", "description": "Niger" }, { "name": "NF", "description": "Norfolk Island" }, { "name": "NG", "description": "Nigeria" }, { "name": "NI", "description": "Nicaragua" }, { "name": "NL", "description": "Netherlands" }, { "name": "NO", "description": "Norway" }, { "name": "NP", "description": "Nepal" }, { "name": "NR", "description": "Nauru" }, { "name": "NU", "description": "Niue" }, { "name": "NZ", "description": "New Zealand" }, { "name": "OM", "description": "Oman" }, { "name": "PA", "description": "Panama" }, { "name": "PE", "description": "Peru" }, { "name": "PF", "description": "French Polynesia" }, { "name": "PG", "description": "Papua New Guinea" }, { "name": "PH", "description": "Philippines" }, { "name": "PK", "description": "Pakistan" }, { "name": "PL", "description": "Poland" }, { "name": "PM", "description": "Saint Pierre and Miquelon" }, { "name": "PN", "description": "Pitcairn" }, { "name": "PR", "description": "Puerto Rico" }, { "name": "PS", "description": "Palestine" }, { "name": "PT", "description": "Portugal" }, { "name": "PW", "description": "Palau" }, { "name": "PY", "description": "Paraguay" }, { "name": "QA", "description": "Qatar" }, { "name": "RE", "description": "Réunion" }, { "name": "RO", "description": "Romania" }, { "name": "RS", "description": "Serbia" }, { "name": "RU", "description": "Russia" }, { "name": "RW", "description": "Rwanda" }, { "name": "SA", "description": "Saudi Arabia" }, { "name": "SB", "description": "Solomon Islands" }, { "name": "SC", "description": "Seychelles" }, { "name": "SD", "description": "Sudan" }, { "name": "SE", "description": "Sweden" }, { "name": "SG", "description": "Singapore" }, { "name": "SH", "description": "Saint Helena, Ascension and Tristan da Cunha" }, { "name": "SI", "description": "Slovenia" }, { "name": "SJ", "description": "Svalbard and Jan Mayen" }, { "name": "SK", "description": "Slovakia" }, { "name": "SL", "description": "Sierra Leone" }, { "name": "SM", "description": "San Marino" }, { "name": "SN", "description": "Senegal" }, { "name": "SO", "description": "Somalia" }, { "name": "SR", "description": "Suriname" }, { "name": "SS", "description": "South Sudan" }, { "name": "ST", "description": "Sao Tome and Principe" }, { "name": "SV", "description": "El Salvador" }, { "name": "SX", "description": "Sint Maarten" }, { "name": "SY", "description": "Syrian Arab Republic" }, { "name": "SZ", "description": "Eswatini" }, { "name": "TC", "description": "Turks and Caicos Islands" }, { "name": "TD", "description": "Chad" }, { "name": "TF", "description": "French Southern Territories" }, { "name": "TG", "description": "Togo" }, { "name": "TH", "description": "Thailand" }, { "name": "TJ", "description": "Tajikistan" }, { "name": "TK", "description": "Tokelau" }, { "name": "TL", "description": "Timor-Leste" }, { "name": "TM", "description": "Turkmenistan" }, { "name": "TN", "description": "Tunisia" }, { "name": "TO", "description": "Tonga" }, { "name": "TR", "description": "Turkey" }, { "name": "TT", "description": "Trinidad and Tobago" }, { "name": "TV", "description": "Tuvalu" }, { "name": "TW", "description": "Taiwan" }, { "name": "TZ", "description": "Tanzania" }, { "name": "UA", "description": "Ukraine" }, { "name": "UG", "description": "Uganda" }, { "name": "UM", "description": "United States Minor Outlying Islands" }, { "name": "US", "description": "United States of America" }, { "name": "UY", "description": "Uruguay" }, { "name": "UZ", "description": "Uzbekistan" }, { "name": "VA", "description": "Vatican City" }, { "name": "VC", "description": "Saint Vincent and the Grenadines" }, { "name": "VE", "description": "Venezuela" }, { "name": "VG", "description": "British Virgin Islands" }, { "name": "VI", "description": "U.S. Virgin Islands" }, { "name": "VN", "description": "Vietnam" }, { "name": "VU", "description": "Vanuatu" }, { "name": "WF", "description": "Wallis and Futuna" }, { "name": "WS", "description": "Samoa" }, { "name": "YE", "description": "Yemen" }, { "name": "YT", "description": "Mayotte" }, { "name": "ZA", "description": "South Africa" }, { "name": "ZM", "description": "Zambia" }, { "name": "ZW", "description": "Zimbabwe" } ], "description": "Indicates the country associated with another entity, such as a business.\nValues are in [ISO 3166-1-alpha-2 format](http://www.iso.org/iso/home/standards/country_codes.htm).", "x-release-status": "PUBLIC" }, "CustomerTaxIds": { "type": "object", "description": "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. \nFor more information, see [Customer tax IDs](https://developer.squareup.com/docs/customers-api/what-it-does#customer-tax-ids).", "x-release-status": "PUBLIC", "properties": { "eu_vat": { "type": [ "string", "null" ], "description": "The EU VAT identification number for the customer. For example, `IE3426675K`. The ID can contain alphanumeric characters only.", "maxLength": 20 } } } } }