External IDs make it possible to link your own identifiers to the connections you create within Terminal. This makes it easy for you to search for data in Terminal using your own identifiers.

Once you assign an external ID to a connection, all API responses and webhooks for that connection will include the external ID to make it easy to reconcile data in Terminal with your own systems.

Assigning an External ID

During Connection Creation

When you create a connection with Terminal’s Link Component, you can assign an external ID by including the external_id parameter. For example:

Hosted Flow

https://link.withterminal.com/?external_id=my-external-id&key={PUBLISHABLE_KEY}

React SDK

const terminal = useTerminalLink({
  // production or sandbox publishable key from the Terminal dashboard
  publishableKey: process.env.REACT_APP_TERMINAL_PUBLISHABLE_KEY,
  onSuccess: exchangeToken,
  params: {
    externalId: 'my-external-id'
  }
});

JavaScript SDK

TerminalLink.initialize({
  // production or sandbox publishable key from the Terminal dashboard
  publishableKey: process.env.TERMINAL_PUBLISHABLE_KEY,
  onSuccess: (result) => exchangePublicToken(result.publicToken),
  params: {
    externalId: 'my-external-id'
  }
}).open();

After Connection Creation

You can also assign an external ID to an existing connection by calling the Update Current Connection API and including the external_id parameter.

curl --request PATCH \
  --url https://api.withterminal.com/tsp/v1/connections/current \
  --header 'Authorization: <authorization>' \
  --header 'Connection-Token: <connection-token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "externalId": "external-id"
}'

Searching by External ID

You can search for connections by external ID using the List Connections API. For example:

curl --request GET \
  --url 'https://api.withterminal.com/tsp/v1/connections?externalId=external-id' \
  --header 'Authorization: <authorization>'