{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/square/main/json-schema/square-search-customers-request-schema.json",
  "title": "SearchCustomersRequest",
  "description": "Defines the fields that are included in the request body of a request to the\n`SearchCustomers` 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/SearchCustomersRequest",
  "type": "object",
  "x-release-status": "PUBLIC",
  "properties": {
    "cursor": {
      "type": "string",
      "description": "Include the pagination cursor in subsequent calls to this endpoint to retrieve\nthe next set of results associated with the original query.\n\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)."
    },
    "limit": {
      "type": "integer",
      "description": "The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results.\nIf the specified limit is invalid, Square returns a `400 VALUE_TOO_LOW` or `400 VALUE_TOO_HIGH` error. The default value is 100.\n\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).",
      "format": "int64",
      "minimum": 1,
      "maximum": 100
    },
    "query": {
      "$ref": "#/$defs/CustomerQuery",
      "description": "The filtering and sorting criteria for the search request. If a query is not specified,\nSquare returns all customer profiles ordered alphabetically by `given_name` and `family_name`."
    },
    "count": {
      "type": "boolean",
      "description": "Indicates whether to return the total count of matching customers in the `count` field of the response.\n\nThe default value is `false`."
    }
  },
  "x-sq-sdk-sample-code": {
    "csharp": "/sdk_samples/SearchCustomers/SearchCustomersRequest.csharp",
    "java": "/sdk_samples/SearchCustomers/SearchCustomersRequest.java",
    "javascript": "/sdk_samples/SearchCustomers/SearchCustomersRequest.javascript",
    "php": "/sdk_samples/SearchCustomers/SearchCustomersRequest.php",
    "python": "/sdk_samples/SearchCustomers/SearchCustomersRequest.python",
    "ruby": "/sdk_samples/SearchCustomers/SearchCustomersRequest.ruby"
  },
  "$defs": {
    "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"
    },
    "CustomerAddressFilter": {
      "type": "object",
      "description": "The customer address filter. This filter is used in a [CustomerCustomAttributeFilterValue](entity:CustomerCustomAttributeFilterValue) filter when\nsearching by an `Address`-type custom attribute.",
      "x-release-status": "PUBLIC",
      "properties": {
        "postal_code": {
          "$ref": "#/$defs/CustomerTextFilter",
          "description": "The postal code to search for. Only an `exact` match is supported."
        },
        "country": {
          "$ref": "#/$defs/Country",
          "description": "The country code to search for.\nSee [Country](#type-country) for possible values"
        }
      }
    },
    "CustomerCreationSource": {
      "type": "string",
      "enum": [
        "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"
      ],
      "x-enum-elements": [
        {
          "name": "OTHER",
          "description": "The default creation source. This source is typically used for backward/future\ncompatibility when the original source of a customer profile is\nunrecognized. For example, when older clients do not support newer\nsource types."
        },
        {
          "name": "APPOINTMENTS",
          "description": "The customer profile was created automatically when an appointment\nwas scheduled."
        },
        {
          "name": "COUPON",
          "description": "The customer profile was created automatically when a coupon was issued\nusing Square Point of Sale."
        },
        {
          "name": "DELETION_RECOVERY",
          "description": "The customer profile was restored through Square's deletion recovery\nprocess."
        },
        {
          "name": "DIRECTORY",
          "description": "The customer profile was created manually through Square Seller Dashboard or the \nPoint of Sale application."
        },
        {
          "name": "EGIFTING",
          "description": "The customer profile was created automatically when a gift card was\nissued using Square Point of Sale. Customer profiles are created for\nboth the buyer and the recipient of the gift card."
        },
        {
          "name": "EMAIL_COLLECTION",
          "description": "The customer profile was created through Square Point of Sale when\nsigning up for marketing emails during checkout."
        },
        {
          "name": "FEEDBACK",
          "description": "The customer profile was created automatically when providing feedback\nthrough a digital receipt."
        },
        {
          "name": "IMPORT",
          "description": "The customer profile was created automatically when importing customer\ndata through Square Seller Dashboard."
        },
        {
          "name": "INVOICES",
          "description": "The customer profile was created automatically during an invoice payment."
        },
        {
          "name": "LOYALTY",
          "description": "The customer profile was created automatically when customers provide a\nphone number for loyalty reward programs during checkout."
        },
        {
          "name": "MARKETING",
          "description": "The customer profile was created as the result of a campaign managed\nthrough Square’s Facebook integration."
        },
        {
          "name": "MERGE",
          "description": "The customer profile was created as the result of explicitly merging\nmultiple customer profiles through the Square Seller Dashboard or the Point of\nSale application."
        },
        {
          "name": "ONLINE_STORE",
          "description": "The customer profile was created through Square's Online Store solution\n(legacy service)."
        },
        {
          "name": "INSTANT_PROFILE",
          "description": "The customer profile was created automatically as the result of a successful\ntransaction that did not explicitly link to an existing customer profile."
        },
        {
          "name": "TERMINAL",
          "description": "The customer profile was created through Square's Virtual Terminal."
        },
        {
          "name": "THIRD_PARTY",
          "description": "The customer profile was created through a Square API call."
        },
        {
          "name": "THIRD_PARTY_IMPORT",
          "description": "The customer profile was created by a third-party product and imported\nthrough an official integration."
        },
        {
          "name": "UNMERGE_RECOVERY",
          "description": "The customer profile was restored through Square's unmerge recovery\nprocess."
        }
      ],
      "description": "Indicates the method used to create the customer profile.",
      "x-release-status": "PUBLIC"
    },
    "CustomerCreationSourceFilter": {
      "type": "object",
      "description": "The creation source filter.\n\nIf one or more creation sources are set, customer profiles are included in,\nor excluded from, the result if they match at least one of the filter criteria.",
      "x-release-status": "PUBLIC",
      "properties": {
        "values": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "$ref": "#/$defs/CustomerCreationSource"
          },
          "description": "The list of creation sources used as filtering criteria.\nSee [CustomerCreationSource](#type-customercreationsource) for possible values"
        },
        "rule": {
          "$ref": "#/$defs/CustomerInclusionExclusion",
          "description": "Indicates whether a customer profile matching the filter criteria\nshould be included in the result or excluded from the result.\n\nDefault: `INCLUDE`.\nSee [CustomerInclusionExclusion](#type-customerinclusionexclusion) for possible values"
        }
      }
    },
    "CustomerCustomAttributeFilter": {
      "type": "object",
      "description": "The custom attribute filter. Use this filter in a set of [custom attribute filters](entity:CustomerCustomAttributeFilters) to search\nbased on the value or last updated date of a customer-related [custom attribute](entity:CustomAttribute).",
      "x-release-status": "PUBLIC",
      "required": [
        "key"
      ],
      "properties": {
        "key": {
          "type": "string",
          "description": "The `key` of the [custom attribute](entity:CustomAttribute) to filter by. The key is the identifier of the custom attribute\n(and the corresponding custom attribute definition) and can be retrieved using the [Customer Custom Attributes API](api:CustomerCustomAttributes)."
        },
        "filter": {
          "$ref": "#/$defs/CustomerCustomAttributeFilterValue",
          "description": "A filter that corresponds to the data type of the target custom attribute. For example, provide the `phone` filter to\nsearch based on the value of a `PhoneNumber`-type custom attribute. The data type is specified by the schema field of the custom attribute definition,\nwhich can be retrieved using the [Customer Custom Attributes API](api:CustomerCustomAttributes).\n\nYou must provide this `filter` field, the `updated_at` field, or both."
        },
        "updated_at": {
          "$ref": "#/$defs/TimeRange",
          "description": "The date range for when the custom attribute was last updated. The date range can include `start_at`, `end_at`, or\nboth. Range boundaries are inclusive. Dates are specified as RFC 3339 timestamps.\n\nYou must provide this `updated_at` field, the `filter` field, or both."
        }
      }
    },
    "CustomerCustomAttributeFilterValue": {
      "type": "object",
      "description": "A type-specific filter used in a [custom attribute filter](entity:CustomerCustomAttributeFilter) to search based on the value \nof a customer-related [custom attribute](entity:CustomAttribute).",
      "x-release-status": "PUBLIC",
      "properties": {
        "email": {
          "$ref": "#/$defs/CustomerTextFilter",
          "description": "A filter for a query based on the value of an `Email`-type custom attribute. This filter is case-insensitive and can\ninclude `exact` or `fuzzy`, but not both.\n\nFor an `exact` match, provide the complete email address.\n\nFor a `fuzzy` match, provide a query expression containing one or more query tokens to match against the email address. Square removes\nany punctuation (including periods (.), underscores (_), and the @ symbol) and tokenizes the email addresses on spaces. A match is found\nif a tokenized email address contains all the tokens in the search query, irrespective of the token order. For example, `Steven gmail`\nmatches steven.jones@gmail.com and mygmail@stevensbakery.com."
        },
        "phone": {
          "$ref": "#/$defs/CustomerTextFilter",
          "description": "A filter for a query based on the value of a `PhoneNumber`-type custom attribute. This filter is case-insensitive and\ncan include `exact` or `fuzzy`, but not both.\n\nFor an `exact` match, provide the complete phone number. This is always an E.164-compliant phone number that starts\nwith the + sign followed by the country code and subscriber number. For example, the format for a US phone number is +12061112222.\n\nFor a `fuzzy` match, provide a query expression containing one or more query tokens to match against the phone number.\nSquare removes any punctuation and tokenizes the expression on spaces. A match is found if a tokenized phone number contains\nall the tokens in the search query, irrespective of the token order. For example, `415 123 45` is tokenized to `415`, `123`, and `45`,\nwhich matches +14151234567 and +12345674158, but does not match +1234156780. Similarly, the expression `415` matches\n+14151234567, +12345674158, and +1234156780."
        },
        "text": {
          "$ref": "#/$defs/CustomerTextFilter",
          "description": "A filter for a query based on the value of a `String`-type custom attribute. This filter is case-insensitive and \ncan include `exact` or `fuzzy`, but not both.\n\nFor an `exact` match, provide the complete string.\n\nFor a `fuzzy` match, provide a query expression containing one or more query tokens in any order that contain complete words\nto match against the string. Square tokenizes the expression using a grammar-based tokenizer. For example, the expressions `quick brown`,\n`brown quick`, and `quick fox` match \"The quick brown fox jumps over the lazy dog\". However, `quick foxes` and `qui` do not match."
        },
        "selection": {
          "$ref": "#/$defs/FilterValue",
          "description": "A filter for a query based on the display name for a `Selection`-type custom attribute value. This filter is case-sensitive\nand can contain `any`, `all`, or both. The `none` condition is not supported.\n\nProvide the display name of each item that you want to search for. To find the display names for the selection, use the \n[Customer Custom Attributes API](api:CustomerCustomAttributes) to retrieve the corresponding custom attribute definition\nand then check the `schema.items.names` field. For more information, see\n[Search based on selection](https://developer.squareup.com/docs/customers-api/use-the-api/search-customers#custom-attribute-value-filter-selection).\n\nNote that when a `Selection`-type custom attribute is assigned to a customer profile, the custom attribute value is a list of one\nor more UUIDs (sourced from the `schema.items.enum` field) that map to the item names. These UUIDs are unique per seller."
        },
        "date": {
          "$ref": "#/$defs/TimeRange",
          "description": "A filter for a query based on the value of a `Date`-type custom attribute.\n\nProvide a date range for this filter using `start_at`, `end_at`, or both. Range boundaries are inclusive. Dates can be specified\nin `YYYY-MM-DD` format or as RFC 3339 timestamps."
        },
        "number": {
          "$ref": "#/$defs/FloatNumberRange",
          "description": "A filter for a query based on the value of a `Number`-type custom attribute, which can be an integer or a decimal with up to\n5 digits of precision.\n\nProvide a numerical range for this filter using `start_at`, `end_at`, or both. Range boundaries are inclusive. Numbers are specified\nas decimals or integers. The absolute value of range boundaries must not exceed `(2^63-1)/10^5`, or 92233720368547."
        },
        "boolean": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "A filter for a query based on the value of a `Boolean`-type custom attribute."
        },
        "address": {
          "$ref": "#/$defs/CustomerAddressFilter",
          "description": "A filter for a query based on the value of an `Address`-type custom attribute. The filter can include `postal_code`, `country`, or both."
        }
      }
    },
    "CustomerCustomAttributeFilters": {
      "type": "object",
      "description": "The custom attribute filters in a set of [customer filters](entity:CustomerFilter) used in a search query. Use this filter\nto search based on [custom attributes](entity:CustomAttribute) that are assigned to customer profiles. For more information, see\n[Search by custom attribute](https://developer.squareup.com/docs/customers-api/use-the-api/search-customers#search-by-custom-attribute).",
      "x-release-status": "PUBLIC",
      "properties": {
        "filters": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "$ref": "#/$defs/CustomerCustomAttributeFilter"
          },
          "description": "The custom attribute filters. Each filter must specify `key` and include the `filter` field with a type-specific filter,\nthe `updated_at` field, or both. The provided keys must be unique within the list of custom attribute filters."
        }
      }
    },
    "CustomerFilter": {
      "type": "object",
      "description": "Represents the filtering criteria in a [search query](entity:CustomerQuery) that defines how to filter\ncustomer profiles returned in [SearchCustomers](api-endpoint:Customers-SearchCustomers) results.",
      "x-release-status": "PUBLIC",
      "properties": {
        "creation_source": {
          "$ref": "#/$defs/CustomerCreationSourceFilter",
          "description": "A filter to select customers based on their creation source."
        },
        "created_at": {
          "$ref": "#/$defs/TimeRange",
          "description": "A filter to select customers based on when they were created."
        },
        "updated_at": {
          "$ref": "#/$defs/TimeRange",
          "description": "A filter to select customers based on when they were last updated."
        },
        "email_address": {
          "$ref": "#/$defs/CustomerTextFilter",
          "description": "A filter to [select customers by their email address](https://developer.squareup.com/docs/customers-api/use-the-api/search-customers#search-by-email-address) \nvisible to the seller. \nThis filter is case-insensitive.\n\nFor [exact matching](https://developer.squareup.com/docs/customers-api/use-the-api/search-customers#exact-search-by-email-address), this\nfilter causes the search to return customer profiles \nwhose `email_address` field value are identical to the email address provided\nin the query.\n\nFor [fuzzy matching](https://developer.squareup.com/docs/customers-api/use-the-api/search-customers#fuzzy-search-by-email-address), \nthis filter causes the search to return customer profiles \nwhose `email_address` field value has a token-wise partial match against the filtering \nexpression in the query. For example, with `Steven gmail` provided in a search\nquery, the search returns customers whose email address is `steven.johnson@gmail.com` \nor `mygmail@stevensbakery.com`. Square removes any punctuation (including periods (.),\nunderscores (_), and the @ symbol) and tokenizes the email addresses on spaces. A match is\nfound if a tokenized email address contains all the tokens in the search query, \nirrespective of the token order."
        },
        "phone_number": {
          "$ref": "#/$defs/CustomerTextFilter",
          "description": "A filter to [select customers by their phone numbers](https://developer.squareup.com/docs/customers-api/use-the-api/search-customers#search-by-phone-number)\nvisible to the seller.\n\nFor [exact matching](https://developer.squareup.com/docs/customers-api/use-the-api/search-customers#exact-search-by-phone-number),\nthis filter returns customers whose phone number matches the specified query expression. The number in the query must be of an\nE.164-compliant form. In particular, it must include the leading `+` sign followed by a country code and then a subscriber number.\nFor example, the standard E.164 form of a US phone number is `+12062223333` and an E.164-compliant variation is `+1 (206) 222-3333`.\nTo match the query expression, stored customer phone numbers are converted to the standard E.164 form.\n\nFor [fuzzy matching](https://developer.squareup.com/docs/customers-api/use-the-api/search-customers#fuzzy-search-by-phone-number),\nthis filter returns customers whose phone number matches the token or tokens provided in the query expression. For example, with `415`\nprovided in a search query, the search returns customers with the phone numbers `+1-415-212-1200`, `+1-212-415-1234`, and `+1 (551) 234-1567`.\nSimilarly, a search query of `415 123` returns customers with the phone numbers `+1-212-415-1234` and `+1 (551) 234-1567` but not\n`+1-212-415-1200`. A match is found if a tokenized phone number contains all the tokens in the search query, irrespective of the token order."
        },
        "reference_id": {
          "$ref": "#/$defs/CustomerTextFilter",
          "description": "A filter to [select customers by their reference IDs](https://developer.squareup.com/docs/customers-api/use-the-api/search-customers#search-by-reference-id).\nThis filter is case-insensitive.\n\n[Exact matching](https://developer.squareup.com/docs/customers-api/use-the-api/search-customers#exact-search-by-reference-id) \nof a customer's reference ID against a query's reference ID is evaluated as an\nexact match between two strings, character by character in the given order.\n\n[Fuzzy matching](https://developer.squareup.com/docs/customers-api/use-the-api/search-customers#fuzzy-search-by-reference-id) \nof stored reference IDs against queried reference IDs works \nexactly the same as fuzzy matching on email addresses. Non-alphanumeric characters \nare replaced by spaces to tokenize stored and queried reference IDs. A match is found\nif a tokenized stored reference ID contains all tokens specified in any order in the query. For example,\na query of `NYC M` matches customer profiles with the `reference_id` value of `NYC_M_35_JOHNSON`\nand `NYC_27_MURRAY`."
        },
        "group_ids": {
          "$ref": "#/$defs/FilterValue",
          "description": "A filter to select customers based on the [groups](entity:CustomerGroup) they belong to.\nGroup membership is controlled by sellers and developers.\n\nThe `group_ids` filter has the following syntax:\n```\n\"group_ids\": {\n\"any\":  [\"{group_a_id}\", \"{group_b_id}\", ...],\n\"all\":  [\"{group_1_id}\", \"{group_2_id}\", ...],\n\"none\": [\"{group_i_id}\", \"{group_ii_id}\", ...]\n}\n```\n\nYou can use any combination of the `any`, `all`, and `none` fields in the filter.\nWith `any`, the search returns customers in groups `a` or `b` or any other group specified in the list.\nWith `all`, the search returns customers in groups `1` and `2` and all other groups specified in the list.\nWith `none`, the search returns customers not in groups `i` or `ii` or any other group specified in the list.\n\nIf any of the search conditions are not met, including when an invalid or non-existent group ID is provided,\nthe result is an empty object (`{}`)."
        },
        "custom_attribute": {
          "$ref": "#/$defs/CustomerCustomAttributeFilters",
          "description": "A filter to select customers based on one or more custom attributes.  \nThis filter can contain up to 10 custom attribute filters. Each custom attribute filter specifies filtering criteria for a target custom\nattribute. If multiple custom attribute filters are provided, they are combined as an `AND` operation.\n\nTo be valid for a search, the custom attributes must be visible to the requesting application. For more information, including example queries,\nsee [Search by custom attribute](https://developer.squareup.com/docs/customers-api/use-the-api/search-customers#search-by-custom-attribute).\n\nSquare returns matching customer profiles, which do not contain custom attributes. To retrieve customer-related custom attributes,\nuse the [Customer Custom Attributes API](api:CustomerCustomAttributes). For example, you can call\n[RetrieveCustomerCustomAttribute](api-endpoint:CustomerCustomAttributes-RetrieveCustomerCustomAttribute) using a customer ID from the result set."
        },
        "segment_ids": {
          "$ref": "#/$defs/FilterValue",
          "description": " A filter to select customers based on the [segments](entity:CustomerSegment) they belong to.\nSegment membership is dynamic and adjusts automatically based on whether customers meet the segment criteria.\n\nYou can provide up to three segment IDs in the filter, using any combination of the `all`, `any`, and `none` fields.\nFor the following example, the results include customers who belong to both segment A and segment B but do not belong to segment C.\n\n```\n\"segment_ids\": {\n\"all\":  [\"{segment_A_id}\", \"{segment_B_id}\"],\n\"none\":  [\"{segment_C_id}\"]\n}\n```\n\nIf an invalid or non-existent segment ID is provided in the filter, Square stops processing the request\nand returns a `400 BAD_REQUEST` error that includes the segment ID."
        }
      }
    },
    "CustomerInclusionExclusion": {
      "type": "string",
      "enum": [
        "INCLUDE",
        "EXCLUDE"
      ],
      "x-enum-elements": [
        {
          "name": "INCLUDE",
          "description": "Customers should be included in the result set when they match the\nfiltering criteria."
        },
        {
          "name": "EXCLUDE",
          "description": "Customers should be excluded from the result set when they match\nthe filtering criteria."
        }
      ],
      "description": "Indicates whether customers should be included in, or excluded from,\nthe result set when they match the filtering criteria.",
      "x-release-status": "PUBLIC"
    },
    "CustomerQuery": {
      "type": "object",
      "description": "Represents filtering and sorting criteria for a [SearchCustomers](api-endpoint:Customers-SearchCustomers) request.",
      "x-release-status": "PUBLIC",
      "properties": {
        "filter": {
          "$ref": "#/$defs/CustomerFilter",
          "description": "The filtering criteria for the search query. A query can contain multiple filters in any combination.\nMultiple filters are combined as `AND` statements.\n\n__Note:__ Combining multiple filters as `OR` statements is not supported. Instead, send multiple single-filter\nsearches and join the result sets."
        },
        "sort": {
          "$ref": "#/$defs/CustomerSort",
          "description": "Sorting criteria for query results. The default behavior is to sort \ncustomers alphabetically by `given_name` and `family_name`."
        }
      }
    },
    "CustomerSort": {
      "type": "object",
      "description": "Represents the sorting criteria in a [search query](entity:CustomerQuery) that defines how to sort\ncustomer profiles returned in [SearchCustomers](api-endpoint:Customers-SearchCustomers) results.",
      "x-release-status": "PUBLIC",
      "properties": {
        "field": {
          "$ref": "#/$defs/CustomerSortField",
          "description": "Indicates the fields to use as the sort key, which is either the default set of fields or `created_at`.\n\nThe default value is `DEFAULT`.\nSee [CustomerSortField](#type-customersortfield) for possible values"
        },
        "order": {
          "$ref": "#/$defs/SortOrder",
          "description": "Indicates the order in which results should be sorted based on the\nsort field value. Strings use standard alphabetic comparison\nto determine order. Strings representing numbers are sorted as strings.\n\nThe default value is `ASC`.\nSee [SortOrder](#type-sortorder) for possible values"
        }
      }
    },
    "CustomerSortField": {
      "type": "string",
      "enum": [
        "DEFAULT",
        "CREATED_AT"
      ],
      "x-enum-elements": [
        {
          "name": "DEFAULT",
          "description": "Use the default sort key. By default, customers are sorted\nalphanumerically by concatenating their `given_name` and `family_name`. If\nneither name field is set, string comparison is performed using one of the\nremaining fields in the following order: `company_name`, `email`,\n`phone_number`."
        },
        {
          "name": "CREATED_AT",
          "description": "Use the creation date attribute (`created_at`) of customer profiles as the sort key."
        }
      ],
      "description": "Specifies customer attributes as the sort key to customer profiles returned from a search.",
      "x-release-status": "PUBLIC"
    },
    "CustomerTextFilter": {
      "type": "object",
      "description": "A filter to select customers based on exact or fuzzy matching of\ncustomer attributes against a specified query. Depending on the customer attributes, \nthe filter can be case-sensitive. This filter can be exact or fuzzy, but it cannot be both.",
      "x-release-status": "PUBLIC",
      "properties": {
        "exact": {
          "type": [
            "string",
            "null"
          ],
          "description": "Use the exact filter to select customers whose attributes match exactly the specified query."
        },
        "fuzzy": {
          "type": [
            "string",
            "null"
          ],
          "description": "Use the fuzzy filter to select customers whose attributes match the specified query \nin a fuzzy manner. When the fuzzy option is used, search queries are tokenized, and then \neach query token must be matched somewhere in the searched attribute. For single token queries, \nthis is effectively the same behavior as a partial match operation."
        }
      }
    },
    "FilterValue": {
      "type": "object",
      "description": "A filter to select resources based on an exact field value. For any given\nvalue, the value can only be in one property. Depending on the field, either\nall properties can be set or only a subset will be available.\n\nRefer to the documentation of the field.",
      "x-release-status": "BETA",
      "properties": {
        "all": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "string"
          },
          "description": "A list of terms that must be present on the field of the resource."
        },
        "any": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "string"
          },
          "description": "A list of terms where at least one of them must be present on the\nfield of the resource."
        },
        "none": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "string"
          },
          "description": "A list of terms that must not be present on the field the resource"
        }
      }
    },
    "FloatNumberRange": {
      "type": "object",
      "description": "Specifies a decimal number range.",
      "x-release-status": "PUBLIC",
      "properties": {
        "start_at": {
          "type": [
            "string",
            "null"
          ],
          "description": "A decimal value indicating where the range starts."
        },
        "end_at": {
          "type": [
            "string",
            "null"
          ],
          "description": "A decimal value indicating where the range ends."
        }
      }
    },
    "SortOrder": {
      "type": "string",
      "enum": [
        "DESC",
        "ASC"
      ],
      "x-enum-elements": [
        {
          "name": "DESC",
          "description": "The results are returned in descending (e.g., newest-first or Z-A) order."
        },
        {
          "name": "ASC",
          "description": "The results are returned in ascending (e.g., oldest-first or A-Z) order."
        }
      ],
      "description": "The order (e.g., chronological or alphabetical) in which results from a request are returned.",
      "x-release-status": "PUBLIC"
    },
    "TimeRange": {
      "type": "object",
      "description": "Represents a generic time range. The start and end values are\nrepresented in RFC 3339 format. Time ranges are customized to be\ninclusive or exclusive based on the needs of a particular endpoint.\nRefer to the relevant endpoint-specific documentation to determine\nhow time ranges are handled.",
      "x-release-status": "PUBLIC",
      "properties": {
        "start_at": {
          "type": [
            "string",
            "null"
          ],
          "description": "A datetime value in RFC 3339 format indicating when the time range\nstarts."
        },
        "end_at": {
          "type": [
            "string",
            "null"
          ],
          "description": "A datetime value in RFC 3339 format indicating when the time range\nends."
        }
      }
    }
  }
}