> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withterminal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Identifiers

## Overview

Terminal provides customers multiple options to associate custom identifiers. This makes it easy to search for data in Terminal using these identifiers.

You can assign the following custom identifiers to your connections:

**External ID**\
A unique identifier that you can assign to connections, typically mapping to your internal system identifiers. Common uses include:

* Internal classification (submissionId, policyId, quoteId, etc.)
* Fleet ID (ID in source system)

**Tags**\
Flexible labels that help categorize and identify connections. You can use tags to track:

* Customer Account Type (pre-bind, post-bind)
* Business context (prospect, customer, enterprise)
* Internal classifications (DOT, submissionId=1234)

## Usage

### Assigning Custom Identifiers

When you create a connection with Terminal's [Link Component](/link-component), you can assign custom identifiers by including the `external_id` or `tags` parameters.

<Note>
  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.
</Note>

**Hosted Flow**

```
https://link.withterminal.com/?external_id=my-external-id&tags=customer,prospect&key={PUBLISHABLE_KEY}
```

**React SDK**

```tsx theme={null}
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', 'submissionId=1234'],
  },
});
```

**JavaScript SDK**

```ts theme={null}
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', 'submissionId=1234'],
  },
}).open();
```

### Updating Custom Identifiers

You can also assign custom identifiers to an existing connection by calling the [Update Current Connection API](/api-reference/connections/update-current-connection) and including the appropriate parameters.

```bash theme={null}
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": "new-external-id",
  "tags": ["customer", "prospect", "submissionId=1234"]
}'
```

### Searching by Custom Identifiers

You can search for connections using custom identifiers with the [List Connections API](/api-reference/connections/list-connections). You can search using all or any of the identifier types. For example:

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

This example searches for connections with the external ID `new-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.