--- title: "Sync external accounts through a vendor, such as Plaid." method: POST path: "/external_accounts/sync_vendor_accounts" tags: ["External Accounts"] --- # Sync external accounts through a vendor, such as Plaid. `POST /external_accounts/sync_vendor_accounts` Sync external accounts for a customer through an existing access token. The token must be valid, and the information on the accounts returned by the vendor must correspond to the customer. A success response for this route may include failures if an account could not be added and deletions if the account is removed by the end user, so it's important that the caller checks the response body. ## Headers - `Idempotency-Key` string ## Request body - AddVendorAccountsRequest - `business_id` string, uuid — The identifier for the business customer associated with this external account. Exactly one of `business_id` or `customer_id` must be specified. - `customer_id` string, uuid — The identifier for the personal customer associated with this external account. Exactly one of `customer_id` or `business_id` must be specified. - `customer_type` 'BUSINESS' | 'PERSONAL', required — The type of customer in the external financial institution. _Not_ necessarily the customer type on Synctera's platform: a business customer might link to the owner's personal account at an external financial institution. - `vendor` 'FINICITY' | 'PLAID', required — The vendor selected for the operation. - `vendor_access_token` string — The token provided to link external accounts. For Plaid, this is their `access_token`. - `vendor_account_ids` string[] — The list of vendor account IDs that the customer chose to link. For Plaid, these are `account_id`s. - `vendor_customer_id` string — The identifier provided by the vendor for the customer associated with this external account. - `verify_owner` boolean — If true, Synctera will attempt to verify that the external account owner is the same as the customer by comparing external account data to customer data. At least 2 of the following fields must match: name, phone number, email, address. Verification is disabled by default. ## Response `200` Result of syncing accounts through the vendor. - AddVendorAccountsResponse - `added_accounts` ExternalAccount[], required - `account_identifiers` AccountIdentifiers, required - `iban` string — The IBAN of the account. Value may be masked, in which case only the last four digits are returned. - `number` string, required — The unique identifier of the account. Value may be masked, in which case only the last four digits are returned. - `account_owner_names` string[], required — The names of the account owners. Values may be masked, in which case the array will be empty. - `business_id` string, uuid — The identifier for the business customer associated with this external account. Exactly one of `business_id` or `customer_id` will be returned. - `creation_time` string, date-time, required - `currency` string — ISO 4217 alphabetic currency code - `customer_id` string, uuid — The identifier for the personal customer associated with this external account. Exactly one of `customer_id` or `business_id` will be returned. - `deletion_time` string, date-time - `id` string, uuid, required — External account unique identifier - `last_updated_time` string, date-time, required - `metadata` object — User-supplied JSON format metadata. - `name` string — The official name of the account - `nickname` string, nullable — A user-meaningful name for the account - `routing_identifiers` AccountRouting, required - `ach_routing_number` string — The routing number used for US ACH payments. Only appears if `bank_countries` contains `US`. Value may be masked, in which case only the last four digits are returned. - `bank_address` 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. - `bank_countries` string[], required — The countries that this bank operates the account in - `bank_name` string, required — The name of the bank managing the account - `correspondent_bank_details` CorrespondentBankDetails[], nullable — The details of the correspondent banks for the account. - `bank_address` Address, required - `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. - `bank_name` string, required — The name of the correspondent bank. - `swift_code` string, required — The SWIFT code (also known as BIC code) used for international payments. - `eft_ca_routing_number` string — > 🚧 Alpha > This is an Alpha property. Feedback from the community is welcome. We may make breaking changes to this property. The 9 digit routing number used for EFT CA payments, identifying a Canadian bank. The format is 0xxxyyyyy where xxx is the institution number and yyyyy is the transit number. On write, Synctera will store the entire routing number; on read, we only return the last 4 characters. Value may be masked, in which case only the last four digits are returned. - `eft_routing_number` string — The routing number used for EFT payments, identifying a Canadian bank, consisting of the institution number and the branch number. Only appears if `bank_countries` contains `CA`. Value may be masked, in which case only the last four digits are returned. This attribute is deprecated and will be removed in a future API version. Use eft_ca_routing_number instead. - `network` 'ALGORAND' | 'AVALANCHE' | 'BITCOIN' | 'CARDANO' | 'CIRCLE' | 'EOS' | 'ETHEREUM' | 'OTHER' | 'POLKADOT' | 'SOLANA' | 'TRON' — The infrastructure or network governing the transfer of assets for your account. - `swift_code` string — The SWIFT code for the bank. Value may be masked, in which case only the last four characters are returned. - `wire_routing_number` string — The routing number used for domestic wire payments. Only appears if `bank_countries` contains `US`. Value may be masked, in which case only the last four digits are returned. - `status` 'ACTIVE' | 'CLOSED' | 'DELETED' | 'INACTIVE', required — The current state of the account - `status_reason` string — The reason for the status for the external account. - `tenant` string — The id of the tenant containing the resource. This is relevant for Fintechs that have multiple workspaces. - `type` 'CHECKING' | 'CREDIT_CARD' | 'CRYPTO_WALLET' | 'INVESTMENT_529' | 'MONEY_MARKET' | 'OTHER' | 'OTHER_BANK_ACCOUNT' | 'SAVINGS' | 'WALLET', required — The type of the account - `vendor_data` ExternalAccountVendorData - `account_number_mask` string — The last alphanumeric characters of an account's official account number. Note that the mask may be non-unique between accounts, and it may also not match the mask that the bank displays to the user. - `institution_id` string — The ID of the institution external account belongs - `vendor_info` union — The information provided to Synctera from the vendor. Interpretation of this object is up to the client. - object - `content_type` 'application/json', required — Describes the content-type encoding received from the vendor - `json` object, required — Data representation in JSON - `vendor` string, required - object - `content_type` 'text/xml', required — Describes the content-type encoding received from the vendor - `vendor` string, required - `xml` string, required — Data representaion in XML - `verification` union, required — Information about the account verification process. If the account has not been verified, this will be null. - BaseAccountVerification - `creation_time` string, date-time — The time at which verification was first completed. - `last_updated_time` string, date-time — The time at which verification was last updated. - `status` 'UNVERIFIED' | 'VERIFIED', required — The status of verification - `vendor` 'FINICITY' | 'MANUAL' | 'PLAID', required — The vendor used for verifying the account - BaseAccountVerification - `creation_time` string, date-time — The time at which verification was first completed. - `last_updated_time` string, date-time — The time at which verification was last updated. - `status` 'UNVERIFIED' | 'VERIFIED', required — The status of verification - `vendor` 'FINICITY' | 'MANUAL' | 'PLAID', required — The vendor used for verifying the account - BaseAccountVerification - `creation_time` string, date-time — The time at which verification was first completed. - `last_updated_time` string, date-time — The time at which verification was last updated. - `status` 'UNVERIFIED' | 'VERIFIED', required — The status of verification - `vendor` 'FINICITY' | 'MANUAL' | 'PLAID', required — The vendor used for verifying the account - `deleted_accounts` ExternalAccount[] - `account_identifiers` AccountIdentifiers, required - `iban` string — The IBAN of the account. Value may be masked, in which case only the last four digits are returned. - `number` string, required — The unique identifier of the account. Value may be masked, in which case only the last four digits are returned. - `account_owner_names` string[], required — The names of the account owners. Values may be masked, in which case the array will be empty. - `business_id` string, uuid — The identifier for the business customer associated with this external account. Exactly one of `business_id` or `customer_id` will be returned. - `creation_time` string, date-time, required - `currency` string — ISO 4217 alphabetic currency code - `customer_id` string, uuid — The identifier for the personal customer associated with this external account. Exactly one of `customer_id` or `business_id` will be returned. - `deletion_time` string, date-time - `id` string, uuid, required — External account unique identifier - `last_updated_time` string, date-time, required - `metadata` object — User-supplied JSON format metadata. - `name` string — The official name of the account - `nickname` string, nullable — A user-meaningful name for the account - `routing_identifiers` AccountRouting, required - `ach_routing_number` string — The routing number used for US ACH payments. Only appears if `bank_countries` contains `US`. Value may be masked, in which case only the last four digits are returned. - `bank_address` 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. - `bank_countries` string[], required — The countries that this bank operates the account in - `bank_name` string, required — The name of the bank managing the account - `correspondent_bank_details` CorrespondentBankDetails[], nullable — The details of the correspondent banks for the account. - `bank_address` Address, required - `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. - `bank_name` string, required — The name of the correspondent bank. - `swift_code` string, required — The SWIFT code (also known as BIC code) used for international payments. - `eft_ca_routing_number` string — > 🚧 Alpha > This is an Alpha property. Feedback from the community is welcome. We may make breaking changes to this property. The 9 digit routing number used for EFT CA payments, identifying a Canadian bank. The format is 0xxxyyyyy where xxx is the institution number and yyyyy is the transit number. On write, Synctera will store the entire routing number; on read, we only return the last 4 characters. Value may be masked, in which case only the last four digits are returned. - `eft_routing_number` string — The routing number used for EFT payments, identifying a Canadian bank, consisting of the institution number and the branch number. Only appears if `bank_countries` contains `CA`. Value may be masked, in which case only the last four digits are returned. This attribute is deprecated and will be removed in a future API version. Use eft_ca_routing_number instead. - `network` 'ALGORAND' | 'AVALANCHE' | 'BITCOIN' | 'CARDANO' | 'CIRCLE' | 'EOS' | 'ETHEREUM' | 'OTHER' | 'POLKADOT' | 'SOLANA' | 'TRON' — The infrastructure or network governing the transfer of assets for your account. - `swift_code` string — The SWIFT code for the bank. Value may be masked, in which case only the last four characters are returned. - `wire_routing_number` string — The routing number used for domestic wire payments. Only appears if `bank_countries` contains `US`. Value may be masked, in which case only the last four digits are returned. - `status` 'ACTIVE' | 'CLOSED' | 'DELETED' | 'INACTIVE', required — The current state of the account - `status_reason` string — The reason for the status for the external account. - `tenant` string — The id of the tenant containing the resource. This is relevant for Fintechs that have multiple workspaces. - `type` 'CHECKING' | 'CREDIT_CARD' | 'CRYPTO_WALLET' | 'INVESTMENT_529' | 'MONEY_MARKET' | 'OTHER' | 'OTHER_BANK_ACCOUNT' | 'SAVINGS' | 'WALLET', required — The type of the account - `vendor_data` ExternalAccountVendorData - `account_number_mask` string — The last alphanumeric characters of an account's official account number. Note that the mask may be non-unique between accounts, and it may also not match the mask that the bank displays to the user. - `institution_id` string — The ID of the institution external account belongs - `vendor_info` union — The information provided to Synctera from the vendor. Interpretation of this object is up to the client. - object - `content_type` 'application/json', required — Describes the content-type encoding received from the vendor - `json` object, required — Data representation in JSON - `vendor` string, required - object - `content_type` 'text/xml', required — Describes the content-type encoding received from the vendor - `vendor` string, required - `xml` string, required — Data representaion in XML - `verification` union, required — Information about the account verification process. If the account has not been verified, this will be null. - BaseAccountVerification - `creation_time` string, date-time — The time at which verification was first completed. - `last_updated_time` string, date-time — The time at which verification was last updated. - `status` 'UNVERIFIED' | 'VERIFIED', required — The status of verification - `vendor` 'FINICITY' | 'MANUAL' | 'PLAID', required — The vendor used for verifying the account - BaseAccountVerification - `creation_time` string, date-time — The time at which verification was first completed. - `last_updated_time` string, date-time — The time at which verification was last updated. - `status` 'UNVERIFIED' | 'VERIFIED', required — The status of verification - `vendor` 'FINICITY' | 'MANUAL' | 'PLAID', required — The vendor used for verifying the account - BaseAccountVerification - `creation_time` string, date-time — The time at which verification was first completed. - `last_updated_time` string, date-time — The time at which verification was last updated. - `status` 'UNVERIFIED' | 'VERIFIED', required — The status of verification - `vendor` 'FINICITY' | 'MANUAL' | 'PLAID', required — The vendor used for verifying the account - `failed_accounts` AddVendorAccountFailure[], required - `reason` 'ACCOUNT_NOT_FOUND' | 'DUPLICATE_ACCOUNT' | 'FAILED_VERIFICATION' | 'PROVIDER_ERROR' | 'UNSUPPORTED_ACCOUNT_TYPE', required — A machine-readable code describing the reason for the failure. - `reason_description` string, required — A human-readable message describing the reason for the failure. - `vendor_account_id` string, required — The vendor account ID for the account that failed. For Plaid, this is an `account_id`. - `vendor_error_message` string — The display_message returned by the vendor. Only returned if reason is set to `PROVIDER_ERROR`. For Plaid, this is the `display_message`. - `vendor_request_id` string — A unique identifier for the request from the vendor, which can be used for troubleshooting. Only returned if reason is set to `PROVIDER_ERROR`. ## Other responses - `400` — BadRequest - `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/versions/b0d812e6cdd0/schema)