Documentation
Development
API
Plaid Links

Plaid Links

Plaid Links are supporting resources behind the normal Link resource. They provide a way to retrieve real transaction and balance data from a person's bank account using Plaid's API. These endpoints expose some basic functionality for interacting with Plaid Links through monetr's API rather than with Plaid directly.

New Plaid Link Token

In order to connect a user's account with Plaid and thus their bank account, you need to create a link token. This token is then used by the Plaid SDK in the UI in order to provide an authentication flow for that user and their bank.

Under the hood, monetr is making a call to Create Link Token (opens in a new tab).

HTTP
GET /api/plaid/token/new

Request Query Parameters

AttributeTypeRequiredDescription
use_cacheboolfalseIf true then the endpoint will not try to create another link token if one has already been created for the current user and has not been completed. This is used to reduce the number of API calls made to Plaid. It is recommended to use true for this. The endpoint will never return a Link token that has already been used.

Response Body

AttributeTypeRequiredDescription
linkTokenstringyesThe link token created from Plaid, this can be used with the Plaid SDK to authenticate a user's bank account.

New Link Token Examples

Example New Link Token Request
curl --request GET \
  --url "https://my.monetr.app/api/plaid/token/new"

Successful

If the user has not reached their limit for links 1 then they will receive a link token in the response and nothing else.

200 Ok
{
  "linkToken": "link-sandbox-af1a0311-da53-4636-b754-dd15cc058176"
}

New Link Errors

Link Limit Reached

400 Bad Request
{
  "error": "max number of Plaid links already reached"
}

Plaid API failure or other failure

500 Internal Server Error
{
  "error": "failed to create link token"
}

Plaid Token Callback

Once the user has completed authenticating their bank account using the Plaid SDK, you will be given a public_token. This new token must be exchanged with Plaid's API in order to allow monetr to access the bank data. The bank account should not be considered linked until this token is successfully exchanged2.

Self-Hosted
If webhooks are not enabled on the monetr server, then a job to retrieve transactions from Plaid will immediately be kicked off once the token has successfully been exchanged. This job will only attempt to retrieve the last 7 days of transactions from Plaid.

HTTP
POST /api/plaid/token/callback

Request Body

AttributeTypeRequiredDescription
publicTokenstringyesThe public_token you received from the Plaid Link flow via the SDK.
institutionIdstringyesThe Plaid institution_id, the API will not return an error if this is not provided (TODO). But it is required in order for the API to function properly.
institutionNamestringyesThe name of the institution as provided by the Plaid SDK. This is used as the initial name for the link until the user decides to rename it.
accountIds[]stringyesAn array of Plaid bank account IDs, this should be the list of IDs that the user selected when they were going through the link process.

Response Body

AttributeTypeRequiredDescription
linkIdintegeryesThe ID of the newly created link for the Plaid connection.

There is an additional field in the response body called success. This field is not present if the request fails and is only present if it succeeds. The status of the request is already indicated properly using the status code of the response. This field should not be used, it will be removed in the future. GitHub issue/pull request detail (opens in a new tab)

Plaid Token Callback Examples

Example Plaid Token Callback Request
curl --request POST \
  --url "https://my.monetr.app/api/plaid/token/callback" \
  --header "content-type: application/json" \
  --data '{
    "publicToken": "public-sandbox-5c224a01-8314-4491-a06f-39e193d5cddc",
    "institutionId": "ins_1",
    "institutionName": "A Banks Name",
    "accountIds": [
      "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
      "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDje"
    ]
}'

Successful

If monetr is able to exchange the public token successfully, then you will receive a successful response with the newly created Link ID.

The Link ID is not a unique identifier for Plaid, it is monetr's internal unique identifier.

200 Ok
{
  "linkId": 1234
}

Plaid Token Callback Errors

No public token provided

You must provide a public token to create a Plaid link, there is no other way to authenticate a bank account through Plaid.

400 Bad Request
{
  "error": "must provide a public token"
}

