> ## Documentation Index > Fetch the complete documentation index at: https://docs.trykintsugi.com/llms.txt > Use this file to discover all available pages before exploring further. # Get Customers > The Get Customers API retrieves a paginated list of customers based on specified filters. This API allows searching, filtering by country and state, and sorting the results. ## OpenAPI ````yaml get /v1/customers openapi: 3.0.0 info: title: Tax Platform version: 1.0.0 servers: - url: https://api.trykintsugi.com description: Production API server URL security: [] paths: /v1/customers: get: tags: - Customers summary: Get Customers description: |- The Get Customers API retrieves a paginated list of customers based on specified filters. This API allows searching, filtering by country and state, and sorting the results. operationId: get_customers_v1 parameters: - name: search_query in: query required: false schema: description: Search term to filter customers by name or other details type: string description: Search term to filter customers by name or other details example: John - name: country in: query required: false schema: description: Country code in ISO 3166-1 alpha-2 format (e.g., 'US') type: array items: $ref: '#/components/schemas/CountryCodeEnum' description: Country code in ISO 3166-1 alpha-2 format (e.g., 'US') example: US - name: state in: query required: false schema: description: State or province code to filter customers type: string description: State or province code to filter customers example: CA - name: source__in in: query required: false schema: description: Filter customers by source (comma-separated) type: string description: Filter customers by source (comma-separated) example: SHOPIFY,API - name: order_by in: query required: false schema: description: Comma-separated list of fields to sort results by. type: string description: Comma-separated list of fields to sort results by. example: created_at,street_1,street_2,city,state,postal_code,country,status - name: page in: query required: false schema: type: integer minimum: 1 description: Page number default: 1 title: Page description: Page number - name: size in: query required: false schema: type: integer maximum: 100 minimum: 1 description: Page size default: 50 title: Size description: Page size responses: '200': description: Successfully retrieved customers content: application/json: schema: $ref: '#/components/schemas/Page_CustomerRead_' example: items: - id: cust_123abc organization_id: org_456xyz name: John Doe external_id: cust_123 status: ACTIVE email: john.doe@example.com phone: '+1234567890' street_1: 123 Main Street street_2: Apt 4B city: San Francisco county: San Francisco County state: CA postal_code: '94105' country: US full_address: 123 Main Street, Apt 4B, San Francisco, CA 94105 source: BIGCOMMERCE connection_id: conn_12345 address_status: UNVERIFIED external_friendly_id: '1234567890' total: 1 page: 1 size: 50 pages: 1 '401': description: The request is missing a valid x-api-key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: detail: Authorization header is missing or token is invalid. '404': description: Entered an incorrect URL. content: application/json: example: detail: Resource Not Found schema: $ref: '#/components/schemas/ErrorResponse' '422': description: >- Query parameters failed validation, such as an out-of-range page number. content: application/json: example: detail: - type: greater_than_equal loc: - query - page msg: Input should be greater than or equal to 1 input: '0' ctx: ge: 1 schema: $ref: >- #/components/schemas/backend__src__customers__responses__ValidationErrorResponse '500': description: An unexpected server error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: detail: An unexpected error occurred. security: - APIKeyHeader: [] CustomHeader: [] components: schemas: CountryCodeEnum: type: string enum: - AF - AX - AL - DZ - AS - AD - AO - AI - AQ - AG - AR - AM - AW - AU - AT - AZ - BS - BH - BD - BB - BY - BE - BZ - BJ - BM - BT - BO - BQ - BA - BW - BV - BR - IO - BN - BG - BF - BI - CV - KH - CM - CA - KY - CF - TD - CL - CN - CX - CC - CO - KM - CG - CD - CK - CR - HR - CU - CW - CY - CZ - DK - DJ - DM - DO - EC - EG - SV - GQ - ER - EE - SZ - ET - FK - FO - FJ - FI - FR - GF - PF - TF - GA - GM - GE - DE - GH - GI - GR - GL - GD - GP - GU - GT - GG - GN - GW - GY - HT - HM - VA - HN - HK - HU - IS - IN - ID - IR - IQ - IE - IM - IL - IT - CI - JM - JP - JE - JO - KZ - KE - KI - KP - KR - KW - KG - LA - LV - LB - LS - LR - LY - LI - LT - LU - MO - MG - MW - MY - MV - ML - MT - MH - MQ - MR - MU - YT - MX - FM - MD - MC - MN - ME - MS - MA - MZ - MM - NA - NR - NP - NL - NC - NZ - NI - NE - NG - NU - NF - MK - MP - 'NO' - OM - PK - PW - PS - PA - PG - PY - PE - PH - PN - PL - PT - PR - QA - RE - RO - RU - RW - BL - SH - KN - LC - MF - PM - VC - WS - SM - ST - SA - SN - RS - SC - SL - SG - SX - SK - SI - SB - SO - ZA - GS - SS - ES - LK - SD - SR - SJ - SE - CH - SY - TW - TJ - TZ - TH - TL - TG - TK - TO - TT - TN - TR - TM - TC - TV - UG - UA - AE - GB - US - UM - UY - UZ - VU - VE - VN - VG - VI - WF - EH - YE - ZM - ZW - XK - ZZ_EU title: CountryCodeEnum Page_CustomerRead_: properties: items: items: $ref: '#/components/schemas/CustomerRead' type: array title: Items total: type: integer minimum: 0 title: Total page: type: integer minimum: 1 title: Page size: type: integer minimum: 1 title: Size pages: type: integer minimum: 0 title: Pages type: object required: - items - total - page - size - pages title: Page[CustomerRead] ErrorResponse: properties: detail: type: string title: Detail description: Error message type: object required: - detail title: ErrorResponse backend__src__customers__responses__ValidationErrorResponse: properties: detail: items: $ref: >- #/components/schemas/backend__src__customers__responses__ValidationErrorItem type: array title: Detail type: object required: - detail title: ValidationErrorResponse CustomerRead: properties: phone: description: Customer's phone number type: string street_1: description: Primary street address. type: string street_2: description: >- Additional street address details, such as an apartment or suite number. type: string city: description: City where the customer resides. type: string county: description: County or district of the customer. type: string state: description: State or province of the customer. type: string postal_code: description: ZIP or Postal code of the customer. type: string country: $ref: '#/components/schemas/CountryCodeEnum' description: Country code in ISO 3166-1 alpha-2 format full_address: description: >- Complete address string of the customer, which can be used as an alternative to individual fields. type: string name: description: Name of the customer. type: string external_id: description: External identifier associated with the customer. type: string status: $ref: '#/components/schemas/StatusEnum' description: Status of the customer. default: ACTIVE email: description: Customer's email address type: string source: $ref: '#/components/schemas/SourceEnum' description: Source of the customer's record. connection_id: description: Identifier for the connection source, if applicable. type: string address_status: $ref: '#/components/schemas/AddressStatus' description: Status of address verification default: UNVERIFIED registration_number: description: Registration number of the customer. type: string external_friendly_id: description: >- External friendly identifier associated with the customer. We need it for netsuite. type: string customer_tax_registrations: items: $ref: '#/components/schemas/CustomerTaxRegistrationRead' type: array title: Customer Tax Registrations description: Customer tax registrations associated with the customer. id: type: string title: Id description: Unique identifier for the customer required. organization_id: type: string title: Organization Id description: >- Unique identifier for the organization associated with the customer. Required. type: object required: - id - organization_id title: CustomerRead backend__src__customers__responses__ValidationErrorItem: properties: type: type: string title: Type description: Type of validation error loc: items: type: string type: array title: Loc description: Location of error msg: type: string title: Msg description: Error message input: title: Input description: Invalid input value ctx: additionalProperties: true type: object title: Ctx description: Additional context type: object required: - type - loc - msg - input - ctx title: ValidationErrorItem StatusEnum: type: string enum: - ACTIVE - ARCHIVED title: StatusEnum SourceEnum: type: string enum: - BIGCOMMERCE - BESTBUY - BUNNY - CHARGEBEE - SHOPIFY - STRIPE - AMAZON - TIKTOK - CUSTOM - UNKNOWN - IMPORT - ZUORA - APIDECK - QUICKBOOKS - API - APPLE_APP_STORE - GOOGLE_APP_STORE - WALMART - PAYPAL - NETSUITE - XERO - MAXIO - RECURLY - SALESFORCE - ETSY - EBAY - WIX - SQUARESPACE - WOOCOMMERCE - MAGENTO - BILLING_PLATFORM - DEEL - RIPPLING - GUSTO - FACEBOOK - OTHER - ORDWAY - INSTAGRAM - PINTEREST - WAYFAIR - WISH - POS - TARGET - NEWEGG - GROUPON - GOOGLE_EXPRESS - NOCNOC - MERCADO_LIBRE - MODALYST - NORDSTROM - FAIRE - SHOPWARE - ZOHO - SAGE-INTACCT - AIRWALLEX - ORB - ZENSKAR - MICROSOFT_DYNAMICS_365 - KICKSTARTER - INTERNAL_ERP title: SourceEnum AddressStatus: type: string enum: - UNVERIFIED - INVALID - PARTIALLY_VERIFIED - VERIFIED - UNVERIFIABLE - BLANK title: AddressStatus CustomerTaxRegistrationRead: properties: id: type: string title: Id customer_id: type: string title: Customer Id country_code: $ref: '#/components/schemas/CountryCodeEnum' tax_type: $ref: '#/components/schemas/CustomerTaxTypeEnum' tax_id: type: string title: Tax Id is_valid: type: boolean title: Is Valid type: object required: - id - customer_id - country_code - tax_type - tax_id - is_valid title: CustomerTaxRegistrationRead CustomerTaxTypeEnum: type: string enum: - gst - hst - gst_hst - qst - pst - rst - vat - unknown title: CustomerTaxTypeEnum description: Enum for customer tax registration types. securitySchemes: APIKeyHeader: type: apiKey in: header name: X-API-KEY CustomHeader: type: apiKey in: header name: x-organization-id ````