plaid.connection.disconnected

A Plaid connection of one of your business entities stopped syncing and has to be reconnected by the business owner.

A bank stops accepting the credentials behind a Plaid connection often enough that it needs handling: consent expires, the account holder changes a password, or the institution starts asking for a factor Plaid cannot complete. Until someone reconnects it, that account imports nothing, and the books quietly go stale.

This event is how your integration hears about it as it happens instead of noticing a gap at close.

When it fires

The event is sent once, on the transition into the broken state. Kick does not re-send it while the connection stays broken, and it is held back when a healthy direct bank connection in Kick still covers the same account.

Only connections your integration created through Plaid Connections reach your endpoint.

Payload

{
  "event": "plaid.connection.disconnected",
  "version": 1,
  "occurredAt": 1723363200,
  "payload": {
    "connectionId": "0f1e4e0c-5f2c-4f0e-9d4a-3b3c2b7c9a11",
    "workspaceId": "8d3a1b52-9f1d-4a7e-b0a1-2c5d6e7f8a90",
    "entityId": "b6c4d2e1-7a3f-4c8b-9e0d-1f2a3b4c5d6e",
    "bankName": "Mercury",
    "errorCode": "disconnected"
  }
}

payload carries:

Field	Type	Notes
connectionId	uuid	The connection's id on Plaid Connections, so you can read or delete it
workspaceId	uuid	Workspace the entity belongs to
entityId	uuid	Entity the connection's account is assigned to
bankName	string	Institution name as Kick recorded it
errorCode	string	disconnected when the bank needs re-authentication, mfa_required when it asks for a factor Plaid cannot complete

Handling it

The connection stays broken until the business owner reconnects the account, so the useful response is to get it in front of them rather than to retry anything.