No accounts provided

If you do not provide any Plaid bank account IDs then the API will not attempt to exchange the provided public token.

400 Bad Request
{
  "error": "must select at least one account"
}

Plaid API failure or other failure

500 Internal Server Error
{
  "error": "failed to exchange token"
}

Update Plaid Link

Plaid links can be updated after they have been established. This can be used as a method of re-authenticating a link if it ends up in an error state (though sometimes a link can end up in an error state without indicating 3). This can also be used as a way to add additional accounts to a link if those accounts were not originally granted access when the link was created.

HTTP
PUT /api/plaid/link/update/{linkId}

Request Path Parameters

AttributeTypeRequiredDescription
linkIdnumberyesA link ID must be provided in order to put that link into update mode. The link must also be a Plaid link, a manual link will result in a bad request.

Request Query Parameters

AttributeTypeRequiredDescription
update_account_selectionbooleannoThis parameter is used to specify whether you want to put this link into an update mode that will allow you to add/remove accounts that are visible to monetr. This will change the Plaid Link dialog behavior slightly when it is presented to the client.

Update Link Examples

Example Update Link Request
curl --request PUT \
  --url "https://my.monetr.app/api/plaid/link/update/123?update_account_selection=true"

Successful

If the link is able to be put into update mode, then a Link Token is returned to the client. This can then be used with the Plaid Link library to allow the user to update their account selection or re-authenticate their link with their bank.

200 Ok
{
  "linkToken": "link-sandbox-af1a0311-da53-4636-b754-dd15cc058176"
}

Update Link Errors

Manual Link Update Requested

400 Bad Request
{
  "error": "cannot update a non-Plaid link"
}

Manually Resync Plaid Link

Sometimes you might need to manually trigger a resync with Plaid; this can happen if there were issues where a webhook was not properly received. By triggering a manual resync, transactions for the last 14 days and balances for all bank accounts within the specified link will be checked.

Links can be manually synced once every 30 minutes, an error will be returned if you try to resync a link too quickly.

This will not send a "sync" request to Plaid. This will only retrieve data already available via Plaid's API and update monetr's data accordingly.

HTTP
POST /api/plaid/link/sync

Request Body

AttributeTypeRequiredDescription
linkIdnumberyesThe link ID that you want to manually resync. This must be a Plaid link that is in a status of Setup or Error. Other link statuses will result in a bad request.

Manually Resync Examples

Example manual resync request
curl --request POST \
  --url "https://my.monetr.app/api/plaid/link/sync" \
  --header "content-type: application/json" \
  --data '{
    "linkId": 1234
}'

Successful

If the manual sync is kicked off successfully, you will recieve a 202 Accepted status code with no response body.

Errors

If the request fails then you will receive a JSON response body.

Provided Link does not exist

404 Not Found
{
  "error": "failed to retrieve link: record does not exist"
}

Link is not a Plaid link

400 Bad Request
{
  "error": "cannot manually sync a non-Plaid link"
}

Link is not in a valid status

400 Bad Request
{
  "error": "link is not in a valid status, it cannot be manually synced"
}

Previous manual sync was too recent

425 Too Early
{
  "error": "link has been manually synced too recently"
}

Failed to enqueue sync job

500 Internal Server Error
{
  "error": "failed to trigger manual sync"
}

Footnotes

  1. monetr can be configured to limit the number of links an account can have. This is for those using development credentials. If you intend to self-host monetr and let friends and/or family use it, it is recommended that you limit how many links someone can have to prevent someone from adding many links to their account and using up your limited number of development links. ↩

  2. If you fully authenticate a bank account, but you never exchange the public_token for that authenticated bank account. It should not affect the number of accounts linked for development credentials. ↩

  3. While working on monetr I had a link fail to receive any updates from Plaid/the bank. It still showed that it was in a healthy state though. It didn't require re-authentication but at the time putting the link through "link update" was ultimately what resolved it. ↩

LinksSpending