External Accounts

External Accounts represent user accounts at other financial institutions, such as checking, savings or credit cards. In order to have access to any of these accounts it is necessary to verify ownership. Synctera has partnered with Plaid and Finicity to enable this verification. The External Accounts API allow you to verify an account's ownership through these partners and get information regarding balance and transactions.

For example, you could do balance checks before issuing ACH debits to reduce the likelihood of an overdraft. ACH transactions are yet another reason to verify your account. You can originate ACH credits without verifying the account owner, however you can only initiate ACH debits when the customer has verified that they own the external account.

📘
If you're using another provider such as MX, you can directly create external accounts by posting to the /v0/external_accounts API. Synctera will confirm that customers validate ownership of the external account as part of the launch process.

Verification Steps (Plaid)

Request a link token and call Plaid Link UI
Verify account information by requesting an access token
- For micro-deposit verification only: Once micro-deposits have been received, request a secondary link token to call the Plaid Link UI again
Add verified external account

1. Request a Link Token and Call Plaid Link UI

Getting a link token is the first step to verifying an external account. This token is used to get access to Plaid Link, the UI where customers provide verification details about their bank and accounts.

You'll need to integrate Plaid Link to prompt customers to verify their external account through Plaid's UI. Plaid offers SDKs for Android, iOS, WebView, React Native and web.

In case you want to keep testing your calls to Synctera before creating your integration with Plaid Link, you can use our test page. If you are using our test page for micro-deposits, you can find test data here.

📘
Refer to Plaid's documentation to ensure that you've correctly configured the UI.

To request a link token, call the Create Link Token endpoint.

curl -X POST \
  -H 'Authorization: Bearer $apikey' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "client_name": "Name of your application",
    "customer_id":"27b1bfd0-d83f-42bc-9b2a-a0241adcba9a",
    "country_codes": [
      "US"
    ],
    "type":"DEPOSITORY",
    "language": "EN"
  }' https://api.synctera.com/v0/external_accounts/link_tokens

The customer_id is the UUID returned when you create a customer in Synctera's API. If you haven't created a customer yet, do it so by following the Customer API spec in order to proceed.
If you want to create an external account for a business, provide business_id instead of customer_id.

Notice that the type of link token requested will define what kind of account can be verified in this process.

DEPOSITORY used for accounts such as checking and savings
MICRO_DEPOSIT also used for depository accounts, with the extra benefit of being able to verify the account via micro-deposits (can be used for institutions that do not support instant verification, or if the customer prefers to not use their log-in information to connect their account).
CREDIT credit card accounts
INVESTMENT as the name says, investment accounts

Synctera will return the following response:

{
  "client_name": "Name of your application",
  "country_codes": ["US"],
  "customer_id": "27b1bfd0-d83f-42bc-9b2a-a0241adcba9a",
  "expiration": "2022-03-08T21:29:13Z",
  "language": "EN",
  "link_token": "link-sandbox-b68c1a6f-c514-4535-9781-0c2b8e2281ad",
  "request_id": "Roius8bd2DeXq6D",
  "type": "DEPOSITORY",
  "verify_owner": false
}

After the integration of your choice is done you'll use the link_token returned in the above response to launch the Plaid Link UI. Once the customer confirms their account, Plaid sends an onSuccess callback that includes metadata about the external account and a public_token. This new token is what you need for the next step.

If you are using the test page, you'll input the link_token in the Plaid Link Token field, and click Link Account. Follow the steps through the UI to confirm an account (or use test data for confirming an account through micro-deposits). After following the steps, you'll see the public_token at the top of the page.

2. Verify Account Information by Requesting an Access Token

The access token gives you all the details Plaid retrieved from the account during the verification process. In addition, this token enables you to communicate with the Synctera API to manage the account. For example, you can fetch transactions, balances, and other details about the account.

Call the Access Token endpoint to create an access token for the verified institution. For all link token types, except MICRO_DEPOSIT, the Plaid success response will include a vendor_public_token, and vendor_institution_id that must be included in the request for an access token.

📘
For micro-deposits, where the vendor_public_token and vendor_institution_id are not included in the success response, the request for access tokens and following steps for verifying the account can be found in the next section.

Provide customer_id if this is an account for a personal customer, or business_id for a business customer.

The `customer_id` is the same you used on the previous request.

