Skip to main content
GET
/
v2
/
telematics
/
users
/
{user_id}
Get User
curl --request GET \
  --url https://api.catenatelematics.com/v2/telematics/users/{user_id} \
  --header 'Authorization: Bearer <token>'
{
  "fleet_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "connection_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "source_id": "<string>",
  "source_data_hash": "<string>",
  "fleet_ref": "<string>",
  "deleted_at": "2023-11-07T05:31:56Z",
  "tsp_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "tsp_slug": "<string>",
  "source_data": {},
  "occurred_at": "2023-11-07T05:31:56Z",
  "execution_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "schedule_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "extras": {},
  "username": "<string>",
  "started_at": "2023-11-07T05:31:56Z",
  "ended_at": "2023-11-07T05:31:56Z",
  "is_active": true,
  "status": "<string>",
  "is_driver": true,
  "user_designation": "<string>",
  "user_email": "<string>",
  "first_name": "<string>",
  "last_name": "<string>",
  "phone_number": "<string>",
  "country_code": "<string>",
  "license_country": "<string>",
  "license_region": "<string>",
  "license_number": "<string>",
  "license_expiration": "2023-12-25",
  "employee_number": "<string>",
  "company_groups": {},
  "private_user_groups": {},
  "report_groups": {},
  "security_groups": {},
  "authority_name": "<string>",
  "authority_address": "<string>",
  "company_name": "<string>",
  "company_address": "<string>",
  "carrier_number": "<string>",
  "last_tsp_login": "2023-11-07T05:31:56Z",
  "notes": "<string>",
  "allow_yard_move": true,
  "allow_personal_conveyance": true,
  "allow_adverse_driving": true
}

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Path Parameters

​
user_id
string<uuid>
required

The unique identifier of the user.

Query Parameters

​
include_source_data
boolean
default:false

Include the raw data from the telematics provider. Useful for auditing or accessing fields not normalized by Catena

Response

Successful Response

User model for API responses

​
fleet_id
string<uuid> | null
required

Internal fleet identifier.

​
id
string<uuid>
required

Unique identifier of the record at Catena Telematics.

​
created_at
string<date-time>
required

Immutable: The datetime the record was ingested into Catena Telematics.

​
updated_at
string<date-time>
required

The dateime the record was last modified in Catena Telematics.

​
connection_id
string<uuid>
required

Unique identifier of the connection at Catena Telematics through which this record was ingested. A connection represents a Fleet/TSP pairing.

​
source_name
enum<string>
required

The underlying telematics platform that provided this data (e.g., samsara, motive, hos247). Note: Some platforms like hos247 offer white-labeling, so multiple TSPs may share the same source_name — use tsp_id or tsp_slug to identify the specific ELD provider.

Available options:
ada,
ai_eld,
air_eld,
alfa_eld,
alpha_eld,
als,
anytrek_pro,
anytrek_classic,
apex_eld,
apollo,
apollocloud,
ascend,
att,
awaregps,
azuga,
bigroad,
bluehorse_eld,
blueinktech,
bouncie,
budgetgps,
catena_simulator,
captain_eld,
carrier_lynx,
club_eld,
counting_trucks_eld,
cyntrx,
digital_eld,
dragon_eld,
drive_hos,
drive_hos_v2,
driver_tech,
dsg_elogs,
dynamic_eld,
eighteighteight_eld,
eld_88,
eld_books,
eld_mandate,
eld_mandate_prime,
eroad,
eva_eld,
evo_eld,
expressway_eld,
extreme_eld,
ezlogz,
ez_lynk,
factor_eld,
firstgate,
fleetcomplete,
fleetcompletehub,
fleethunt,
fleetpulse,
fleetsharp,
fleetup,
fm,
forwardthinking,
forza_eld,
geotab,
gpsinsight,
gpstab,
gpstrackit,
grand_eld,
greenlight,
groundhog,
hcss,
hos247,
hutch,
intellishift,
ironman_eld,
isaac,
jjkeller,
kinexaiot,
knight_eld,
konexial,
lioneight,
linxup,
loop_eld,
lucid_eld,
luna_eld,
lytx,
lytxv3,
mapon,
matrack,
maven,
mdm_eld,
mobilefleet,
moonlight_eld,
motion_eld,
motive,
my_drivebook,
my_logs_eld,
nero,
netradyne,
new_eld_world,
nextgen_eld,
nextraq,
omnitracs,
onestep,
ontime_eld,
optima,
orbcomm,
orient_eld,
panda_eld,
payd,
peak_eld,
peoplenet,
phillips_connect,
phoenix,
pop_eld,
prologs,
proride_eld,
qualitylogs_eld,
randmcnally,
rastrac,
raven,
redfox,
regulog_eld,
ridehub,
roadeazy,
rock_eld,
rollingtrans,
routemate,
royal_eld,
safelane,
samsara,
selectivedrive,
simba_eld,
skybitz,
smart_elds,
sparkle_eld,
spireon,
sun_eld,
surfsight,
swift,
switchboard,
synergy_eld,
teletracnavman,
teletracnavman_director,
telogis,
tenna,
thermo_king,
think,
tive,
topcompliance_eld,
traccar,
trackease_eld,
trackpro,
traclog,
transflo,
trimble,
truckford,
truckspy,
truckx,
trueroad_eld,
tt,
txt_eld,
us_fast_eld,
verizon_connect,
vista_eld,
vistracks,
vlog_eld,
vulcansols_eld,
wialon,
webfleet,
xplore_eld,
zigzag_eld,
zms_eld,
zonar,
zubie
​
source_id
string
required

