--- title: "List Customers" method: GET path: "/customers" tags: ["Customers"] --- # List Customers `GET /customers` Retrieves paginated list of Customers associated with the authorized requester ## Query parameters - `has_accounts` boolean - `ssn_last_4` string — Only return resources where the last 4 characters of the SSN match the specified value. - `last_name` string — Only return resources where the last_name field matches the specified string. Any * characters in the string are wildcards, and match any characters. - `email` string — Only return resources where the email field matches the specified string. Any * characters in the string are wildcards, and match any characters. - `first_name` string — Only return resources where the first_name or chosen_name field matches the specified string. Any * characters in the string are wildcards, and match any characters. - `classifications` Classification[] — Specifies the classification of a party for banks. This may contain multiple values for a combined classifications list of customers. - `phone_number` string — Only return resources where the phone_number field matches the specified string. Phone numbers use the E.164 format e.g. +19178675309. Any * characters in the string are wildcards, and match any characters. - `page_token` string — Optional pagination token to be provided to retrieve subsequent pages, returned from previous get - `id` string[] - `limit` integer — Maximum number of objects to return per page. If the limit is greater than 100, then it will be set to 100. - `sort_by` string[] - `status` 'ACTIVE' | 'DECEASED' | 'DENIED' | 'DORMANT' | 'ESCHEAT' | 'FROZEN' | 'INACTIVE' | 'PROSPECT' | 'SANCTION' — Only return resources where with the specified status. ## Response `200` List of customers - CustomerList - `customers` CustomerResponseBody[], required — Array of Customers - union - object — Details of a prospect - `vendor_info` PartyVendorInfo — Vendor information for external account management systems - `vendor_data` PartyVendorData, required — Vendor-specific data - `loanpro` PartyLoanproVendorData — LoanPro-specific vendor data - … - `vendor_type` 'LOANPRO', required — Vendor type - `addresses` Address[] — All of the customer's addresses - `address_line_1` string, required — Street address line 1 - `address_line_2` string — Street address line 2 - `address_type` 'BILLING' | 'LEGAL' | 'OPERATING' | 'OTHER' | 'SHIPPING' — Specifies the address type. - `city` string — City - `country_code` string, required — ISO-3166-1 Alpha-2 country code - `id` string, uuid — The unique identifier for this resource. - `is_registered_agent` boolean — Indicates whether an address is a registered agent. Omitted if the address is not a registered agent. - `nickname` string — A nickname for the address. This is used to identify the address in the UI. - `postal_code` string — Postal code. For US, formats of 12345 or 12345-1234 are accepted. For CA, formats of A1A 1A1 or A1A1A1 (regardless of case) are accepted, and will be converted to A1A 1A1 format. - `state` string — State, region, province, or prefecture. This is the ISO-3166-2 subdivision code, excluding the country prefix. For example, TX for Texas USA or TAM for Tamaulipas Mexico. Its length varies by country, e.g. 2 characters for US, 3 for MX. - `ban_status` 'ALLOWED' | 'BANNED' | 'SUSPENDED' — (beta) Ban status of the person. One of the following: * `ALLOWED` – person is not banned or suspended * `SUSPENDED` - person is manually suspended due to fraud * `BANNED` – person is banned due to matching ban rules Note: changing the ban status to or from BANNED can only be performed by the Synctera platform based on ban rules. - `classifications` Classification[] — Specifies the classification of a party for banks. This may contain multiple values for a combined classifications list of customers. - `creation_time` string, date-time — The date and time the resource was created. - `email` string — Customer's email - `has_accounts` boolean — This flag indicates whether the person or business has accounts. - `id` string, uuid — Customer unique identifier - `kyc_exempt` boolean — Customer's KYC exemption - `kyc_last_run` string, date-time — Date and time KYC was last run on the customer - `kyc_status` 'ACCEPTED' | 'PENDING' | 'PROVIDER_FAILURE' | 'PROVISIONAL' | 'REJECTED' | 'REVIEW' | 'UNVERIFIED' — Customer's KYC status - `last_updated_time` string, date-time — The date and time the resource was last updated. - `legal_address` LegalAddress — Legal address - `address_line_1` string, required — Street address line 1 - `address_line_2` string — Street address line 2 - `address_type` 'BILLING' | 'LEGAL' | 'OPERATING' | 'OTHER' | 'SHIPPING' — Specifies the address type. - `city` string — City - `country_code` string, required — ISO-3166-1 Alpha-2 country code - `id` string, uuid — The unique identifier for this resource. - `is_registered_agent` boolean — Indicates whether an address is a registered agent. Omitted if the address is not a registered agent. - `nickname` string — A nickname for the address. This is used to identify the address in the UI. - `postal_code` string — Postal code. For US, formats of 12345 or 12345-1234 are accepted. For CA, formats of A1A 1A1 or A1A1A1 (regardless of case) are accepted, and will be converted to A1A 1A1 format. - `state` string — State, region, province, or prefecture. This is the ISO-3166-2 subdivision code, excluding the country prefix. For example, TX for Texas USA or TAM for Tamaulipas Mexico. Its length varies by country, e.g. 2 characters for US, 3 for MX. - `metadata` object — User-supplied metadata. Do not use to store PII. - `middle_name` string — Customer's middle name - `note` string — Add an optional note when creating or updating a customer. A note is required when updating a customers's ban_status between SUSPENDED and ALLOWED. - `phone_number` string — Customer's mobile phone number with country code in E.164 format. Must have a valid country code. Area code and local phone number are not validated. - `related_customers` Relationship[] — Customer's relationships with other accounts eg. guardian. This property is no longer supported. Setting it will return an error. - `id` string, uuid, required — ID of related entity - `relationship_role` 'BENEFICIARY' | 'CUSTODIAN' | 'PARTNER', required — CUSTODIAN - Related party is the custodian e.g. the parent, BENEFICIARY - Related party is the beneficiary e.g. the dependent, PARTNER - Related party is the partner - `shipping_address` ShippingAddress — Shipping address - `address_line_1` string, required — Street address line 1 - `address_line_2` string — Street address line 2 - `address_type` 'BILLING' | 'LEGAL' | 'OPERATING' | 'OTHER' | 'SHIPPING' — Specifies the address type. - `city` string — City - `country_code` string, required — ISO-3166-1 Alpha-2 country code - `id` string, uuid — The unique identifier for this resource. - `is_registered_agent` boolean — Indicates whether an address is a registered agent. Omitted if the address is not a registered agent. - `nickname` string — A nickname for the address. This is used to identify the address in the UI. - `postal_code` string — Postal code. For US, formats of 12345 or 12345-1234 are accepted. For CA, formats of A1A 1A1 or A1A1A1 (regardless of case) are accepted, and will be converted to A1A 1A1 format. - `state` string — State, region, province, or prefecture. This is the ISO-3166-2 subdivision code, excluding the country prefix. For example, TX for Texas USA or TAM for Tamaulipas Mexico. Its length varies by country, e.g. 2 characters for US, 3 for MX. - `spend_control_ids` string[] — List of spend control IDs to control spending for the customer - `ssn` string — Customer's full tax ID eg SSN formatted with hyphens. This optional parameter is required when running KYC on a customer. Input must match the pattern ^\d{3}-\d{2}-\d{4}$. The response contains the last 4 digits only (e.g. 6789). - `ssn_source` 'MANUAL' | 'PREFILL' — Describes the collection method for the customer's SSN: * `MANUAL` – the full 9 digits of the customer's SSN was collected. * `PREFILL` – the customer's SSN was collected using SSN Prefill. - `tenant` string — The id of the tenant containing the resource. This is relevant for Fintechs that have multiple workspaces. - `dob` string, date — Customer's date of birth in RFC 3339 full-date format (YYYY-MM-DD) - `first_name` string — Customer's first name - `last_name` string — Customer's last name - `status` 'ACTIVE' | 'DECEASED' | 'DENIED' | 'DORMANT' | 'ESCHEAT' | 'FROZEN' | 'INACTIVE' | 'PROSPECT' | 'SANCTION', required — Customer's status - object — Details of a customer - `vendor_info` PartyVendorInfo — Vendor information for external account management systems - `vendor_data` PartyVendorData, required — Vendor-specific data - `loanpro` PartyLoanproVendorData — LoanPro-specific vendor data - … - `vendor_type` 'LOANPRO', required — Vendor type - `addresses` Address[] — All of the customer's addresses - `address_line_1` string, required — Street address line 1 - `address_line_2` string — Street address line 2 - `address_type` 'BILLING' | 'LEGAL' | 'OPERATING' | 'OTHER' | 'SHIPPING' — Specifies the address type. - `city` string — City - `country_code` string, required — ISO-3166-1 Alpha-2 country code - `id` string, uuid — The unique identifier for this resource. - `is_registered_agent` boolean — Indicates whether an address is a registered agent. Omitted if the address is not a registered agent. - `nickname` string — A nickname for the address. This is used to identify the address in the UI. - `postal_code` string — Postal code. For US, formats of 12345 or 12345-1234 are accepted. For CA, formats of A1A 1A1 or A1A1A1 (regardless of case) are accepted, and will be converted to A1A 1A1 format. - `state` string — State, region, province, or prefecture. This is the ISO-3166-2 subdivision code, excluding the country prefix. For example, TX for Texas USA or TAM for Tamaulipas Mexico. Its length varies by country, e.g. 2 characters for US, 3 for MX. - `ban_status` 'ALLOWED' | 'BANNED' | 'SUSPENDED' — (beta) Ban status of the person. One of the following: * `ALLOWED` – person is not banned or suspended * `SUSPENDED` - person is manually suspended due to fraud * `BANNED` – person is banned due to matching ban rules Note: changing the ban status to or from BANNED can only be performed by the Synctera platform based on ban rules. - `classifications` Classification[] — Specifies the classification of a party for banks. This may contain multiple values for a combined classifications list of customers. - `creation_time` string, date-time — The date and time the resource was created. - `email` string — Customer's email - `has_accounts` boolean — This flag indicates whether the person or business has accounts. - `id` string, uuid — Customer unique identifier - `kyc_exempt` boolean — Customer's KYC exemption - `kyc_last_run` string, date-time — Date and time KYC was last run on the customer - `kyc_status` 'ACCEPTED' | 'PENDING' | 'PROVIDER_FAILURE' | 'PROVISIONAL' | 'REJECTED' | 'REVIEW' | 'UNVERIFIED' — Customer's KYC status - `last_updated_time` string, date-time — The date and time the resource was last updated. - `legal_address` LegalAddress — Legal address - `address_line_1` string, required — Street address line 1 - `address_line_2` string — Street address line 2 - `address_type` 'BILLING' | 'LEGAL' | 'OPERATING' | 'OTHER' | 'SHIPPING' — Specifies the address type. - `city` string — City - `country_code` string, required — ISO-3166-1 Alpha-2 country code - `id` string, uuid — The unique identifier for this resource. - `is_registered_agent` boolean — Indicates whether an address is a registered agent. Omitted if the address is not a registered agent. - `nickname` string — A nickname for the address. This is used to identify the address in the UI. - `postal_code` string — Postal code. For US, formats of 12345 or 12345-1234 are accepted. For CA, formats of A1A 1A1 or A1A1A1 (regardless of case) are accepted, and will be converted to A1A 1A1 format. - `state` string — State, region, province, or prefecture. This is the ISO-3166-2 subdivision code, excluding the country prefix. For example, TX for Texas USA or TAM for Tamaulipas Mexico. Its length varies by country, e.g. 2 characters for US, 3 for MX. - `metadata` object — User-supplied metadata. Do not use to store PII. - `middle_name` string — Customer's middle name - `note` string — Add an optional note when creating or updating a customer. A note is required when updating a customers's ban_status between SUSPENDED and ALLOWED. - `phone_number` string — Customer's mobile phone number with country code in E.164 format. Must have a valid country code. Area code and local phone number are not validated. - `related_customers` Relationship[] — Customer's relationships with other accounts eg. guardian. This property is no longer supported. Setting it will return an error. - `id` string, uuid, required — ID of related entity - `relationship_role` 'BENEFICIARY' | 'CUSTODIAN' | 'PARTNER', required — CUSTODIAN - Related party is the custodian e.g. the parent, BENEFICIARY - Related party is the beneficiary e.g. the dependent, PARTNER - Related party is the partner - `shipping_address` ShippingAddress — Shipping address - `address_line_1` string, required — Street address line 1 - `address_line_2` string — Street address line 2 - `address_type` 'BILLING' | 'LEGAL' | 'OPERATING' | 'OTHER' | 'SHIPPING' — Specifies the address type. - `city` string — City - `country_code` string, required — ISO-3166-1 Alpha-2 country code - `id` string, uuid — The unique identifier for this resource. - `is_registered_agent` boolean — Indicates whether an address is a registered agent. Omitted if the address is not a registered agent. - `nickname` string — A nickname for the address. This is used to identify the address in the UI. - `postal_code` string — Postal code. For US, formats of 12345 or 12345-1234 are accepted. For CA, formats of A1A 1A1 or A1A1A1 (regardless of case) are accepted, and will be converted to A1A 1A1 format. - `state` string — State, region, province, or prefecture. This is the ISO-3166-2 subdivision code, excluding the country prefix. For example, TX for Texas USA or TAM for Tamaulipas Mexico. Its length varies by country, e.g. 2 characters for US, 3 for MX. - `spend_control_ids` string[] — List of spend control IDs to control spending for the customer - `ssn` string — Customer's full tax ID eg SSN formatted with hyphens. This optional parameter is required when running KYC on a customer. Input must match the pattern ^\d{3}-\d{2}-\d{4}$. The response contains the last 4 digits only (e.g. 6789). - `ssn_source` 'MANUAL' | 'PREFILL' — Describes the collection method for the customer's SSN: * `MANUAL` – the full 9 digits of the customer's SSN was collected. * `PREFILL` – the customer's SSN was collected using SSN Prefill. - `tenant` string — The id of the tenant containing the resource. This is relevant for Fintechs that have multiple workspaces. - `dob` string, date — Customer's date of birth in RFC 3339 full-date format (YYYY-MM-DD). Must be on or after 1900-01-01 and before current date. - `first_name` string — Customer's first name - `last_name` string — Customer's last name - `status` 'ACTIVE' | 'DECEASED' | 'DENIED' | 'DORMANT' | 'ESCHEAT' | 'FROZEN' | 'INACTIVE' | 'PROSPECT' | 'SANCTION', required — Customer's status - `next_page_token` string — If returned, use the next_page_token to query for the next page of results. Not returned if there are no more rows. ## Other responses - `401` — Unauthorized - `403` — Forbidden error - `500` — Internal server error --- [API](https://skmtc.net/synctera/apis/synctera-api.md) · [All operations](https://skmtc.net/synctera/apis/synctera-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/synctera/synctera-api/revisions/b0d812e6cdd0/schema)