```shell
curl -X POST \
  -H 'Authorization: Bearer $apikey' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "customer_id":"27b1bfd0-d83f-42bc-9b2a-a0241adcba9a",
    "vendor_institution_id": "ins_3",
    "vendor_public_token": "public-sandbox-45524484-45f9-490e-bb44-aec4131f6fb8"
  }' https://api.synctera.com/v0/external_accounts/access_tokens

Response

{
  "customer_id": "17f4c82d-a398-48ed-a9c8-5bd9a53fe862",
  "request_id": "xsHszMQwyB4IbeP",
  "vendor_access_token": "access-sandbox-2fa1d335-2d85-4563-8faa-d5e2a022d4db",
  "vendor_customer_id": "17f4c82d-a398-48ed-a9c8-5bd9a53fe862",
  "vendor_institution_id": "ins_3",
  "vendor_public_token": "public-sandbox-46a9e08e-a153-4189-85ac-143f8061746b"
}

The response returns the access token (vendor_access_token), the verification part of the process is done.

Micro-Deposits Flow

As mentioned before, there may be a variety of reasons to use micro-deposits to link an external account.
The difference in this flow is that, once the customer fills in their account information and authorizes the deposits and withdrawals, Plaid will make a $0.01 deposit to the customer's accounts. The customer will have to manually verify the code, which is part of the transaction description of the micro-deposit received.

At this point, it is assumed that you have:

Created a link token, with type: "MICRO_DEPOSIT"

Used the link token to launch Plaid Link UI (or our test page) and followed the steps outlined, using an existing account or test data.

When prompted on how you want to link your bank account, choose "Manual"

OR

Search the financial institution, a link "Link With Account Numbers" will show up. Click it.

THEN

Fill your account information and authorize the deposits and withdrawals. Plaid will make a $0.01 deposit.

Once submitted, you'll get the public token to use for the next steps.

The following steps are unique to the micro-deposit flow, starting with the request for an access token.

After receiving a public token, the next step is to create an access token by making a request to the Synctera access token endpoint. Provide the public token as the vendor_public_token. As the institution information is not returned by Plaid in the micro-deposit flow, the value for vendor_institution_id should be "-".

Example Request

The customer_id is the same you used on the previous request.
curl -X POST \
  -H 'Authorization: Bearer $apikey' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "customer_id":"27b1bfd0-d83f-42bc-9b2a-a0241adcba9a",
    "vendor_institution_id": "-",
    "vendor_public_token": "public-sandbox-45524484-45f9-490e-bb44-aec4131f6fb8"
  }' https://api.synctera.com/v0/external_accounts/access_tokens
Response
{
  "customer_id": "27b1bfd0-d83f-42bc-9b2a-a0241adcba9a",
  "request_id": "xsHszMQwyB4IbeP",
  "vendor_access_token": "access-sandbox-2fa1d335-2d85-4563-8faa-d5e2a022d4db",
  "vendor_customer_id": "17f4c82d-a398-48ed-a9c8-5bd9a53fe862",
  "vendor_institution_id": "-",
  "vendor_public_token": "public-sandbox-46a9e08e-a153-4189-85ac-143f8061746b"
}
The response returns the access token (vendor_access_token). The next step is to submit a 3-letter alphabetical code from the transaction description of the micro-deposit received. Please wait up to 48 hours, after linking your account in Step 1, to receive your micro-deposit. Once it have been received, you can move on to the next step. If you're using the test data, you can move on to the next step immediately.

After receiving the access token, and the micro-deposit, you'll need to create another link token by making a second request to the link_token endpoint. This call must include the vendor_access_token from the previous request. This secondary link token will allow you to use the Plaid Link UI (or the test page) to input the code from the transaction description of the micro-deposit received.

Example Request
curl -X POST \
  -H 'Authorization: Bearer $apikey' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "type": "MICRO_DEPOSIT",
    "language": "EN",
    "client_name": "Name of your application",
    "country_codes": ["US"],
    "customer_id": "27b1bfd0-d83f-42bc-9b2a-a0241adcba9a",
    "vendor_access_token": "access-sandbox-bf7436d8-8a18-4a11-a293-66cee2355eb6"
  }' https://api.synctera.com/v0/external_accounts/link_tokens
Like in all previous calls, if this is an account that belongs to a business, you have to provide business_id instead of customer_id.

Example Response
{
  "client_name": "Name of your application",
  "country_codes": ["US"],
  "customer_id": "27b1bfd0-d83f-42bc-9b2a-a0241adcba9a",
  "expiration": "2022-04-11T05:58:55Z",
  "language": "EN",
  "link_token": "link-sandbox-42da8003-d278-4736-a0f3-437e3cb18b40",
  "request_id": "xcJAllc7Aao6Lfh",
  "type": "MICRO_DEPOSIT",
  "vendor_access_token": "access-sandbox-2fa1d335-2d85-4563-8faa-d5e2a022d4db",
  "verify_owner": false
}
Now you'll need to launch Plaid Link UI (or the test page) with the latest link token created. You'll be prompted to submit the code from the transaction description.

Once the micro-deposit has been received, and the code from the deposit has been submitted through the Plaid Link UI, the verification for the account is complete. The last step is to add the external vendor accounts to Synctera, which is outlined below.

3. Add External Accounts

This step is essential to the process of verifying an account to avoid having to verify the account every time we want to make use of it. The Add External Accounts endpoint allows you to persist the Access Token (vendor_access_token in previous response) to add accounts the customer selected while linking the financial institution. To add an external account, you need to include the following information in the request:

customer_id or business_id: The identifier for the customer, personal or business, associated with these accounts (the one used in the previous call).
customer_type: The type of account (PERSONAL or BUSINESS), not the party type associated with the account.
vendor: The vendor selected for the operation (PLAID or FINICITY for this flow it should be PLAID).
vendor_access_token: The token provided to link external accounts. The value returned in the previous response.
vendor_account_ids: The list of vendor account IDs that the customer chose to link. For Plaid, these are account_ids.
verify_owner: Whether or not to verify the account owner information returned from Plaid/Finicity against the information entered in the Synctera system. This verification is not supported for accounts associated with business customers or for micro deposits flow.

Owner identity information is also not yet supported for business customers, so no extra information about the owner will be in the response.

Example Request

curl -X POST \
  -H 'Authorization: Bearer $apikey' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "customer_id": "3bd1a112-a98e-49ab-831c-33278cab49fb",
    "customer_type": "PERSONAL",
    "vendor": "PLAID",
    "vendor_access_token": "access-sandbox-de3ce8ef-33f8-452c-a685-8671031fc0f6",
    "vendor_account_ids": [
      "blgvvBlXw3cq5GMPwqB6s6q4dLKB9WcVqGDGo"
    ],
    "verify_owner": false
  }' https://api.synctera.com/v0/external_accounts/add_vendor_accounts

Example Response

The response below is expected for all account types, except micro-deposits.

{
  "added_accounts": [
    {
      "account_identifiers": {
        "iban": "LB7750793201TP7049N596464T98",
        "number": "78277121"
      },
      "account_owner_names": ["Jay Hansen"],
      "creation_time": "Sun Aug 22 2021 02:06:32 GMT+0000 (Coordinated Universal Time)",
      "customer_id": "1381e689-90ff-4176-8f65-a4a1225120ff",
      "id": "df0978ca-9816-4b3f-b3c1-9f1354e062fe",
      "last_updated_time": "Tue Sep 21 2021 18:04:16 GMT+0000 (Coordinated Universal Time)",
      "metadata": {},
      "nickname": "Home Loan Account",
      "routing_identifiers": {
        "ach_routing_number": "756392185",
        "bank_countries": ["US"],
        "bank_name": "Chase",
        "eft_routing_number": "02101140",
        "swift_code": "CHASUS3AXXX",
        "wire_routing_number": "756392185"
      },
      "status": "ACTIVE",
      "type": "CHECKING",
      "verification": {
        "creation_time": "Mon Mar 22 2021 12:46:17 GMT+0000 (Coordinated Universal Time)",
        "last_updated_time": "Sat Jan 15 2022 18:54:20 GMT+0000 (Coordinated Universal Time)",
        "status": "VERIFIED",
        "vendor": "PLAID"
      }
    }
  ],
  "failed_accounts": [
    {
      "reason": "FAILED_VERIFICATION",
      "reason_description": "string",
      "vendor_account_id": "blgvvBlXw3cq5GMPwqB6s6q4dLKB9WcVqGDGo",
      "vendor_error_message": "string",
      "vendor_request_id": "string"
    }
  ]
}

Example Response for Micro-Deposits

{
  "added_accounts": [
    {
      "account_identifiers": {
          "number": "0000"
      },
      "account_owner_names": [],
      "creation_time": "2022-08-09T18:28:04.354566Z",
      "customer_id": "b0f0577c-6614-4b2e-ab21-9c9437202de4",
      "id": "cf10c441-401f-4395-97de-cff8583041be",
      "last_updated_time": "2022-08-09T18:28:04.354566Z",
      "metadata": {},
      "nickname": null,
      "routing_identifiers": {
          "ach_routing_number": "0000",
          "bank_countries": [
              "US"
          ],
          "bank_name": ""
      },
      "status": "ACTIVE",
      "type": "CHECKING",
      "vendor_data": {
          "account_number_mask": "0000",
          "institution_id": ""
      },
      "verification": {
          "creation_time": "2022-08-09T18:28:04.354566Z",
          "last_updated_time": "2022-08-09T18:28:04.354566Z",
          "status": "VERIFIED",
          "vendor": "PLAID"
      }
    }
  ],
  "failed_accounts": []
}

The success callback will include a list of account IDs passed in the UI. The response includes both added and failed accounts, so you'll need to check the response to see which accounts were added and which ones failed. You can also use the List External Accounts endpoint to retrieve a list of all external accounts assigned to customers.

Update Mode

Update Mode allows two things:

Re-authenticate an account that has been disconnected.
Link additional accounts for the customer (at the same bank).
To launch Plaid Link in update mode you need to create a new link token by providing vendor_institution_id and vendor_access_token in the request body.

Example Request

curl -X POST \
  -H 'Authorization: Bearer $apikey' \
  -H 'Content-Type: application/json' \
  -d '
  {
     "type": "DEPOSITORY",
     "language": "EN",
     "client_name": "Synctera",
     "country_codes": [
       "US"
     ],
     "customer_id": "8bb5f852-5b53-4b0e-97f0-43bcb4f8532b",
     "vendor_institution_id": "ins_56",
     "vendor_access_token": "access-sandbox-23ac17ff-b4b7-4dce-8194-2e17f9656ccb"
 }' https://api.synctera.com/v0/external_accounts/link_tokens

Response

{
  "client_name": "Synctera",
  "country_codes": [
     "US"
  ],
  "customer_id": "8bb5f852-5b53-4b0e-97f0-43bcb4f8532b",
  "expiration": "2022-09-13T00:58:44Z",
  "language": "EN",
  "link_token": "link-sandbox-1d3d4450-9325-4f48-979f-4baf77ba3635",
  "request_id": "M9priKvIHeLDvcg",
  "type": "DEPOSITORY",
  "vendor_access_token": "access-sandbox-23ac17ff-b4b7-4dce-8194-2e17f9656ccb",
  "vendor_institution_id": "ins_56",
  "verify_owner": false
}

Once you have the link token, you can launch Plaid Link. Notice that for that institution and user, you'll see the accounts that are already linked in list of accounts.
Now you're able to add new accounts, or remove the ones that are already linked. Once you're done selecting the accounts you want and submitting your changes, you'll get a new access token, and you can use it to update the accounts by calling the Sync Vendor Accounts endpoint.

Verification Steps (Finicity)

Request Connect URL from Finicity
Link your account(s)
Add verified external account(s)

Plaid vs Finicity

Plaid and Finicity provide very similar services, but they have a few differences.
The main difference is in the account linking process.
Plaid's interface to link accounts, called Plaid Link, requires the fintech to integrate with Plaid directly, using their offered SDKs.
Finicity Connect on the other hand, is a web interface hosted by Finicity, where the users can provide for their accounts' credentials directly.

Another important difference, micro-deposits are not supported by Finicity.

1. Request Connect URL from Finicity

The Connect URL takes you to Finicity's web interface that allows your customers to link their account(s).

To request the URL, call the Create Link Token endpoint.

curl -X POST \
  -H 'Authorization: Bearer $apikey' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "client_name": "Name of your application",
    "customer_id":"27b1bfd0-d83f-42bc-9b2a-a0241adcba9a",
    "country_codes": [
      "US"
    ],
    "type":"DEPOSITORY",
    "language": "EN"
  }' https://api.synctera.com/v0/external_accounts/link_tokens

The customer_id is the UUID returned when you create a customer in Synctera's API. If you haven't created a customer yet, please do it so by following the Customer API spec in order to proceed.
If you want to create an external account for a business, provide business_id instead of customer_id.

Notice that the type of link token requested will define what kind of account can be verified in this process.

DEPOSITORY used for accounts such as checking and savings
CREDIT credit card accounts
INVESTMENT as the name says, investment accounts

Synctera will return the following response:

{
  "client_name": "Name of your application",
  "country_codes": ["US"],
  "customer_id": "27b1bfd0-d83f-42bc-9b2a-a0241adcba9a",
  "expiration": "2022-03-08T21:29:13Z",
  "language": "EN",
  "link_token": "https://connect2.finicity.com?customerId=6003202401&experience=8ab62f1c-5f9b-4f3f-a20f-377aa28a8de2&origin=url&partnerId=2445583932772&signature=bdc6b061a8b25822de164fc857a74601c1c1f1b816d9200a8d14dd57c1095246&timestamp=1656025350309&ttl=1656032550309",
  "request_id": "Roius8bd2DeXq6D",
  "type": "DEPOSITORY",
  "verify_owner": false
}

Your vendor customer ID will be needed in a future step, it should be saved for later. You can locate it as the query parameter customerId in the URL above, in this case the vendor customer id is 6003202401.

2. Link your account(s)

Load the URL returned on the last step, so your users can search the financial institution, provide credential and link their account(s).

3. Add External Accounts

This step is essential to the process of linking an account. You linked your account through Finicity, but in order to make use of it (request balance, transaction history, etc) you need to persist it with Synctera API. To add an external account linked through Finicity, you need to call Sync External Accounts and include the following information in the request:

customer_id or business_id: The identifier for the customer, personal or business, associated with these accounts (the one used in the previous call).
customer_type: The type of account (PERSONAL or BUSINESS), not the party type associated with the account.
vendor: The vendor selected for the operation (PLAID or FINICITY for this flow it should be FINICITY).
vendor_customer_id: The customer ID returned by the vendor.
verify_owner: Whether or not to verify the account owner information returned from Plaid/Finicity against the information entered in the Synctera system. This verification is not supported for accounts associated with business customers or for micro deposits flow.

All accounts selected in Finicity Connect by your customer in step 2 will be added to Synctera as verified external accounts. The same can be done to delete or add new accounts, just link the accounts you need and call sync_vendor_accounts again.

Owner identity information is also not yet supported for business customers, so no extra information about the owner will be in the response.


**Example Request**

```shell
curl -X POST \
  -H 'Authorization: Bearer $apikey' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "customer_id": "3bd1a112-a98e-49ab-831c-33278cab49fb",
    "customer_type": "PERSONAL",
    "vendor": "FINICITY",
    "vendor_customer_id": "6003202403",
    "verify_owner": false
  }' https://api.synctera.com/v0/external_accounts/add_vendor_accounts

