Skip to main content
The external_id field on connections lets you associate a Deck resource with an identifier from your own system. This is the primary mechanism for mapping Deck connections to your users, accounts, or tenants.

​
How it works

When you create a connection, pass an external_id to link it to a record in your system: 
curl -X POST "https://api.deck.co/v2/connections" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "src_abc",
    "external_id": "user_12345",
    "auth_method": "username_password",
    "auth_credentials": {
      "username": "...",
      "password": "..."
    }
  }'
The external_id is stored on the connection and returned in all API responses and event payloads for that connection.

​
Constraints

  • Maximum length: 255 characters
  • Must be a string
  • Can be null (no external mapping)
  • Not required to be unique across connections, but in most cases you’ll want it to be meaningful

​
Multi-tenant patterns

If you’re building a platform where multiple end users connect to the same source, external_id is how you keep track of which connection belongs to which user.
The simplest pattern. Each user in your system has a single connection per source. Use your internal user ID as the external_id.
{
  "source_id": "src_bank",
  "external_id": "user_12345",
  "auth_method": "username_password",
  "auth_credentials": { ... }
}
To find a user’s connection later:
curl "https://api.deck.co/v2/connections?source_id=src_bank&external_id=user_12345" \
  -H "Authorization: Bearer sk_live_..."

​
Updating an external ID

You can update the external_id on an existing connection: 
curl -X PATCH "https://api.deck.co/v2/connections/{connection_id}" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "new_user_id"
  }'
Set it to null to remove the mapping: 
{
  "external_id": null
}

​
External IDs in events

When a connection triggers an event (e.g., task_run.completed), the event payload includes the connection’s external_id. This lets you route event processing to the right user in your system without an extra API call. 
{
  "id": "evt_abc",
  "type": "task_run.completed",
  "data": {
    "id": "trun_xyz",
    "connection_id": "conn_def",
    "external_id": "user_12345",
    "status": "completed",
    "result": "success"
  }
}
Use this to look up the user in your database and take action (send a notification, update a record, trigger a downstream process) without needing to call GET /v2/connections/{connection_id}.

​
Best practices

  • Set external_id at creation time. It’s easier to set it upfront than to backfill later.
  • Use stable identifiers. Choose IDs that won’t change, like your database primary key or a UUID. Avoid using emails or usernames that users can modify.
  • Keep it consistent. Use the same external_id format across all connections for a given user. If you use user_12345 for one source, use it for all sources.
  • Use it for filtering. The list connections endpoint supports filtering by external_id, making it easy to find all connections for a specific user. You can also search by external_id in the Dashboard.