Database Insights and Match (legacy)

Database Insights (beta) can increase conversion by providing instant account verification without requiring users to link a bank account via credentials. End users choosing the manual Database Insights path will not be required to log in to their financial institution and instead can enter their account and routing number manually.

Database Insights verifies account and routing numbers by checking the information provided against Plaid's known account numbers, leveraging Plaid's database of over 200 million verified accounts. If no match is found, Plaid will check the account number format against known usages by the institution associated with the given routing number. Database Insights will provide a verification status of 'pass', 'pass with caution', or 'fail' and a set of attributes that contributed to that status, such as whether a match was found or whether Plaid fell back to checking account number formats.

Database Insights does not verify that the user has access to the bank account and Database Insights does also not fully guarantee that the account exists, especially in a 'pass with caution' scenario. For these reasons, Database Insights should only be enabled where there is a low risk of fraud or ACH returns. Examples of use cases where Database Insights may be appropriate include bill payment, rent collection, business to business payments, or subscription payments.

Database Insights and Embedded Institution Search are both designed to increase adoption of ACH payment methods and are frequently used together. Database Insights is also fully compatible with the standard, non-Embedded Institution Search Link flow.

1. Starting on a page in your app, the user clicks an action that opens Plaid Link.
2. Inside of Plaid Link, the user selects an option to enter the manual verification flow and provides their account and routing number.
3. Once the user has submitted their information, Link closes and returns a public_token within the onSuccess callback.
4. Call /item/token/exchange to exchange the public_token for an access_token, then call /auth/get to obtain the account numbers and the verification results.
5. Based on the values of the verification_status and verification_insights fields returned by /auth/get, make a decision whether to proceed with the account information for ACH or to reject the account information as unverified.

Create a link_token with the following parameters:

• The products array should include only auth or transfer as a product when using Database Insights. While in most cases additional products can be added to existing Plaid Items, Items created with Database Insights are an exception and cannot be used with any Plaid products other than Auth, Transfer, Signal, or Identity Match.

• country_codes should be set to ['US'] or ['CA']– Database Insights is currently only available in the United States or Canada.
• The auth object should specify "database_insights_enabled": true.
• (Optional) Within the auth object, specify "auth_type_select_enabled": true in order to enable Auth Type Select, which will surface the manual entry point for Database Insights on the default Link screen. If Auth Type Select is not enabled, credential-based flows will be the primary UI flow and the Database Insights entry point will only appear as a fallback, except when using Embedded Institution Search.

Database Insights cannot be used in the same session as Database Match, Same-Day Micro-deposits, or Instant Micro-deposits. If any of those flows are explicitly enabled in the auth object alongside Database Insights, an error will occur when calling /link/token/create. If they are implicitly enabled due to account default settings, they will be overridden by enabling Database Insights.

1const request: LinkTokenCreateRequest = {
2  user: { client_user_id: new Date().getTime().toString() },
3  client_name: 'Plaid App',
4  products: [Products.Auth],
5  country_codes: [CountryCode.Us],
6  webhook: 'https://webhook.sample.com',
7  language: 'en',
8  auth: {
9    database_insights_enabled: true
10  },
11};
12try {
13  const response = await plaidClient.linkTokenCreate(request);
14  const linkToken = response.data.link_token;
15} catch (error) {
16  // handle error
17}

After creating a link_token for the auth product, use it to initialize Plaid Link.

When the user successfully inputs their account and routing numbers, the onSuccess() callback function will return a public_token.

1const linkHandler = Plaid.create({
2  // Fetch a link_token configured for 'auth' from your app server
3  token: (await $.post('/create_link_token')).link_token,
4  onSuccess: (public_token, metadata) => {
5    // Send the public_token and connected accounts to your app server
6    $.post('/exchange_public_token', {
7      publicToken: public_token,
8      accounts: metadata.accounts,
9    });
10
11    metadata = {
12      ...,
13      link_session_id: String,
14      institution: {
15        name: null, // name is always null for Database Insights
16        institution_id: null // institution_id is always null for Database Insights
17      },
18      accounts: [{
19        id: 'vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D',
20        mask: '1234',
21        name: null,
22        type: 'depository',
23        subtype: 'checking',
24        verification_status: ''
25      }]
26    }
27  },
28  // ...
29});
30
31// Open Link on user-action
32linkHandler.open();

In your own backend server, call the /item/public_token/exchange endpoint with the Link public_token received in the onSuccess callback to obtain an access_token. Persist the returned access_token and item_id in your database in relation to the user.

1// publicToken and accountID are sent from your app to your backend-server
2const accountID = 'vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D';
3const publicToken = 'public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d';
4
5// Obtain an access_token from the Link public_token
6const response = await client
7  .itemPublicTokenExchange({
8    public_token: publicToken,
9  })
10  .catch((err) => {
11    // handle error
12  });
13const accessToken = response.access_token;