Example Response

{
  "added_accounts": [
    {
      "account_identifiers": {
        "iban": "LB7750793201TP7049N596464T98",
        "number": "78277121"
      },
      "account_owner_names": ["Jay Hansen"],
      "creation_time": "Sun Aug 22 2021 02:06:32 GMT+0000 (Coordinated Universal Time)",
      "customer_id": "1381e689-90ff-4176-8f65-a4a1225120ff",
      "id": "df0978ca-9816-4b3f-b3c1-9f1354e062fe",
      "last_updated_time": "Tue Sep 21 2021 18:04:16 GMT+0000 (Coordinated Universal Time)",
      "metadata": {},
      "nickname": "Home Loan Account",
      "routing_identifiers": {
        "ach_routing_number": "756392185",
        "bank_countries": ["US"],
        "bank_name": "Chase",
        "eft_routing_number": "02101140",
        "swift_code": "CHASUS3AXXX",
        "wire_routing_number": "756392185"
      },
      "status": "ACTIVE",
      "type": "CHECKING",
      "verification": {
        "creation_time": "Mon Mar 22 2021 12:46:17 GMT+0000 (Coordinated Universal Time)",
        "last_updated_time": "Sat Jan 15 2022 18:54:20 GMT+0000 (Coordinated Universal Time)",
        "status": "UNVERIFIED",
        "vendor": "FINICITY"
      }
    }
  ],
  "failed_accounts": [
    {
      "reason": "FAILED_VERIFICATION",
      "reason_description": "string",
      "vendor_account_id": "blgvvBlXw3cq5GMPwqB6s6q4dLKB9WcVqGDGo",
      "vendor_error_message": "string",
      "vendor_request_id": "string"
    }
  ]
}

