Playing in Plaid’s Sandbox

I had a software client who required an integration to Plaid, a financial technology company specializing in bank login verification.

If you are in a similar position, and are attempting to get started with Plaid’s Application Programming Interface (API), then this post may be of assistance to you in setting up and using their Plaid Postman Collection with Postman (if not, then this post will probably not make that much sense, and I will not be offended if you bail out now).

I found that even with the Plaid documentation, it still took me quite a bit of time to figure out how to get valid responses from the Plaid Sandbox. I originally submitted the content of this post as a documentation pull request, but it seems that Plaid was not interested, and so I figure it can live here on my blog.

The following is meant to be read after you have completed the steps in the Getting Started section of the Plaid Postman README.

Making Plaid API calls

Most Plaid API calls require a Plaid Token in the form of an access_token (or an asset_report_token when dealing with a Plaid Asset).

After you have imported and configured the request collection in Postman, if you open up the Retrieve Auth request and click the Send button, you will receive something like the following error:

Opening up the Body tab of the request will reveal the issue:

You can see that the access_token contains an invalid place holder ("ENTER_ACCESS_TOKEN_HERE"), leading to the request failing. So, how can you use the Postman Collection to generate a valid access_token?

You will need to emulate the Exchange Token Flow process by using the following included API requests:

• Create Item [Sandbox Only]
• Exchange Token

Only then can you begin using the generated access_token to make other requests. So, let’s set about doing just that.

Create a Public Token

First, you need to create a public_token using the Create Item [Sandbox Only] request. Simply open it up, click the Send button, and you should see a response similar to the following:

If you are going to need to use the Assets API, then make sure you open up the Body tab of the request and add "assets" to the initial_products array, and then generate your token. Otherwise, your public_token will not have the correct permissions set to use Assets:

Create an Access Token

Next, use the public_token you generated in the previous step to generate an access_token with the Exchange Token request.

Paste your public_token into the "public_token" field into the Body section of the request. Click the Send button, and you should see a response similar to the following:

An access_token associated to an Item does not expire, so you can use it in all of your requests. The Postman Collection has an access_token environment variable field available where you can store your generated access token, so I would suggest putting your newly generated token in there.

Use Access Token in API Calls

Now, go back to the Retrieve Auth request that failed earlier, open up the Body of the request, and set the access_token field to be a reference to the access token set in your environment variables. Do this by changing the value to be "{{access_token}}". Then, click the Send button, and you should see a successful response.

You can now repeat this step for any other Plaid API that requires an access_token.

Create an Asset Report Token

As well as using access_tokens, Plaid Asset Reports have their own asset_report_token that need to be used when using the Retrieve an Asset Report request.

You generate an asset_report_token using the Create Asset Report request.

Open up the request Body tab, and add a reference to your access token ("{{access_token}}") to the array in the access_tokens field. Then, click the Send button, and you should see a response similar to the following:

(The options object that is included by default in the Body was removed here for brevity).

Similar to an access_token, an asset_report_token also does not expire, so you can use it in all of your asset report-related requests.

The Postman Collection has an asset_report_token environment variable field available where you can store your generated token, so I would suggest putting it here with your access_token.

Use Asset Report Token in API Calls

Now, you can try an API request like the Retrieve an Asset Report (JSON) request, which requires an asset_report_token.

Open up the Body of the request, and set the asset_report_token field to be a reference to the asset report token set in your environment variables ("{{asset_report_token}}"). Then, click the Send button, and you should see a successful response.

You should now be all set up and ready to begin playing in Plaid’s Sandbox with any API that requires an access_token or asset_report_token.