---
title: "List persons"
method: GET
path: "/persons"
tags: ["Persons"]
---

# List persons

`GET /persons`

Retrieves paginated list of persons associated with the authorized requester.

## Query parameters

- `sort_by` string[]
- `is_customer` boolean
- `id` string[]
- `has_accounts` boolean
- `ssn_last_4` string — Only return resources where the last 4 characters of the SSN match the specified value.
- `dob` string, date — Only return resources where the date of birth matches 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.
- `status` 'ACTIVE' | 'DECEASED' | 'DENIED' | 'DORMANT' | 'ESCHEAT' | 'FROZEN' | 'INACTIVE' | 'PROSPECT' | 'SANCTION' — Status of the person. One of the following: * `ACTIVE` – is an integrator defined status. Integrators should set a person to active if they believe the person to be qualified for conducting business. Synctera will combine this status with other statuses such a verification to determine if the person is eligible for specific actions such as initiating transactions or issuing a card. * `DECEASED` – person is deceased. * `DENIED` – customer was turned down. * `DORMANT` – person is no longer active. * `ESCHEAT` – person's assets are abandoned and are property of the state. * `FROZEN` – person's actions are blocked for security, legal, or other reasons. * `INACTIVE` – an inactive status indicating that the person is no longer active. * `PROSPECT` – a potential customer, used for information-gathering and disclosures. * `SANCTION` – person is on a sanctions list and should be carefully monitored.
- `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.
- `verification_status` VerificationStatus[]
- `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
- `include_console_users` boolean
- `ban_status` BanStatus[]
- `limit` integer — Maximum number of objects to return per page. If the limit is greater than 100, then it will be set to 100.

## Response `200`

List of persons.

- PersonList
  - `persons` ResponsePerson[], required — Array of persons.
    - `ban_status` 'ALLOWED' | 'BANNED' | 'SUSPENDED', required — (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.
    - `chosen_name` string — Person's chosen name.
    - `creation_time` string, date-time, required — The date and time the resource was created.
    - `customer_active` string, date-time — The date and time this person became a bank customer.
    - `dob` string, date — Person'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.
    - `email` string — Person's email.
    - `first_name` string — Person's first name.
    - `has_accounts` boolean — This flag indicates whether the person or business has accounts.
    - `id` string, uuid, required — Person's unique identifier.
    - `is_customer` boolean, required — True for personal and business customers with a direct relationship with the fintech or bank. Set this to true for any customer related to an account.
    - `is_user` boolean — True for console users. Set this to true for any users direct access to the Synctera console.
    - `last_name` string — Person's last name.
    - `last_updated_time` string, date-time, required — 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` Metadata — Optional field to store additional information about the resource. Intended to be used by the integrator to store non-sensitive data.
    - `middle_name` string — Person's middle name.
    - `phone_number` string — Person'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
    - `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 — Person's full tax ID eg SSN formatted with hyphens. 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.
    - `status` 'ACTIVE' | 'DECEASED' | 'DENIED' | 'DORMANT' | 'ESCHEAT' | 'FROZEN' | 'INACTIVE' | 'PROSPECT' | 'SANCTION', required — Status of the person. One of the following: * `ACTIVE` – is an integrator defined status. Integrators should set a person to active if they believe the person to be qualified for conducting business. Synctera will combine this status with other statuses such a verification to determine if the person is eligible for specific actions such as initiating transactions or issuing a card. * `DECEASED` – person is deceased. * `DENIED` – customer was turned down. * `DORMANT` – person is no longer active. * `ESCHEAT` – person's assets are abandoned and are property of the state. * `FROZEN` – person's actions are blocked for security, legal, or other reasons. * `INACTIVE` – an inactive status indicating that the person is no longer active. * `PROSPECT` – a potential customer, used for information-gathering and disclosures. * `SANCTION` – person is on a sanctions list and should be carefully monitored.
    - `tenant` string, required — The id of the tenant containing the resource. This is relevant for Fintechs that have multiple workspaces.
    - `verification_last_run` string, date-time — Date and time KYC verification was last run on the person.
    - `verification_status` 'ACCEPTED' | 'PENDING' | 'PROVISIONAL' | 'REJECTED' | 'REVIEW' | 'UNVERIFIED', required — The result of a KYC/KYB verification. One of the following: * `UNVERIFIED` – verification has not been completed for this customer. * `PENDING` – verification is in progress for this customer. * `PROVISIONAL` – partially verified or verified with restrictions. * `ACCEPTED` – the customer has been verified. * `REVIEW` – verification has run and issues have been identified and require review. * `REJECTED` – the customer was rejected and should not be allowed to take certain actions e.g., open an account.
    - `classifications` Classification[] — Specifies the classification of a party for banks. This may contain multiple values for a combined classifications list of customers.
    - `vendor_info` PartyVendorInfo — Vendor information for external account management systems
      - `vendor_data` PartyVendorData, required — Vendor-specific data
        - `loanpro` PartyLoanproVendorData — LoanPro-specific vendor data
          - `customer_id` integer, required — LoanPro customer ID
      - `vendor_type` 'LOANPRO', required — Vendor type
    - `personal_ids` ResponsePersonalId[] — Array of personal identifiers
      - `country_code` string, US, required — The ISO 3166 Alpha-2 country code for the country that issued the personal identifier.
      - `id` string, uuid, required — UUID for the personal identifier for subsequent changes and deletion
      - `id_type` 'CITIZENSHIP_CARD' | 'DRIVER_LICENSE' | 'ITIN' | 'NATIONAL_ID' | 'PASSPORT_NUMBER' | 'PROVINCIAL_ID' | 'PR_CARD' | 'SECURE_STATUS_CARD' | 'SIN' | 'SSN' | 'STATE_ID' | 'TAX_ID', required — The type of the personal identifier. This cannot be changed once the personal identifier is created. One of the following: * `ITIN` - US Individual Tax Identification Number. Format is 987-65-4321. Country code will default to US. * `PASSPORT_NUMBER` - Passport Number. Format varies by country. Country code is required. * `SIN` - Canadian Social Insurance Number. Format is 123-456-789. Country code will default to CA. * `SSN` - US Social Security Number. Format is 123-45-6789. Country code will default to US. * `DRIVER_LICENSE` - Driver License Number. Format varies by country and state. * `STATE_ID` - US State ID Number. Format varies by state. * `NATIONAL_ID` - National ID Number. Format varies by country. * `TAX_ID` - Tax ID Number. Format varies by country. * `CITIZENSHIP_CARD` - Canadian Citizenship Card Number. Format is A1234567. * `PR_CARD` - Permanent Resident Card Number. Format varies by country. * `PROVINCIAL_ID` - Canadian Provincial ID Number. Format varies by province. * `SECURE_STATUS_CARD` - Canadian Secure Status Card Number. Format is 1998-12-123456.
      - `identifier` string, required — The personal identifier. Format varies by personal identifier type.
      - `system_provided` boolean, required — True if the identifier was provided by the system, e.g. via SSN Prefill.
      - `expiry_date` string, date — The date the associated document is set to expire on set by the governing authority.
      - `issue_date` string, date — The date the associated document was issued by the governing authority.
  - `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)