The response includes both added, deleted and failed accounts. You can also use the List External Accounts endpoint to retrieve a list of all external accounts assigned to customers.

⚠️
Finicity flow does not support adding accounts through Add External Accounts, only through Sync External Accounts.

Operations

Now that you linked your account and added it to Synctera, you can list transactions and see the account's balance. Note: these operations will not be available for micro deposits as Plaid does not allow Auth
on micro deposits which means balances and transactions are not available.

List Transactions

You can retrieve a list transactions for a given external account using the List Transactions for an external account endpoint. You'll need to provide the following query parameters:

The external_account_id, this is the UUID returned on last response.
The start_date and end_date to specify a date range. Important to notice, start_date is inclusive, and end_date is exclusive, so if you want all transactions from 2022-01-01, you should have for example start_date=2022-01-01&end_date=2022-01-02 in your URL.

Example Request

curl -H 'Authorization: Bearer $apikey' \
     -H 'Content-Type: application/json' "https://api.synctera.com/v0/external_accounts/df0978ca-9816-4b3f-b3c1-9f1354e062fe/transactions?start_date=2022-02-01&end_date=2022-02-01"

Example Response

{
  "transactions": [
    {
      "amount": 0,
      "currency": "USD",
      "category": ["string"],
      "check_number": "string",
      "is_pending": true,
      "date": "2022-02-01",
      "authorized_date": "2022-02-01",
      "merchant_name": "Fancy store",
      "payment_channel": "IN_STORE",
      "payment_method": "string",
      "transaction_id": "string"
    }
  ]
}