1{
2  "access_token": "access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755",
3  "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op",
4  "request_id": "m8MDnv9okwxFNBV"
5}

Next, we can retrieve Auth data, along with the results of the Database Insights verification check, by calling /auth/get.

1const accessToken = 'access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755';
2
3// Instantly fetch Auth numbers
4const request: AuthGetRequest = {
5  access_token: accessToken,
6};
7const response = await client.authGet(request).catch((err) => {
8  // handle error
9});
10const numbers = response.numbers;

1{
2  "numbers": {
3    "ach": [
4      {
5        "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
6        "account": "9900009606",
7        "routing": "011401533",
8        "wire_routing": "021000021"
9      }
10    ],
11    "eft": [],
12    "international": [],
13    "bacs": []
14  },
15  "accounts": [
16    {
17      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
18      "balances": { Object },
19      "mask": "0000",
20      "name": null,
21      "official_name": null,
22      "verification_status": "database_insights_pass",
23      "verification_insights": { 
24        "network_status": {
25          "has_numbers_match": true, 
26          "is_numbers_match_verified": true,
27        },
28        "previous_returns": { 
29          "previous_administrative_return": false,
30        },
31        "account_number_format": "valid", 
32      },
33      "subtype": "checking",
34      "type": "depository"
35    }
36  ],
37  "item": { Object },
38  "request_id": "m8MDnv9okwxFNBV"
39}

The results of the Database Insights verification can be found in the verification_status and verification_insights fields returned by /auth/get. Based on the values in these fields, you will make a business decision on whether to accept the account numbers as verified, take additional risk mitigation steps, or reject the account numbers as unverified.

For test credentials that can be used to test Database Insights in the Sandbox environment, see Testing Database Auth or Database Insights.

Database Match enables instant manual account verification without the need for micro-deposits, instead relying on Plaid's database of known account numbers. When provided as an alternative to Same-Day Micro-deposits, Database Match can increase conversion, as the user may be able to verify instantly, without having to return to Plaid to verify their micro-deposit codes.

Database Match will present the user with the option to manually add a bank account in Link by providing their name, account number, and routing number. Plaid will then check this information against its network of over 200 million known bank accounts. Approximately 30% of user bank accounts can be verified via Database Match. If a match is not found, Database Match will fall back to routing the user to a manual micro-deposit flow, either Instant Micro-deposits or Same-Day Micro-deposits.

1. Starting on a page in your app, the user clicks an action that opens Plaid Link.
2. Inside of Plaid Link, the user selects an option to enter the manual verification flow and provides their legal name, account and routing number.
3. Plaid will confirm the account number, routing number, and name match a previously verified account.
4. If a match is confirmed, Link closes with a public_token and a verification status of database_matched.
5. If there is no match, the user will be prompted to enter the Instant or Same Day Micro-deposits flow.

When these steps are complete, you can call /item/public_token/exchange to obtain an access_token for calling endpoints such as /auth/get or /processor/token/create.

To enable Database Match, use the same settings as Same-Day Micro-deposits. You can then enable the feature in one of two ways:

• When calling /link/token/create, set auth.database_match_enabled: true.
• In the Dashboard Account Verification pane, enable Database Match.

Database Match cannot be used in the same session as Database Insights. If Database Insights is explicitly enabled in the auth object alongside Database Match, an error will occur when calling /link/token/create.

1const request: LinkTokenCreateRequest = {
2  user: { client_user_id: new Date().getTime().toString() },
3  client_name: 'Plaid App',
4  products: [Products.Auth],
5  country_codes: [CountryCode.Us],
6  webhook: 'https://webhook.sample.com',
7  language: 'en',
8  auth: {
9    database_match_enabled: true,
10    same_day_microdeposits_enabled, true
11  },
12};
13try {
14  const response = await plaidClient.linkTokenCreate(request);
15  const linkToken = response.data.link_token;
16} catch (error) {
17  // handle error
18}

When calling /auth/get, the returned object will have a verification_status value of database_matched as an indication that the user's data was verified through Database Match.

1{
2  "numbers": {
3    "ach": [
4      {
5        "account": "1111222233330000",
6        "routing": "011401533",
7        "wire_routing": "021000021"
8      }
9    ],
10    ...
11  },
12  "accounts": [
13    {
14      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
15      "balances": { Object },
16      "mask": "0000",
17      "name": "Checking...0000",
18      "official_name": null,
19      "verification_status": "database_matched",
20      "subtype": "checking",
21      "type": "depository"
22    }
23  ],
24  ...
25}

For test credentials that can be used to test Database Match in the Sandbox environment, see Testing Database Match.