v1

latestOpenAPI 3.0.02026-07-26224386470.0 KB

Integrations

Create an integration Link

Create a Link for an active Integration every time a customer connects their bank. In Plaid, this is a Plaid Link every time a customer connects their bank. For Plaid, call this after exchanging a public token for an Item access_token.

post/api/integrations/{heron_id}/links

Path parameters

heron_idstring required

Request body

access_tokenstring required

The generated token that grants access to the bank (this is encrypted in transit and at-rest with a custom key)

asset_report_tokenstring nullable

Optional. If you already have a Plaid asset report, pass the token to skip creating a new one.

createdstring date-time

When the integration link was created in Heron system

end_user_idstring required

A unique identifier for your end user (customer) generated by you

end_user_namestring

An human readable name for this end user, like the company legal name

item_idstring required

Unique identifier for each bank connection made by your end users. In Plaid this is the 'item_id'.

last_successful_syncstring date-time

When the integration link was last successfully synced

last_updatedstring date-time

When the integration link was last updated in Heron system

The integration link status

status_messagestring

A message describing the 'erroring' status of the integration link

typestring

The integration link type, inherited from the integration: plaid_assets_report or plaid_integration

Example request

{
  "access_token": "access-sandbox-de3ce8ef-33f8-452c-a685-8671031fc0f6",
  "created": "2020-01-01T00:00:00Z",
  "end_user_id": "7de477c5-2c5f-4de4-8bc6-edb935176f9a",
  "end_user_name": "Acme Corp",
  "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op",
  "last_successful_sync": "2020-01-01T00:00:00Z",
  "last_updated": "2020-01-01T00:00:00Z",
  "status": "active",
  "status_message": "[ITEM_LOGIN_REQUIRED] the login details of this item have changed (credentials, MFA, or required user action) and a user login is required to update this information. use Link's update mode to restore the item to a good state",
  "type": "plaid_assets_report"
}

Response

Created

Example response

{
  "link": {
    "access_token": "access-sandbox-de3ce8ef-33f8-452c-a685-8671031fc0f6",
    "created": "2020-01-01T00:00:00Z",
    "end_user_id": "7de477c5-2c5f-4de4-8bc6-edb935176f9a",
    "end_user_name": "Acme Corp",
    "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op",
    "last_successful_sync": "2020-01-01T00:00:00Z",
    "last_updated": "2020-01-01T00:00:00Z",
    "status": "active",
    "status_message": "[ITEM_LOGIN_REQUIRED] the login details of this item have changed (credentials, MFA, or required user action) and a user login is required to update this information. use Link's update mode to restore the item to a good state",
    "type": "plaid_assets_report"
  }
}