Get Balance

You can retrieve an external account balance by specifying an external_account_id. The response includes the following balance information:

available: The available account balance in cents. For example, 1000 represents $10.00.
current: The current account balance in cents.
currency: The ISO 4217 alphabetic currency code.
limit: The limit on the balance amount.

Example Request

curl -H 'Authorization: Bearer $apikey' \
     -H 'Content-Type: application/json' https://api.synctera.com/v0/external_accounts/df0978ca-9816-4b3f-b3c1-9f1354e062fe/balance

Example Response

{
  "available": 10000,
  "current": 11000,
  "currency": "SEK",
  "limit": 20000
}

Account Management

List External Accounts

You can view all external accounts (or optionally filter them by personal customer with the query parameter customer_id, or business customer with business_id) with the following example:

Example Request

curl -X POST \
  -H 'Authorization: Bearer $apikey' \
  -H 'Content-Type: application/json' https://api.synctera.com/v0/external_accounts

Example Response

{
  "external_accounts": [
    {
      "account_identifiers": {
        "number": "0000"
      },
      "account_owner_names": [],
      "creation_time": "2022-04-08T22:43:43.990785Z",
      "customer_id": "17f4c82d-a398-48ed-a9c8-5bd9a53fe862",
      "id": "1542ea0f-09ef-410c-9d66-57f36af5b52b",
      "last_updated_time": "2022-04-08T22:43:43.990785Z",
      "metadata": {},
      "nickname": "Plaid Checking",
      "routing_identifiers": {
        "ach_routing_number": "1533",
        "bank_countries": ["US"],
        "bank_name": "Chase"
      },
      "status": "ACTIVE",
      "type": "CHECKING",
      "vendor_data": {
        "account_number_mask": "0000",
        "institution_id": "ins_3"
      },
      "vendor_info": {
        "content_type": "application/json",
        "json": {
          "addresses": null,
          "emails": null,
          "names": null,
          "phone_numbers": null
        },
        "vendor": "PLAID"
      },
      "verification": {
        "creation_time": "2022-04-08T22:43:43.990785Z",
        "last_updated_time": "2022-04-08T22:43:43.990785Z",
        "status": "VERIFIED",
        "vendor": "PLAID"
      }
    }
  ]
}