Unique identifier of the record in the TSP. Note: we generate a unique composite key based on available fields if the TSP does not provide an unique ID.

​
source_data_hash
string
required

SHA-256 hash of the source data payload. Note: we use it internally for idempotence and deduplication.

Maximum string length: 64
​
fleet_ref
string | null

External fleet reference in the partner system.

​
deleted_at
string<date-time> | null

The datetime the record was logically deleted from Catena Telematics.

​
tsp_id
string<uuid> | null

Unique identifier of the TSP at Catena Telematics from which this record was ingested.

​
tsp_slug
string | null

Human readable slug of the TSP at Catena Telematics from which this record was ingested.

​
source_data
Source Data · object

Raw source payload as ingested from the TSP. Note: use it for audit/debugging.

​
occurred_at
string<date-time> | null

Datetime of when the underlying event/observation occurred, as reported by the TSP, or the moment it was ingested by us if not available in the source data.

​
execution_id
string<uuid> | null

Unique identifier for the execution that ingested this record into Catena Telematics. Note: useful for tracing.

​
schedule_id
string<uuid> | null

Unique identifier for schedule that triggered this record's execution. Note: useful for tracing.

​
extras
Extras · object

Additional data available in the TSP (e.g., we may have external_id, provider_resource_id, etc. — this field captures all those extra attributes in a flexible way).

​
username
string | null

Unique username/login for the user (source or Catena).

​
started_at
string<date-time> | null

Timestamp when this user record became active/in service (UTC).

​
ended_at
string<date-time> | null

Timestamp when this user record ended/out of service (UTC).

​
is_active
boolean | null

Indicates whether the user is currently active.

​
status
string | null

User/account status label (e.g., 'ACTIVE', 'INACTIVE', 'SUSPENDED').

​
is_driver
boolean | null

Indicates whether the user is a driver (vs. back-office/admin).

​
user_designation
string | null

Role/title or TSP designation (e.g., 'DRIVER', 'DISPATCHER', 'ADMIN').

​
user_email
string | null

Email address for the user.

​
first_name
string | null

User's given name.

​
last_name
string | null

User's family/surname.

​
phone_number
string | null

User's phone number.

​
country_code
string | null

User's country code (ISO-3166-1 alpha-3, e.g., 'USA', 'CAN').

​
license_country
string | null

Issuing country for the driver's license (ISO-3166-1 alpha-3, e.g., 'USA', 'CAN').

​
license_region
string | null

Issuing region/subdivision for the license (state/province code, e.g., 'CA', 'ON').

​
license_number
string | null

Driver's license number as recorded by the source.

​
license_expiration
string<date> | null

License expiration date (YYYY-MM-DD, local to issuing authority).

​
employee_number
string | null

