External IDs allow you to reference Samsara objects using a custom ID field set by you. Additionally, you can identify some objects by their unique fields, such as vin or name (see Automatic External IDs).

The following entities support External IDs:

• Addresses
• Drivers
• Vehicles
• Trailers
• Routes
• Route Stops
• Tags

Creating External IDs

External IDs consist of key-value pairs, where the key is the name of the ID and the value is the unique identifier for that object. For example, you could have a payroll ID and a maintenance ID, allowing you to retrieve that object by either of those IDs. External IDs are represented as dictionaries for their respective objects:

{
  "externalIds" : {
    "payroll": "ABCD",
    "maintenance": "1234"
  }
}

Currently, you can only set External IDs through the API. To set an External ID, use either the POST or PATCH method for the given object and include a dictionary of External ID key-value pairs. For example:

curl --request POST 'https://api.samsara.com/fleet/drivers' \
--header 'Authorization: Bearer <<token>>' \
--data-raw '{
    "name": "Tyler Freckmann",
    "username": "tyler.freckmann",
    "password": "password",
    "externalIds": {
        "payrollSys1": "[email protected]",
        "maintenanceSys1": "Ty_Frec-%99+88+77%"
    }
}'

The above example will create a driver with two External IDs:

📘External ID Types

Both External ID keys and values are strings. Samsara will convert External ID values to strings if a different type is submitted in the request.

Uniqueness

External ID values must be unique across all entities. This means that if one object has the External ID maintenance:1234, no other objects can use the value 1234 for the maintenance ID, even if the objects are of different classes.

For example, if a driver has the external ID maintenance:1234, no other drivers or vehicles or addresses or any other object may use the value 1234 for the maintenance External ID.

Characters Limits

Both the External ID keys and values are strings.

External ID keys can only contain alphanumeric characters and cannot contain any special or punctuation characters. Keys must be 32 characters or less.

External ID values can only contain alphanumeric characters and the following special characters: @, ., _, %, +, -.

Number of Keys

There can be at most 30 unique external ID keys per object type (e.g. routes, drivers, users) for the organization.

For example, payroll and maintenance would count as two external ID keys for my organization - even if I was using them on two different classes of objects (drivers vs vehicles, for example). Samsara automatic External ID keys don't count against the limit.

Using External IDs

To retrieve or update an object by its External ID, include it in the path of the request using the following syntax: key:value. For example, the following URL would reference the driver above.

https://api.samsara.com/fleet/drivers/payrollSys1:[email protected]

Deleting External IDs

To delete an External ID from an object, overwrite the existing value with the empty string (""). For example, the following request would delete the payrollSys1 and maintenanceSys1 IDs from the driver with the Samsara ID 123456789:

curl --request PATCH 'https://api.samsara.com/fleet/drivers/123456789' \
--header 'Authorization: Bearer <<token>>' \
--data-raw '{
    "externalIds": {
        "payrollSys1": null,
        "maintenanceSys1": null
    }
}'

Automatic External IDs

Samsara will automatically populate External IDs on certain types of objects. The External ID keys will be prefixed with samsara. and will be read-only.

Current automatically populated external IDs:

📘

External ID Availability

The External ID feature is not supported across all endpoints. To identify which APIs support externalID, please refer to the request and response parameters section for your desired endpoint in our REST API Section.

If you're seeking to use an endpoint where you would like to be able to use an External ID as an input parameter please provide API feedback.