View Specific External Account

You might want to get information about a single account, for that you'll just need the account id.

Example Request

curl -H 'Authorization: Bearer $apikey' \
     -H 'Content-Type: application/json' https://api.synctera.com/v0/external_accounts/1542ea0f-09ef-410c-9d66-57f36af5b52b

Example Response

{
  "account_identifiers": {
    "number": "0000"
  },
  "account_owner_names": [],
  "creation_time": "2022-04-08T22:43:43.990785Z",
  "customer_id": "17f4c82d-a398-48ed-a9c8-5bd9a53fe862",
  "id": "1542ea0f-09ef-410c-9d66-57f36af5b52b",
  "last_updated_time": "2022-04-08T22:43:43.990785Z",
  "metadata": {},
  "nickname": "Plaid Gold Standard 0% Interest Checking",
  "routing_identifiers": {
    "ach_routing_number": "1533",
    "bank_countries": ["US"],
    "bank_name": "Chase"
  },
  "status": "ACTIVE",
  "type": "CHECKING",
  "vendor_data": {
    "account_number_mask": "0000",
    "institution_id": "ins_3"
  },
  "vendor_info": {
    "content_type": "application/json",
    "json": {
      "addresses": null,
      "emails": null,
      "names": null,
      "phone_numbers": null
    },
    "vendor": "PLAID"
  },
  "verification": {
    "creation_time": "2022-04-08T22:43:43.990785Z",
    "last_updated_time": "2022-04-08T22:43:43.990785Z",
    "status": "VERIFIED",
    "vendor": "PLAID"
  }
}

Unlink External Account

Deleting an account from Synctera does not mean it will delete its link through Plaid. If you want to unlink an account with Plaid, you need to follow these steps:

Create a link token in update mode.
Like in all previous calls that have customer_id in the request body or as a query parameter, if this is an account that belongs to a business, you have to provide business_id instead of customer_id.

Example Request

curl -X POST \
  -H 'Authorization: Bearer $apikey' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "client_name": "Name of your application",
    "customer_id":"27b1bfd0-d83f-42bc-9b2a-a0241adcba9a",
    "country_codes": [
      "US"
    ],
    "type":"DEPOSITORY",
    "language": "EN",
    "vendor_institution_id": "ins_3"
  }' https://api.synctera.com/v0/external_accounts/link_tokens

Example Response

{
  "client_name": "Name of your application",
  "country_codes": ["US"],
  "customer_id": "17f4c82d-a398-48ed-a9c8-5bd9a53fe862",
  "expiration": "2022-04-11T07:04:42Z",
  "language": "EN",
  "link_token": "link-sandbox-ad4acabf-8290-4731-b1ea-8629060b97a9",
  "request_id": "rM3eu8wSqKlR5mk",
  "type": "DEPOSITORY",
  "vendor_access_token": "access-sandbox-69e649e2-93ef-41b5-93ef-34fea33a2a50",
  "vendor_institution_id": "ins_3",
  "verify_owner": false
}

Use the newly created link token to launch Plaid Link, fill your credentials and uncheck the accounts you wish to unlink and click Continue. You can also check and link accounts in this same institution that were not linked before. After you clicked Continue you should have the accounts information updated.

The unlinked accounts can now be deleted from Synctera using the delete endpoint. If you linked new accounts you need to add them to Synctera or you'll have no way to access them. You can update the accounts in Synctera with the Sync Vendor Accounts endpoint