Employer/HR or payroll identifier for the user (if applicable).

​
company_groups
Company Groups · object

JSON map of company/organization group memberships (segmentation/visibility).

​
private_user_groups
Private User Groups · object

JSON map of user-specific private groups (per-user tags/categories).

​
report_groups
Report Groups · object

JSON map of reporting groups (used for dashboards/permissions).

​
security_groups
Security Groups · object

JSON map of security/role groups (authorization).

​
authority_name
string | null

Authority name associated with the user for RODS/inspection docs (as provided by the TSP).

​
authority_address
string | null

Authority mailing/address line associated with the user for RODS/inspection docs (from TSP).

​
company_name
string | null

Employer/carrier name associated with the user.

​
company_address
string | null

Employer/carrier address associated with the user.

​
carrier_number
string | null

Carrier/company identifier as provided by the TSP (e.g., USDOT/MC or internal).

​
last_tsp_login
string<date-time> | null

Timestamp of the user's last login in the source TSP (UTC).

​
notes
string | null

Free-text notes about the user (plain text).

​
hos_ruleset_code
enum<string> | null

Assigned HOS ruleset code for the user (normalized; see ref_hos_ruleset_codes).

Available options:
US_INT_PROP_60_7,
US_INT_PROP_60_7_BIG,
US_INT_PROP_60_7_BIG_SLP,
US_INT_PROP_60_7_NORST,
US_INT_PROP_60_7_NORST_SLP,
US_INT_PROP_60_7_NOBRK,
US_INT_PROP_60_7_NOBRK_BIG,
US_INT_PROP_60_7_NOBRK_BIG_SLP,
US_INT_PROP_60_7_NOBRK_SLP,
US_INT_PROP_60_7_SH,
US_INT_PROP_60_7_SH_NORST,
US_INT_PROP_70_8,
US_INT_PROP_70_8_BIG,
US_INT_PROP_70_8_BIG_SLP,
US_INT_PROP_70_8_NORST,
US_INT_PROP_70_8_NORST_SLP,
US_INT_PROP_70_8_NOBRK,
US_INT_PROP_70_8_NOBRK_BIG,
US_INT_PROP_70_8_NOBRK_BIG_SLP,
US_INT_PROP_70_8_NOBRK_SLP,
US_INT_PROP_70_8_SH,
US_INT_PROP_70_8_SH_14H,
US_INT_PROP_70_8_SH_NORST,
US_INT_PROP_SH_14H,
US_INT_PAX_60_7,
US_INT_PAX_60_7_SH,
US_INT_PAX_70_8,
US_INT_PAX_70_8_SH,
US_INT_SALESP,
US_INT_SALESP_NCDL_SH,
US_INT_OILTR_60_7,
US_INT_OILTR_70_8,
US_INT_OILWL_60_7,
US_INT_OILWL_70_8,
US_INT_RAIL_EX,
US_INT_PROP_SLPVAR,
US_INT_PROP_60_7_SLPVAR,
US_INT_PROP_70_8_SLPVAR,
US_INT_CARRIER_EX,
US_INT_NOHOS_7,
US_INT_NOHOS_8,
US_TX_INTRA_PROP_70_7,
US_TX_INTRA_SH_70_7,
US_TX_INTRA_SH_70_8,
US_CA_INTRA_PROP_80_8,
US_CA_INTRA_PAX_80_8,
US_CA_INTRA_FARM_112_8,
US_CA_INTRA_FARM_BRK,
US_CA_INTRA_FLAM_80_8,
US_CA_INTRA_FLAM_BRK,
US_CA_INTRA_SCH_80_8,
US_CA_INTRA_SCH_BRK,
US_AK_INTRA_PROP_70_7,
US_AK_INTRA_PROP_80_8,
US_AK_INTRA_PAX_70_7,
US_AK_INTRA_PAX_80_8,
US_AK_INTRA_PROP_70_7_SLP,
US_AK_INTRA_PROP_80_8_SLP,
US_FL_INTRA_PROP_70_7,
US_FL_INTRA_PROP_80_8,
US_FL_INTRA_SH_70_7,
US_FL_INTRA_SH_80_8,
US_OR_INTRA_PROP_70_7,
US_OR_INTRA_PROP_80_8,
US_MD_INTRA_SH_70_7,
US_MD_INTRA_SH_80_8,
US_NE_INTRA_PROP_70_7,
US_NE_INTRA_PROP_80_8,
US_NC_INTRA_PROP_70_7,
US_NC_INTRA_PROP_80_8,
US_ND_INTRA_PROP_70_7,
US_ND_INTRA_SH_70_7,
US_SC_INTRA_PROP_70_7,
US_SC_INTRA_PROP_80_8,
US_WA_INTRA_PROP_70_7,
US_WA_INTRA_PROP_80_8,
US_WI_INTRA_PROP_70_7,
US_WI_INTRA_PROP_80_8,
CA_FED_C1_70_7,
CA_FED_C2_120_14,
CA_FED_C1_TEAM,
CA_FED_C2_TEAM,
CA_FED_NOHOS,
CA_N60_C1_80_7,
CA_N60_C2_120_14,
CA_N60_C1_TEAM,
CA_N60_C2_TEAM,
CA_N60_NOHOS,
CA_N60_OIL,
CA_N60_OIL_TEAM,
CA_AB_PROV_PROP_70_7,
CA_SK_PROV_PROP_70_7,
CA_SK_PROV_FERT_EX,
CA_BC_PROV_LOG,
CA_S60_OIL,
CA_OIL_TEAM,
US_INT_OILTR_60_7_BIG,
US_INT_OILTR_60_7_BIG_SLP,
US_INT_OILTR_60_7_SLP,
US_INT_OILTR_70_8_BIG,
US_INT_OILTR_70_8_BIG_SLP,
US_INT_OILTR_70_8_SLP,
US_CA_INTRA_OILTR_80_8,
US_CA_INTRA_OILTR_PROP,
US_INT_OILTR_60_7_NOBRK,
US_INT_OILTR_60_7_NOBRK_BIG,
US_INT_OILTR_60_7_NOBRK_BIG_SLP,
US_INT_OILTR_60_7_NOBRK_SLP,
US_INT_OILTR_70_8_NOBRK,
US_INT_OILTR_70_8_NOBRK_BIG,
US_INT_OILTR_70_8_NOBRK_BIG_SLP,
US_INT_OILTR_70_8_NOBRK_SLP,
US_INT_OILTR_SH_12H,
US_INT_OILTR_SH_14H,
US_INT_OILTR_70_8_SH_12H,
US_INT_OILTR_70_8_SH_14H,
US_TX_INTRA_OILTR_70_7,
US_INT_OILWL_60_7_BIG,
US_INT_OILWL_60_7_BIG_SLP,
US_INT_OILWL_60_7_SLP,
US_INT_OILWL_70_8_BIG,
US_INT_OILWL_70_8_BIG_SLP,
US_INT_OILWL_70_8_SLP,
US_CA_INTRA_OILWL_80_8,
US_CA_INTRA_OILWL_PROP,
US_INT_OILWL_60_7_NOBRK,
US_INT_OILWL_60_7_NOBRK_BIG,
US_INT_OILWL_60_7_NOBRK_BIG_SLP,
US_INT_OILWL_60_7_NOBRK_SLP,
US_INT_OILWL_70_8_NOBRK,
US_INT_OILWL_70_8_NOBRK_BIG,
US_INT_OILWL_70_8_NOBRK_BIG_SLP,
US_INT_OILWL_70_8_NOBRK_SLP,
US_TX_INTRA_OILWL_70_7
​
allow_yard_move
boolean | null

