Custom identifiers are a way to add additional information to a connection you create within Terminal. This makes it easy for you to search for data in Terminal using your own identifiers.

You can assign the following custom identifiers to your connections:

  • external_id: External IDs may include your own identifiers to the connections you create within Terminal.

  • tags: Tags may include identifying information about the connection, such as the user’s “ID” and “email”, or information about the connection’s purpose, such as “Prospect” or “Customer”.

Assigning a Custom Identifier

During Connection Creation

When you create a connection with Terminal’s Link Component, you can assign custom identifiers by including the external_id or tags parameters.

If your application is configured to de-duplicate connections, tags will be added to an existing connection if one exists. Otherwise, a new connection with these tags will be created.

Hosted Flow

https://link.withterminal.com/?external_id=my-external-id&tags=customer,prospect&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',
    tags: ['customer', 'prospect']
  }
});

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',
    tags: ['customer', 'prospect']
  }
}).open();

After Connection Creation

You can also assign custom identifiers to an existing connection by calling the Update Current Connection API and including the appropriate parameters.

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",
  "tags": ["customer", "prospect"]
}'

Searching by Custom Identifiers

You can search for connections using custom identifiers with the List Connections API. You can search using all or any of the identifier types. For example:

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

This example searches for connections with the external ID “external-id” and tags “customer”. You can adjust the query parameters to search by any combination of external IDs and tags that suit your needs.