Sync Vendor Accounts

After running Plaid Link UI in update mode, you can unlink accounts and also link new ones in the same institution. These changes happen only in Plaid. You need to persist them by calling Synctera's POST external_accounts/sync_vendor_accounts. Syncing the accounts mean you will add the newly linked ones and delete the ones that were unlinked.
Provide business_id for accounts associated with business customers, customer_id for accounts associated with personal customers.

Important:
Owner Identity verification is not supported for accounts associated with business customers. You should either omit verify_owner or set it to false.
Owner identity information is also not yet supported for business customers.

Example Request

curl \
  -X POST \
  https://api.synctera.com/v0/external_accounts/sync_vendor_accounts \
  -H 'Authorization: Bearer $apikey' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "customer_id": "0d36a87d-a3dc-4ab9-8732-6c05e955c7fa",
    "customer_type": "PERSONAL",
    "vendor": "PLAID",
    "vendor_access_token": "access-sandbox-de3ce8ef-33f8-452c-a685-8671031fc0f6",
    "vendor_account_ids": [
      "blgvvBlXw3cq5GMPwqB6s6q4dLKB9WcVqGDGo"
    ],
    "verify_owner": false
  }'

Example Response

{
  "added_accounts": [
    {
      "account_identifiers": {
        "iban": "IT64G416327044023JW2925VN20",
        "number": "78277121"
      },
      "account_owner_names": ["Emmett Ziemann"],
      "creation_time": "2022-01-01T00:00:00.000Z",
      "customer_id": "fe630756-8616-4584-b207-0252d234dfb3",
      "id": "320ef27f-2956-4b00-95e4-571603217a98",
      "last_updated_time": "2022-01-01T00:00:00.000Z",
      "metadata": {},
      "nickname": "Home Loan Account",
      "routing_identifiers": {
        "ach_routing_number": "756392185",
        "bank_countries": ["US"],
        "bank_name": "Chase",
        "eft_routing_number": "02101140",
        "swift_code": "CHASUS3AXXX",
        "wire_routing_number": "756392185"
      },
      "status": "ACTIVE",
      "type": "CHECKING",
      "vendor_data": {
        "account_number_mask": "string",
        "institution_id": "string"
      },
      "vendor_info": {
        "content_type": "application/json",
        "json": {},
        "vendor": "SOCURE"
      },
      "verification": {
        "creation_time": "2022-01-01T00:00:00.000Z",
        "last_updated_time": "2022-01-01T00:00:00.000Z",
        "status": "VERIFIED",
        "vendor": "PLAID"
      }
    }
  ],
  "deleted_accounts": [
    {
      "account_identifiers": {
        "iban": "IT64G416327044023JW2925VN20",
        "number": "78277121"
      },
      "account_owner_names": ["Emmett Ziemann"],
      "creation_time": "2022-01-01T00:00:00.000Z",
      "customer_id": "fe630756-8616-4584-b207-0252d234dfb3",
      "id": "320ef27f-2956-4b00-95e4-571603217a98",
      "last_updated_time": "2022-01-01T00:00:00.000Z",
      "metadata": {},
      "nickname": "Home Loan Account",
      "routing_identifiers": {
        "ach_routing_number": "756392185",
        "bank_countries": ["US"],
        "bank_name": "Chase",
        "eft_routing_number": "02101140",
        "swift_code": "CHASUS3AXXX",
        "wire_routing_number": "756392185"
      },
      "status": "ACTIVE",
      "type": "CHECKING",
      "vendor_data": {
        "account_number_mask": "string",
        "institution_id": "string"
      },
      "vendor_info": {
        "content_type": "application/json",
        "json": {},
        "vendor": "SOCURE"
      },
      "verification": {
        "creation_time": "2022-01-01T00:00:00.000Z",
        "last_updated_time": "2022-01-01T00:00:00.000Z",
        "status": "VERIFIED",
        "vendor": "PLAID"
      }
    }
  ],
  "failed_accounts": [
    {
      "reason": "FAILED_VERIFICATION",
      "reason_description": "string",
      "vendor_account_id": "blgvvBlXw3cq5GMPwqB6s6q4dLKB9WcVqGDGo",
      "vendor_error_message": "string",
      "vendor_request_id": "string"
    }
  ]
}

Delete External Account

⚠️
Deleting one account from Synctera does not unlink it from Plaid, for that you'll need to follow the guide to Unlink External Accounts

Deleting an account from Synctera is one simple call, but you can easily add it back if you haven't unlinked it with Plaid.

Example Request

curl -X DELETE \
  -H 'Authorization: Bearer $apikey' \
  -H 'Content-Type: application/json' https://api.synctera.com/v0/external_accounts/1542ea0f-09ef-410c-9d66-57f36af5b52b

Example Response

