External IDs
Reference objects using a custom identifier that you provide
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 Key | Value |
---|---|
payrollSys1 | [email protected] |
maintenanceSys1 | Ty_Frec-%99+88+77% |
📘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:
Object Type | External ID Key | External ID Value |
---|---|---|
Vehicle | samsara.vin | The VIN of the vehicle. If a VIN is not available, this external ID will not exist. |
Vehicle | samsara.serial | The serial number of the Samsara Vehicle Gateway. |
Tag | samsara.name | The name of the Tag. |
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.
Updated about 22 hours ago