action squareup_search_customers { label: "SearchCustomers" description: "Searches the customer profiles associated with a Square account using a supported query filter.\n\nCalling `SearchCustomers` without any explicit query filter returns all\ncustomer profiles ordered alphabetically based on `given_name` and\n`family_name`.\n\nUnder normal operating conditions, newly created or updated customer profiles become available\nfor the search operation in well under 30 seconds. Occasionally, propagation of the new or updated\nprofiles can take closer to one minute or longer, especially during network incidents and outages." provider: squareup method: POST path: "/v2/customers/search" encoding: json input: { type: "object" description: "Defines the fields that are included in the request body of a request to the\n`SearchCustomers` endpoint." 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/working-with-apis/pagination)." } limit: { type: "integer" format: "int64" description: "The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results. \nThe limit is ignored if it is less than the minimum or greater than the maximum value. The default value is 100.\n\nFor more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination)." } query: { type: "object" description: "Represents a query (including filtering criteria, sorting criteria, or both) used to search\nfor customer profiles." properties: { filter: { type: "object" description: "Represents a set of `CustomerQuery` filters used to limit the set of\ncustomers returned by the [SearchCustomers](https://developer.squareup.com/reference/square_2021-08-18/customers-api/search-customers) endpoint." properties: { created_at: { 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." properties: { end_at: { type: "string" description: "A datetime value in RFC 3339 format indicating when the time range\nends." } start_at: { type: "string" description: "A datetime value in RFC 3339 format indicating when the time range\nstarts." } } } creation_source: { 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." properties: { rule: { type: "string" description: "Indicates whether a customer profile matching the filter criteria\nshould be included in the result or excluded from the result.\n\nDefault: `INCLUDE`." } values: { type: "array" description: "The list of creation sources used as filtering criteria." items: { type: "string" } } } } email_address: { 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." properties: { exact: { type: "string" description: "Use the exact filter to select customers whose attributes match exactly the specified query." } fuzzy: { type: "string" 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." } } } group_ids: { 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." properties: { all: { type: "array" description: "A list of terms that must be present on the field of the resource." items: { type: "string" } } any: { type: "array" description: "A list of terms where at least one of them must be present on the\nfield of the resource." items: { type: "string" } } none: { type: "array" description: "A list of terms that must not be present on the field the resource" items: { type: "string" } } } } phone_number: { 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." properties: { exact: { type: "string" description: "Use the exact filter to select customers whose attributes match exactly the specified query." } fuzzy: { type: "string" 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." } } } reference_id: { 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." properties: { exact: { type: "string" description: "Use the exact filter to select customers whose attributes match exactly the specified query." } fuzzy: { type: "string" 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." } } } updated_at: { 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." properties: { end_at: { type: "string" description: "A datetime value in RFC 3339 format indicating when the time range\nends." } start_at: { type: "string" description: "A datetime value in RFC 3339 format indicating when the time range\nstarts." } } } } } sort: { type: "object" description: "Specifies how searched customers profiles are sorted, including the sort key and sort order." properties: { field: { type: "string" description: "Use one or more customer attributes as the sort key to sort searched customer profiles. \nFor example, use the creation date (`created_at`) of customers or default attributes as the sort key.\n\n\nDefault: `DEFAULT`." } order: { type: "string" 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\nDefault: `ASC`." } } } } } } } output: { type: "object" description: "Defines the fields that are included in the response body of\na request to the `SearchCustomers` endpoint.\n\nEither `errors` or `customers` is present in a given response (never both)." properties: { cursor: { type: "string" description: "A pagination cursor that can be used during subsequent calls\nto `SearchCustomers` to retrieve the next set of results associated\nwith the original query. Pagination cursors are only present when\na request succeeds and additional results are available.\n\nFor more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination)." } customers: { type: "array" description: "An array of `Customer` objects that match a query." items: { type: "object" description: "Represents a Square customer profile in the Customer Directory of a Square seller." properties: { address: { type: "object" description: "Represents a postal address in a country. The address format is based \non an [open-source library from Google](https://github.com/google/libaddressinput). For more information, \nsee [AddressValidationMetadata](https://github.com/google/libaddressinput/wiki/AddressValidationMetadata). \nThis format has dedicated fields for four address components: postal code, \nlocality (city), administrative district (state, prefecture, or province), and \nsublocality (town or village). These components have dedicated fields in the \n`Address` object because software sometimes behaves differently based on them. \nFor example, sales tax software may charge different amounts of sales tax \nbased on the postal code, and some software is only available in \ncertain states due to compliance reasons.\n\nFor the remaining address components, the `Address` type provides the \n`address_line_1` and `address_line_2` fields for free-form data entry. \nThese fields are free-form because the remaining address components have \ntoo many variations around the world and typical software does not parse \nthese components. These fields enable users to enter anything they want. \n\nNote that, in the current implementation, all other `Address` type fields are blank. \nThese include `address_line_3`, `sublocality_2`, `sublocality_3`, \n`administrative_district_level_2`, `administrative_district_level_3`, \n`first_name`, `last_name`, and `organization`. \n\nWhen it comes to localization, the seller's language preferences \n(see [Language preferences](https://developer.squareup.com/docs/locations-api#location-specific-and-seller-level-language-preferences)) \nare ignored for addresses. Even though Square products (such as Square Point of Sale \nand the Seller Dashboard) mostly use a seller's language preference in \ncommunication, when it comes to addresses, they will use English for a US address, \nJapanese for an address in Japan, and so on." properties: { address_line_1: { type: "string" 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" description: "The second line of the address, if any." } address_line_3: { type: "string" description: "The third line of the address, if any." } administrative_district_level_1: { type: "string" description: "A civil entity within the address's country. In the US, this\nis the state." } administrative_district_level_2: { type: "string" 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" description: "A civil entity within the address's `administrative_district_level_2`,\nif any." } country: { type: "string" description: "The address's country, in ISO 3166-1-alpha-2 format." } first_name: { type: "string" description: "Optional first name when it's representing recipient." } last_name: { type: "string" description: "Optional last name when it's representing recipient." } locality: { type: "string" description: "The city or town of the address." } organization: { type: "string" description: "Optional organization name when it's representing recipient." } postal_code: { type: "string" description: "The address's postal code." } sublocality: { type: "string" description: "A civil region within the address's `locality`, if any." } sublocality_2: { type: "string" description: "A civil region within the address's `sublocality`, if any." } sublocality_3: { type: "string" description: "A civil region within the address's `sublocality_2`, if any." } } } birthday: { type: "string" description: "The birthday associated with the customer profile, in RFC 3339 format. The year is optional. The timezone and time are not allowed.\nFor example, `0000-09-21T00:00:00-00:00` represents a birthday on September 21 and `1998-09-21T00:00:00-00:00` represents a birthday on September 21, 1998." } cards: { type: "array" description: "Payment details of the credit, debit, and gift cards stored on file for the customer profile. \n\nDEPRECATED at version 2021-06-16. Replaced by calling [ListCards](https://developer.squareup.com/reference/square_2021-08-18/cards-api/list-cards) (for credit and debit cards on file) \nor [ListGiftCards](https://developer.squareup.com/reference/square_2021-08-18/gift-cards-api/list-gift-cards) (for gift cards on file) and including the `customer_id` query parameter. \nFor more information, see [Migrate to the Cards API and Gift Cards API](https://developer.squareup.com/docs/customers-api/use-the-api/integrate-with-other-services#migrate-customer-cards)." items: { type: "object" description: "Represents the payment details of a card to be used for payments. These\ndetails are determined by the payment token generated by Web Payments SDK." properties: { billing_address: { type: "object" description: "Represents a postal address in a country. The address format is based \non an [open-source library from Google](https://github.com/google/libaddressinput). For more information, \nsee [AddressValidationMetadata](https://github.com/google/libaddressinput/wiki/AddressValidationMetadata). \nThis format has dedicated fields for four address components: postal code, \nlocality (city), administrative district (state, prefecture, or province), and \nsublocality (town or village). These components have dedicated fields in the \n`Address` object because software sometimes behaves differently based on them. \nFor example, sales tax software may charge different amounts of sales tax \nbased on the postal code, and some software is only available in \ncertain states due to compliance reasons.\n\nFor the remaining address components, the `Address` type provides the \n`address_line_1` and `address_line_2` fields for free-form data entry. \nThese fields are free-form because the remaining address components have \ntoo many variations around the world and typical software does not parse \nthese components. These fields enable users to enter anything they want. \n\nNote that, in the current implementation, all other `Address` type fields are blank. \nThese include `address_line_3`, `sublocality_2`, `sublocality_3`, \n`administrative_district_level_2`, `administrative_district_level_3`, \n`first_name`, `last_name`, and `organization`. \n\nWhen it comes to localization, the seller's language preferences \n(see [Language preferences](https://developer.squareup.com/docs/locations-api#location-specific-and-seller-level-language-preferences)) \nare ignored for addresses. Even though Square products (such as Square Point of Sale \nand the Seller Dashboard) mostly use a seller's language preference in \ncommunication, when it comes to addresses, they will use English for a US address, \nJapanese for an address in Japan, and so on." properties: { address_line_1: { type: "string" 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" description: "The second line of the address, if any." } address_line_3: { type: "string" description: "The third line of the address, if any." } administrative_district_level_1: { type: "string" description: "A civil entity within the address's country. In the US, this\nis the state." } administrative_district_level_2: { type: "string" 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" description: "A civil entity within the address's `administrative_district_level_2`,\nif any." } country: { type: "string" description: "The address's country, in ISO 3166-1-alpha-2 format." } first_name: { type: "string" description: "Optional first name when it's representing recipient." } last_name: { type: "string" description: "Optional last name when it's representing recipient." } locality: { type: "string" description: "The city or town of the address." } organization: { type: "string" description: "Optional organization name when it's representing recipient." } postal_code: { type: "string" description: "The address's postal code." } sublocality: { type: "string" description: "A civil region within the address's `locality`, if any." } sublocality_2: { type: "string" description: "A civil region within the address's `sublocality`, if any." } sublocality_3: { type: "string" description: "A civil region within the address's `sublocality_2`, if any." } } } bin: { type: "string" description: "The first six digits of the card number, known as the Bank Identification Number (BIN). Only the Payments API\nreturns this field." } card_brand: { type: "string" description: "The card's brand." } card_type: { type: "string" description: "The type of the card.\nThe Card object includes this field only in response to Payments API calls." } cardholder_name: { type: "string" description: "The name of the cardholder." } customer_id: { type: "string" description: "The ID of a customer created using the Customers API to be associated with the card." } enabled: { type: "boolean" description: "Indicates whether or not a card can be used for payments." } exp_month: { type: "integer" format: "int64" description: "The expiration month of the associated card as an integer between 1 and 12." } exp_year: { type: "integer" format: "int64" description: "The four-digit year of the card's expiration date." } fingerprint: { type: "string" description: "__Not currently set.__ Intended as a Square-assigned identifier, based\non the card number, to identify the card across multiple locations within a\nsingle application." } id: { type: "string" description: "Unique ID for this card. Generated by Square." } last_4: { type: "string" description: "The last 4 digits of the card number." } prepaid_type: { type: "string" description: "Indicates whether the Card is prepaid or not.\nThe Card object includes this field only in response to Payments API calls." } reference_id: { type: "string" description: "An optional user-defined reference ID that associates this card with\nanother entity in an external system. For example, a customer ID from an\nexternal customer management system." } version: { type: "integer" format: "int64" description: "Current version number of the card. Increments with each card update. Requests to update an\nexisting Card object will be rejected unless the version in the request matches the current\nversion for the Card." } } } } company_name: { type: "string" description: "A business name associated with the customer profile." } created_at: { type: "string" description: "The timestamp when the customer profile was created, in RFC 3339 format." } creation_source: { type: "string" description: "A creation source represents the method used to create the\ncustomer profile." } email_address: { type: "string" description: "The email address associated with the customer profile." } family_name: { type: "string" description: "The family (i.e., last) name associated with the customer profile." } given_name: { type: "string" description: "The given (i.e., first) name associated with the customer profile." } group_ids: { type: "array" description: "The IDs of customer groups the customer belongs to." items: { type: "string" } } id: { type: "string" description: "A unique Square-assigned ID for the customer profile." } nickname: { type: "string" description: "A nickname for the customer profile." } note: { type: "string" description: "A custom note associated with the customer profile." } phone_number: { type: "string" description: "The 11-digit phone number associated with the customer profile." } preferences: { type: "object" description: "Represents communication preferences for the customer profile." properties: { email_unsubscribed: { type: "boolean" description: "Indicates whether the customer has unsubscribed from marketing campaign emails. A value of `true` means that the customer chose to opt out of email marketing from the current Square seller or from all Square sellers. This value is read-only from the Customers API." } } } reference_id: { type: "string" description: "An optional second ID used to associate the customer profile with an\nentity in another system." } segment_ids: { type: "array" description: "The IDs of segments the customer belongs to." items: { type: "string" } } updated_at: { type: "string" description: "The timestamp when the customer profile was last updated, in RFC 3339 format." } version: { type: "integer" format: "int64" description: "The Square-assigned version number of the customer profile. The version number is incremented each time an update is committed to the customer profile, except for changes to customer segment membership and cards on file." } } } } errors: { type: "array" description: "Any errors that occurred during the request." items: { type: "object" description: "Represents an error encountered during a request to the Connect API.\n\nSee [Handling errors](https://developer.squareup.com/docs/build-basics/handling-errors) for more information." required: ["category", "code"] properties: { category: { type: "string" description: "The high-level category for the error." } code: { type: "string" description: "The specific code of the error." } detail: { type: "string" description: "A human-readable description of the error for debugging purposes." } field: { type: "string" description: "The name of the field provided in the original request (if any) that\nthe error pertains to." } } } } } } }