{
  "id": "1542ea0f-09ef-410c-9d66-57f36af5b52b",
  "resource": "external_account"
}

Create External Account Manually

In case you want to verify account ownership without Synctera's API, once you're done with the verification you can just manually create the external account. For detailed information visit Add an external account's spec page.
Provide business_id for accounts associated with business customers, customer_id for accounts associated with personal customers.

Example Request

curl -X POST \
  -H 'Authorization: Bearer $apikey' \
  -H 'Content-Type: application/json'
  -d '
  {
    "type": "CHECKING",
    "customer_id": "17f4c82d-a398-48ed-a9c8-5bd9a53fe862",
    "account_official_name": "whatever 2",
    "vendor_account_id": "m1w75KWEQQh57qaZlo6mIGVR5r64vDSLP74dr",
    "customer_type": "PERSONAL",
    "account_owner_names": ["Sponge Bob"],
    "routing_identifiers": {
      "bank_name": "Bank of Orion",
      "bank_countries": ["US"],
      "ach_routing_number": "110001001"
    },
    "account_identifiers": {
      "number": "31131242233323021"
    }
  }' https://api.synctera.com/v0/external_accounts/

Example Response

{
  "account_identifiers": {
    "number": "31131242233323021"
  },
  "account_owner_names": ["Sponge Bob"],
  "creation_time": "2022-04-12T23:10:16.269162Z",
  "customer_id": "17f4c82d-a398-48ed-a9c8-5bd9a53fe862",
  "id": "e5994d0f-ade9-4167-b314-f9277ffe8fa5",
  "last_updated_time": "2022-04-12T23:10:16.269162Z",
  "metadata": {},
  "routing_identifiers": {
    "ach_routing_number": "110001001",
    "bank_countries": ["US"],
    "bank_name": "Bank of Orion"
  },
  "status": "ACTIVE",
  "type": "CHECKING",
  "vendor_data": {
    "account_number_mask": ""
  },
  "verification": {
    "status": "UNVERIFIED",
    "vendor": "MANUAL"
  }
}

Update External Account

You can update account details in case that account was created manually, so if your account's details came from the vendor directly to Synctera, you don't want to use this endpoint.

Example Request

curl -X PATCH \
  -H 'Authorization: Bearer 476d901b4-a264a79-9db9-96d3dfaafb72' \
  -H 'Content-Type: application/json'
  -d '
  {
      "nickname": "Super Exciting Account"
  }' https://api.synctera.com/v0/external_accounts/1542ea0f-09ef-410c-9d66-57f36af5b52b

Example Response

{
  "account_identifiers": {
    "number": "1111222233330001"
  },
  "account_owner_names": ["Sponge Bob"],
  "creation_time": "2022-04-11T21:22:50.222189Z",
  "customer_id": "17f4c82d-a398-48ed-a9c8-5bd9a53fe862",
  "id": "30147433-6bc0-48ca-9ebd-8059319a2bdc",
  "last_updated_time": "2022-04-11T21:23:17.785664Z",
  "metadata": {},
  "nickname": "Super Exciting Account",
  "routing_identifiers": {
    "ach_routing_number": "110000001",
    "bank_countries": ["US"],
    "bank_name": "Bank of Orion"
  },
  "status": "ACTIVE",
  "type": "CHECKING",
  "vendor_data": {
    "account_number_mask": ""
  },
  "verification": {
    "status": "UNVERIFIED",
    "vendor": "MANUAL"
  }
}

Troubleshooting

These are some common error scenarios you might encounter while using the External Accounts API:

ITEM_LOGIN_REQUIRED

At times, links to connected accounts may be reset due to bank security changes, password changes, or MFA changes. When that happens you may receive the ITEM_LOGIN_REQUIRED error response to API calls. To relink your accounts and fix the connection, you should take the user through the Plaid Link UI flow in update mode.

If this error persists, please submit a Support ticket through Plaid

PRODUCTS_NOT_SUPPORTED

This error may come back when having a user add new accounts as they go through Link UI in update mode. In Update Mode, Plaid should return all accounts connected to a user. This error happens if the institution does not support this operation, this is not a problem in your integration.

INSTITUTION_NOT_RESPONDING

At times institutions may be doing maintenance on their systems or otherwise be unavailable. When this occurs you'll receive the INSTITUTION_NOT_RESPONDING error. This can generally be handled by retrying later.

If the error persists, please submit a 'Persistent HTTP 500 errors' Support ticket through Plaid.

NO_AUTH_ACCOUNTS

This error may be returned when a user can sign in and select accounts, but Plaid is unable to find account and routing numbers at the institution. For some institutions, the end user may need to specifically opt-in during the OAuth flow to share account and routing number information even if they have already opted in to sharing information about their checking or savings account.

Available Balance is null

When making a call to get the balance for an account, some institutions may not return the available balance.