Indicates whether the user is allowed to use Yard Move (YM).

​
allow_personal_conveyance
boolean | null

Indicates whether the user is allowed to use Personal Conveyance (PC).

​
allow_adverse_driving
boolean | null

Indicates whether the user can apply the Adverse Driving exemption.

​
default_time_zone
enum<string> | null

IANA time zone ID (e.g., 'America/Chicago'); used as the user's default for UI/log normalization.

Available options:
UTC,
Pacific/Honolulu,
America/Adak,
America/Anchorage,
America/Juneau,
America/Metlakatla,
America/Nome,
America/Sitka,
America/Yakutat,
America/Los_Angeles,
America/Vancouver,
America/Boise,
America/Cambridge_Bay,
America/Creston,
America/Dawson,
America/Dawson_Creek,
America/Denver,
America/Edmonton,
America/Fort_Nelson,
America/Inuvik,
America/Phoenix,
America/Whitehorse,
America/Yellowknife,
America/Chicago,
America/Menominee,
America/North_Dakota/Beulah,
America/North_Dakota/Center,
America/North_Dakota/New_Salem,
America/Rainy_River,
America/Rankin_Inlet,
America/Regina,
America/Resolute,
America/Swift_Current,
America/Winnipeg,
America/Indiana/Knox,
America/Indiana/Tell_City,
America/Detroit,
America/Iqaluit,
America/Kentucky/Louisville,
America/Kentucky/Monticello,
America/New_York,
America/Nipigon,
America/Pangnirtung,
America/Thunder_Bay,
America/Toronto,
America/Indiana/Indianapolis,
America/Indiana/Marengo,
America/Indiana/Petersburg,
America/Indiana/Vevay,
America/Indiana/Vincennes,
America/Indiana/Winamac,
America/Atikokan,
America/Blanc-Sablon,
America/Glace_Bay,
America/Goose_Bay,
America/Halifax,
America/Moncton,
America/St_Johns,
America/Mexico_City,
America/Cancun,
America/Merida,
America/Monterrey,
America/Mazatlan,
America/Chihuahua,
America/Hermosillo,
America/Tijuana,
America/Matamoros,
America/Ojinaga,
America/Ciudad_Juarez,
America/Guatemala,
America/Belize,
America/Tegucigalpa,
America/Managua,
America/Costa_Rica,
America/Panama,
America/Bogota,
America/Lima,
America/Santiago,
America/Argentina/Buenos_Aires,
America/Sao_Paulo,
America/Montevideo,
America/Puerto_Rico,
Europe/London,
Europe/Dublin,
Europe/Lisbon,
Europe/Madrid,
Europe/Paris,
Europe/Brussels,
Europe/Amsterdam,
Europe/Luxembourg,
Europe/Berlin,
Europe/Zurich,
Europe/Vienna,
Europe/Rome,
Europe/Copenhagen,
Europe/Stockholm,
Europe/Oslo,
Europe/Prague,
Europe/Budapest,
Europe/Warsaw,
Europe/Helsinki,
Europe/Tallinn,
Europe/Riga,
Europe/Vilnius,
Europe/Belgrade,
Europe/Tirane,
Europe/Sofia,
Europe/Athens,
Europe/Bucharest,
Europe/Kyiv,
Europe/Chisinau,
Europe/Istanbul,
Europe/Kaliningrad,
Europe/Moscow,
Europe/Samara,
Africa/Casablanca,
Africa/Algiers,
Africa/Tunis,
Africa/Cairo,
Africa/Tripoli,
Africa/Lagos,
Africa/Accra,
Africa/Dakar,
Africa/Abidjan,
Africa/Nairobi,
Africa/Dar_es_Salaam,
Africa/Kampala,
Africa/Johannesburg,
Africa/Maputo,
Africa/Windhoek,
Asia/Dubai,
Asia/Riyadh,
Asia/Qatar,
Asia/Kuwait,
Asia/Bahrain,
Asia/Muscat,
Asia/Baghdad,
Asia/Amman,
Asia/Beirut,
Asia/Jerusalem,
Asia/Baku,
Asia/Tbilisi,
Asia/Yerevan,
Asia/Almaty,
Asia/Tashkent,
Asia/Karachi,
Asia/Kolkata,
Asia/Dhaka,
Asia/Colombo,
Asia/Kathmandu,
Asia/Bangkok,
Asia/Ho_Chi_Minh,
Asia/Singapore,
Asia/Kuala_Lumpur,
Asia/Jakarta,
Asia/Manila,
Asia/Shanghai,
Asia/Hong_Kong,
Asia/Taipei,
Asia/Seoul,
Asia/Tokyo,
Australia/Sydney,
Australia/Melbourne,
Australia/Brisbane,
Australia/Adelaide,
Australia/Perth,
Australia/Darwin,
Australia/Hobart,
Pacific/Auckland