> ## Documentation Index > Fetch the complete documentation index at: https://docs.synctera.com/llms.txt > Use this file to discover all available pages before exploring further. # List persons > Retrieves paginated list of persons associated with the authorized requester. ## OpenAPI ````yaml openapi.json get /persons openapi: 3.0.3 info: description: >- This is the official reference documentation for Synctera APIs. If you need something specific or have a question, contact us.

license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html title: Synctera API version: 0.208.0 servers: - description: Sandbox (no real world financial impact) url: https://api-sandbox.synctera.com/v0 - description: Production url: https://api.synctera.com/v0 security: - bearerAuth: [] tags: - description: Lookup merchant information name: Merchants - description: Requests to generate simulated webhooks name: Card Webhook Simulations - description: >- Account programs define configurations for payment rails and transaction capabilities across different account types. name: Account Programs - description: Simulate receiving ACH transactions and returns name: ACH Transaction Simulations - description: Requests for risk evaluation and decisioning name: Risk Evaluations - description: Requests to link and manage External Cards name: External Cards - description: | The disclosures resource is used to track the status of disclosures and ensure that all parties have been shown the necessary disclosures to meet regulatory obligations. name: Disclosures - description: Create and manage Cash Order and Cash Deposit transfers name: Cash Orders and Deposits (alpha) - description: Requests to initiate customer verification. name: KYC Verification (deprecated) - description: Request to create and manage users name: Users - description: See balance history name: BalanceHistory - description: >- Migration mappings associate resources from an old tenant identity with a new tenant identity. name: Migration Mappings - description: | The External Account resource is used for managing links to accounts that operate outside of the Synctera ecosystem. name: External Accounts - description: Requests to create and manage account products, including fees, interest. name: Account Products - description: Requests to create and manage webhooks name: Webhooks - description: Create and manage documents. name: Documents - description: >- Create and manage same currency and multi-currency international wire transfers name: International Wires (alpha) - description: Requests for transaction risk detection name: Transaction risk - description: >- Used to configure bank accounts for which synctera accounts are considered a "subledger" to name: Bank Account - description: Request to create and manage party groups and party group members name: Party Groups - description: Requests to manage addresses name: Addresses - description: Requests to manage monitoring subscriptions and alerts for customers. name: Monitoring - description: Requests to search and manage compliance searches name: Compliance Searches - description: Requests to create and manage customers name: Customers - description: | The internal account resource is used for managing links to internal accounts where the funds are managed by integrators. name: Internal Accounts - description: Create and manage spending controls name: Spend Controls - description: Retrieve user identity information name: Identity - description: Requests to manage banks name: Banks - description: | The Disclosures resource is used to track the status of disclosures and ensure that customers have been shown the necessary disclosures to meet regulatory obligations. name: Disclosures (deprecated) - description: Create and manage wire transfers name: Wires - description: Requests to issue and manage Cards name: Cards - description: Request to create and manage edd name: Trust - description: Request to enroll, renew, or cancel watchlist monitors name: Watchlist (deprecated) - description: Endpoints for modifying or fetching posting dates name: Posting Dates - description: Transaction lines API name: transactions - description: Request to create and manage accounts name: Accounts - description: Requests to create and manage notes name: Notes - description: Account Template name: Account Templates - description: API for effective balances name: effective_balances - description: Requests to create and manage personal ID configurations name: Personal ID Configuration - description: > A natural person (individual human) that is relevant to the Synctera platform in some way: e.g. a personal customer or a director/officer/owner of a business. name: Persons - description: > Represents the relationships between parties. A relationship can exist between personal customers, business customers, or non-customer persons/organizations. name: Relationships - description: > A legal entity (corporation, partnership, etc.) that is relevant to the Synctera platform in some way: a business customer or some other organization that has an ownership share in such a business customer. name: Businesses - description: Request to create and manage payment_schedules name: Cronut - description: Requests to manage partners name: Partners - description: Request to create and manage deposits using remote deposit capture name: Remote Check Deposit - description: Requests to create and manage API keys name: API Keys - description: Requests to create and manage ban rules name: Ban Rules - description: Admin API for Middesk configuration using the tenants API keys. name: Middesk - description: Request to create and manage exclusions name: Stately - description: Request to create and manage partner configurations name: Quickstart - description: Manage contacts for bank and fintech partners name: Contacts - description: Create and manage transactions name: Transactions - description: Request to create and manage rdc configurations name: RDC Config - description: Create and manage holds name: Hold - description: Requests to create and manage roles name: Roles - description: Simulate receiving Wire transactions and returns name: Wire Transaction Simulations - description: Requests to create licenses name: Licenses - description: Requests to Admins to grant permissions to user name: Request Permissions - description: Configure vendor secrets for egress requests name: Egress Gateway Vendor Secret CRUD API - description: Requests to screen parties against sanctions watchlists name: Sanctions Screening - description: Create and manage payments name: ACH - description: Requests to calculate and manage CRR name: CRR - description: Requests to search financial institutions name: Institutions (Beta) - description: Create and manage tenant configurations name: Tenant Configs - description: Create and manage sweep configurations name: Configs - description: > Represents the compliance rules that are used to verify certain kinds of money movement. name: Compliance Rules - description: Configure webhook secrets for egress requests name: Egress Gateway Webhook Secret CRUD API - description: Create and manage transactions name: Transactions (internal) - description: History name: History - description: Create and manage EFT Canada transfers name: EFT Canada (Beta) - description: Requests to generate simulated transactions name: Card Transaction Simulations - description: Requests to initiate customer verification. name: KYC/KYB Verifications paths: /persons: summary: Persons get: tags: - Persons summary: List persons description: >- Retrieves paginated list of persons associated with the authorized requester. operationId: listPersons parameters: - $ref: '#/components/parameters/person_sort_by_query' - $ref: '#/components/parameters/is_customer' - $ref: '#/components/parameters/uuid_query' - $ref: '#/components/parameters/has_accounts_query' - $ref: '#/components/parameters/ssn_last_4' - $ref: '#/components/parameters/dob' - $ref: '#/components/parameters/last_name' - $ref: '#/components/parameters/person_status' - $ref: '#/components/parameters/email' - $ref: '#/components/parameters/first_chosen_name' - $ref: '#/components/parameters/classifications' - $ref: '#/components/parameters/verification_status' - $ref: '#/components/parameters/phone_number' - $ref: '#/components/parameters/page_token' - $ref: '#/components/parameters/include_console_users' - $ref: '#/components/parameters/ban_status' - $ref: '#/components/parameters/limit' responses: '200': content: application/json: schema: $ref: '#/components/schemas/person_list' description: List of persons. '401': $ref: '#/components/responses/unauthorized' '403': $ref: '#/components/responses/forbidden' '500': $ref: '#/components/responses/internal_server_error' components: parameters: person_sort_by_query: description: | Specifies the sort order for the returned persons. explode: false in: query name: sort_by schema: items: enum: - creation_time:asc - creation_time:desc - dob:asc - dob:desc - first_name:asc - first_name:desc - last_name:asc - last_name:desc - last_updated_time:asc - last_updated_time:desc type: string type: array style: form is_customer: description: If true, show only customers. If false, show non-customer parties. in: query name: is_customer schema: type: boolean uuid_query: description: > Unique identifier for the resource. Multiple IDs can be provided as a comma-separated list. explode: false in: query name: id schema: example: >- 64438afd-fa20-4010-a573-2bbdca77cdb6,84ef251c-ab8f-47a5-bbfd-a16648f95157 items: format: uuid type: string type: array style: form has_accounts_query: description: | Filter on resources that have an account(s) in: query name: has_accounts schema: type: boolean ssn_last_4: in: query name: ssn_last_4 schema: description: >- Only return resources where the last 4 characters of the SSN match the specified value. example: '6789' maxLength: 4 minLength: 4 type: string dob: in: query name: dob schema: description: >- Only return resources where the date of birth matches the specified value. example: '1980-12-25' format: date type: string last_name: in: query name: last_name schema: description: >- Only return resources where the last_name field matches the specified string. Any * characters in the string are wildcards, and match any characters. example: Smith type: string person_status: in: query name: status schema: $ref: '#/components/schemas/person_status' email: in: query name: email schema: description: >- Only return resources where the email field matches the specified string. Any * characters in the string are wildcards, and match any characters. example: john.doe@example.com type: string first_chosen_name: in: query name: first_name schema: description: >- 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. example: Alice type: string classifications: description: >- Specifies the classification of a party for banks. It can contain multiple values. example: BANK_CUSTOMER,AUTHORIZED_USER,PROSPECT explode: false in: query name: classifications schema: $ref: '#/components/schemas/classifications' style: form verification_status: description: > Verification status of the person. Multiple values can be provided as a comma-seperated list 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. explode: false in: query name: verification_status schema: items: $ref: '#/components/schemas/verification_status' type: array style: form phone_number: in: query name: phone_number schema: description: >- 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. example: '+12065550100' type: string page_token: in: query name: page_token schema: description: >- Optional pagination token to be provided to retrieve subsequent pages, returned from previous get example: a8937a0d type: string include_console_users: description: > includes the person representations of available console users in the person get respsonse. in: query name: include_console_users schema: type: boolean ban_status: description: > Ban status of the person. Multiple values can be provided as a comma-seperated list of the following: * `ALLOWED` – person is not banned or suspended * `SUSPENDED` - person is suspended * `BANNED` – person is banned explode: false in: query name: ban_status schema: items: $ref: '#/components/schemas/ban_status' type: array style: form limit: in: query name: limit schema: default: 100 description: > Maximum number of objects to return per page. If the limit is greater than 100, then it will be set to 100. example: 100 minimum: 1 type: integer schemas: person_list: allOf: - properties: persons: description: Array of persons. items: $ref: '#/components/schemas/response_person' type: array required: - persons type: object - $ref: '#/components/schemas/paginated_response' person_status: description: > 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. enum: - ACTIVE - DECEASED - DENIED - DORMANT - ESCHEAT - FROZEN - INACTIVE - PROSPECT - SANCTION example: ACTIVE type: string classifications: description: > Specifies the classification of a party for banks. This may contain multiple values for a combined classifications list of customers. items: $ref: '#/components/schemas/classification' readOnly: true type: array verification_status: description: > 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. enum: - ACCEPTED - PENDING - PROVISIONAL - REJECTED - REVIEW - UNVERIFIED example: ACCEPTED readOnly: true type: string ban_status: description: > (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. enum: - ALLOWED - BANNED - SUSPENDED example: ALLOWED type: string response_person: allOf: - $ref: '#/components/schemas/base_person' - properties: classifications: $ref: '#/components/schemas/classifications' vendor_info: $ref: '#/components/schemas/party_vendor_info' type: object - $ref: '#/components/schemas/response_personal_ids_array' description: Details of a person required: - ban_status - creation_time - id - is_customer - last_updated_time - status - tenant - verification_status type: object paginated_response: properties: next_page_token: description: >- If returned, use the next_page_token to query for the next page of results. Not returned if there are no more rows. example: a8937a0d type: string title: Paginated List response type: object error: description: >- Synctera error responses in API v0 follow [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807). Following that standard, the field for a machine-readable "error code" in API v0 is `type`. In our future API v1, we are phasing out RFC 7807 and adopting a custom error format. That format will be documented in our API v1 spec. But you may see some v0 error responses with a machine-readable `code` field while we are making the transition from v0 to v1. properties: code: description: >- An optional “sneak preview” of our future API v1 error responses. This is provided to give integrators a chance to work with our future error codes. Error codes for the same error may change between v0 and v1. example: BAD_REQUEST_BODY type: string detail: description: | A human-readable string explaining this particular error. example: 'missing required fields: first_name, dob' type: string status: description: the HTTP status code for this response example: 400 type: integer title: description: > A human-readable string for this general category of error, which corresponds 1-to-1 with error types (`title` is the human-readable version of `type`). There can be multiple distinct titles for the same HTTP status code, and the same `title` can result in many different `detail` strings. This field will be removed in API v1. example: Bad Request Body type: string type: description: > A machine-readable string that identifies the error for programmatic use. This is a URI, i.e. a globally unique identifier. It is _not_ necessarily a URL, so do not expect it to resolve to a web page. You can use this whole string as an error code, or just everything after the last slash. This field will be removed in API v1. example: https://dev.synctera.com/errors/bad-request-body type: string title: Standard error response (RFC 7807 problem report) type: object classification: description: | Specifies the classification of a party. enum: - AUTHORIZED_USER - BANK_CUSTOMER - INACTIVE_BANK_CUSTOMER - PROSPECT type: string base_person: properties: ban_status: $ref: '#/components/schemas/ban_status' chosen_name: description: Person's chosen name. example: Annie type: string creation_time: description: The date and time the resource was created. example: '2010-05-06T12:23:34.321Z' format: date-time readOnly: true type: string customer_active: description: The date and time this person became a bank customer. example: '2010-05-06T12:23:34.321Z' format: date-time readOnly: true type: string dob: description: >- 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. example: '2000-01-01' format: date type: string email: description: Person's email. example: alice@example.com type: string first_name: description: Person's first name. example: Jane type: string has_accounts: $ref: '#/components/schemas/has_accounts' id: description: Person's unique identifier. example: 7d943c51-e4ff-4e57-9558-08cab6b963c7 format: uuid readOnly: true type: string is_customer: $ref: '#/components/schemas/is_customer' is_user: $ref: '#/components/schemas/is_user' last_name: description: Person's last name. example: Smith type: string last_updated_time: description: The date and time the resource was last updated. example: '2010-05-06T12:23:34.321Z' format: date-time readOnly: true type: string legal_address: $ref: '#/components/schemas/legal_address' metadata: $ref: '#/components/schemas/metadata' middle_name: description: Person's middle name. example: Anne type: string phone_number: description: >- 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 example: '+14374570680' pattern: ^\+[1-9]\d{1,14}$ type: string shipping_address: $ref: '#/components/schemas/shipping_address' spend_control_ids: $ref: '#/components/schemas/spend_control_ids3' ssn: description: >- Person's full tax ID eg SSN formatted with hyphens. The response contains the last 4 digits only (e.g. 6789). example: 123-45-6789 type: string ssn_source: $ref: '#/components/schemas/ssn_source' status: $ref: '#/components/schemas/person_status' tenant: $ref: '#/components/schemas/tenant_id' verification_last_run: description: Date and time KYC verification was last run on the person. example: '2010-05-06T12:23:34.321Z' format: date-time readOnly: true type: string verification_status: $ref: '#/components/schemas/verification_status' type: object party_vendor_info: description: Vendor information for external account management systems properties: vendor_data: $ref: '#/components/schemas/party_vendor_data' vendor_type: $ref: '#/components/schemas/party_vendor_type' required: - vendor_data - vendor_type type: object response_personal_ids_array: properties: personal_ids: description: | Array of personal identifiers items: $ref: '#/components/schemas/response_personal_id' type: array type: object has_accounts: description: This flag indicates whether the person or business has accounts. readOnly: true type: boolean is_customer: description: > 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. example: true type: boolean is_user: description: > True for console users. Set this to true for any users direct access to the Synctera console. example: true readOnly: true type: boolean legal_address: allOf: - description: Legal address - $ref: '#/components/schemas/address' metadata: description: > Optional field to store additional information about the resource. Intended to be used by the integrator to store non-sensitive data. type: object shipping_address: allOf: - $ref: '#/components/schemas/address' - description: Shipping address spend_control_ids3: description: List of spend control IDs to control spending for the customer items: example: 7d943c51-e4ff-4e57-9558-08cab6b963c7 format: uuid type: string maxItems: 100 type: array ssn_source: description: | 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. enum: - MANUAL - PREFILL readOnly: true type: string tenant_id: description: > The id of the tenant containing the resource. This is relevant for Fintechs that have multiple workspaces. example: abcdef_ghijkl type: string party_vendor_data: description: Vendor-specific data properties: loanpro: $ref: '#/components/schemas/party_loanpro_vendor_data' type: object party_vendor_type: description: Vendor type enum: - LOANPRO type: string response_personal_id: allOf: - $ref: '#/components/schemas/personal_id_country_code_response' - $ref: '#/components/schemas/personal_id_base' - $ref: '#/components/schemas/personal_id_document_info' required: - country_code - id - id_type - identifier - system_provided type: object address: properties: address_line_1: description: Street address line 1 example: 100 Main St. type: string address_line_2: description: Street address line 2 example: Suite 99 type: string address_type: description: | Specifies the address type. enum: - BILLING - LEGAL - OPERATING - OTHER - SHIPPING example: SHIPPING readOnly: true type: string city: description: City example: New York type: string country_code: description: ISO-3166-1 Alpha-2 country code example: US pattern: ^[A-Z]{2}$ type: string id: $ref: '#/components/schemas/id' is_registered_agent: description: >- Indicates whether an address is a registered agent. Omitted if the address is not a registered agent. example: true type: boolean nickname: description: > A nickname for the address. This is used to identify the address in the UI. example: Home type: string postal_code: description: > 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. example: '28620' type: string state: description: > 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. example: NY type: string required: - address_line_1 - country_code type: object party_loanpro_vendor_data: description: LoanPro-specific vendor data properties: customer_id: description: LoanPro customer ID example: 12345 format: int64 minimum: 1 type: integer required: - customer_id type: object personal_id_country_code_response: properties: country_code: description: > The ISO 3166 Alpha-2 country code for the country that issued the personal identifier. format: US type: string personal_id_base: properties: id: description: UUID for the personal identifier for subsequent changes and deletion example: 7d943c51-e4ff-4e57-9558-08cab6b963c7 format: uuid readOnly: true type: string id_type: $ref: '#/components/schemas/personal_id_type' identifier: description: The personal identifier. Format varies by personal identifier type. example: 123-45-6789 type: string system_provided: description: >- True if the identifier was provided by the system, e.g. via SSN Prefill. readOnly: true type: boolean type: object personal_id_document_info: properties: expiry_date: description: >- The date the associated document is set to expire on set by the governing authority. example: '2020-01-01' format: date type: string issue_date: description: >- The date the associated document was issued by the governing authority. example: '2020-01-01' format: date type: string type: object id: description: The unique identifier for this resource. example: 7d943c51-e4ff-4e57-9558-08cab6b963c7 format: uuid readOnly: true type: string personal_id_type: description: > 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. enum: - CITIZENSHIP_CARD - DRIVER_LICENSE - ITIN - NATIONAL_ID - PASSPORT_NUMBER - PROVINCIAL_ID - PR_CARD - SECURE_STATUS_CARD - SIN - SSN - STATE_ID - TAX_ID example: SSN type: string responses: unauthorized: content: application/problem+json: schema: $ref: '#/components/schemas/error' description: Unauthorized forbidden: content: application/problem+json: schema: $ref: '#/components/schemas/error' description: Forbidden error internal_server_error: content: application/problem+json: schema: $ref: '#/components/schemas/error' description: Internal server error securitySchemes: bearerAuth: bearerFormat: api_key scheme: bearer type: http ````