> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://catena.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://catena.ferndocs.com/_mcp/server.

# User added

POST 

Emitted when a new user is added to our database.

e.g. The record fetched from the TSP is new and generated a new record in our database.

Reference: https://catena.ferndocs.com/api-reference/notifications/webhook-events/user-added

## Request

### Payload

- `version` (string, required) — Version of the schema used for this event
- `data` (list of BaseUser, required) — The event payload, with one or more records of the specified type
- `webhook_id` (string, required) — Unique identifier for the webhook subscription that triggered this delivery
- `event_name` (string, optional, default: user.added)
- `timestamp` (datetime, optional, nullable) — ISO 8601 timestamp when the event occurred
- `id` (string, optional, nullable) — Unique identifier for this specific event instance (UUID v7 for time-ordered sorting)
- `delivery_attempt` (integer, optional, default: 0) — The number of times the event has been attempted to be delivered

## Types

### BaseUser

Base user event.

- `id` (string, required) — Internal unique identifier for the telematics event record (Catena PK).
- `fleet_id` (string, required) — The Catena fleet this record belongs to (multi-tenant scope).
- `fleet_ref` (string, required, nullable) — The reference of the fleet in the partner system
- `source_name` (enum, 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.
  - Allowed values: `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`, `chronos`, `club_eld`, `cogo_eld`, `counting_trucks_eld`, `cyntrx`, `digital_eld`, `dragon_eld`, `dreyev`, `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`, `fordpro`, `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`, `michelin_connected_fleet`, `mobilefleet`, `moonlight_eld`, `motion_eld`, `motive`, `my_drivebook`, `my_logs_eld`, `nero`, `netradyne`, `new_eld_world`, `nextgen_eld`, `nextraq`, `nexus_eld`, `omnitracs`, `1sew_eld`, `onestep`, `ontime_eld`, `optima`, `optimus_tracker`, `orbcomm`, `orient_eld`, `ozod_eld`, `panda_eld`, `patriot_eld`, `payd`, `peak_eld`, `pedigree`, `peoplenet`, `phillips_connect`, `phoenix`, `pop_eld`, `prologs`, `proride_eld`, `qualitylogs_eld`, `randmcnally`, `rastrac`, `raven`, `redfox`, `regulog_eld`, `ridehub`, `rigbot`, `roadeazy`, `roadready`, `rock_eld`, `rollingtrans`, `routemate`, `route_one_eld`, `royal_eld`, `safelane`, `samsara`, `selectivedrive`, `simba_eld`, `skybitz`, `smart_elds`, `sparkle_eld`, `spireon`, `sts_eld`, `sun_eld`, `surfsight`, `swift`, `switchboard`, `synergy_eld`, `teletracnavman`, `teletracnavman_director`, `telogis`, `tenna`, `teslemetry`, `thermo_king`, `think`, `tive`, `topcompliance_eld`, `traccar`, `trackease_eld`, `trackpro`, `traclog`, `transflo`, `trimac`, `trimble`, `truckford`, `truckspy`, `truckx`, `trueroad_eld`, `tt`, `txt_eld`, `us_fast_eld`, `verizon_connect`, `vista_eld`, `vistracks`, `vlog_eld`, `vulcansols_eld`, `wialon`, `webfleet`, `wizefleet_eld`, `xplore_eld`, `zigzag_eld`, `zms_eld`, `zonar`, `zubie`
- `connection_id` (string, required) — The specific fleet↔TSP connection through which this record was sourced.
- `source_id` (string, required) — The ID of the record in the TSP or a deterministic ID/Hash generated from a composite unique key
- `created_at` (datetime, required) — Immutable: first time this record was ingested into our system.
- `updated_at` (datetime, required) — Last time we modified this record in our system.
- `occurred_at` (datetime, required) — When the underlying event/observation occurred, as reported by the TSP, or the moment it was ingested by us if not available.
- `tsp_id` (string, optional, nullable) — Unique identifier of the TSP at Catena Telematics from which this record was ingested.
- `tsp_slug` (string, optional, nullable) — Human readable slug of the TSP at Catena Telematics from which this record was ingested.
- `deleted_at` (datetime, optional, nullable) — Logical delete marker: when the TSP stopped reporting this record.
- `execution_id` (string, optional, nullable) — Identifier for the ingestion execution that processed this record (for tracing).
- `schedule_id` (string, optional, nullable) — Identifier for the ingestion schedule that triggered this record's processing (for tracing).
- `extras` (map from string to any, optional, nullable) — 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, optional, nullable) — Unique username/login for the user (source or Catena).
- `started_at` (datetime, optional, nullable) — Timestamp when this user record became active/in service (UTC).
- `ended_at` (datetime, optional, nullable) — Timestamp when this user record ended/out of service (UTC).
- `is_active` (boolean, optional, nullable) — Indicates whether the user is currently active.
- `status` (string, optional, nullable) — User/account status label (e.g., 'ACTIVE', 'INACTIVE', 'SUSPENDED').
- `is_driver` (boolean, optional, nullable) — Indicates whether the user is a driver (vs. back-office/admin).
- `user_designation` (string, optional, nullable) — Role/title or TSP designation (e.g., 'DRIVER', 'DISPATCHER', 'ADMIN').
- `user_email` (string, optional, nullable) — Email address for the user.
- `first_name` (string, optional, nullable) — User's given name.
- `last_name` (string, optional, nullable) — User's family/surname.
- `phone_number` (string, optional, nullable) — User's phone number.
- `country_code` (string, optional, nullable) — User's country code (ISO-3166-1 alpha-2, e.g., 'US', 'CA').
- `license_country` (string, optional, nullable) — Issuing country for the driver's license (ISO-3166-1 alpha-2).
- `license_region` (string, optional, nullable) — Issuing region/subdivision for the license (state/province code, e.g., 'CA', 'ON').
- `license_number` (string, optional, nullable) — Driver's license number as recorded by the source.
- `license_expiration` (date, optional, nullable) — License expiration date (YYYY-MM-DD, local to issuing authority).
- `employee_number` (string, optional, nullable) — Employer/HR or payroll identifier for the user (if applicable).
- `company_groups` (map from string to any, optional, nullable) — JSON map of company/organization group memberships (segmentation/visibility).
- `private_user_groups` (map from string to any, optional, nullable) — JSON map of user-specific private groups (per-user tags/categories).
- `report_groups` (map from string to any, optional, nullable) — JSON map of reporting groups (used for dashboards/permissions).
- `security_groups` (map from string to any, optional, nullable) — JSON map of security/role groups (authorization).
- `authority_name` (string, optional, nullable) — Authority name associated with the user for RODS/inspection docs (as provided by the TSP).
- `authority_address` (string, optional, nullable) — Authority mailing/address line associated with the user for RODS/inspection docs (from TSP).
- `company_name` (string, optional, nullable) — Employer/carrier name associated with the user.
- `company_address` (string, optional, nullable) — Employer/carrier address associated with the user.
- `carrier_number` (string, optional, nullable) — Carrier/company identifier as provided by the TSP (e.g., USDOT/MC or internal).
- `last_tsp_login` (datetime, optional, nullable) — Timestamp of the user's last login in the source TSP (UTC).
- `notes` (string, optional, nullable) — Free-text notes about the user (plain text).
- `hos_ruleset_code` (enum, optional, nullable) — Assigned HOS ruleset code for the user (normalized; see ref_hos_ruleset_codes).
  - Allowed values: `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`
- `hos_ruleset_name` (string, optional, nullable) — Human-readable name of the HOS ruleset assigned to the user (e.g., 'US Property (60/7)').
- `allow_yard_move` (boolean, optional, nullable) — Indicates whether the user is allowed to use Yard Move (YM).
- `allow_personal_conveyance` (boolean, optional, nullable) — Indicates whether the user is allowed to use Personal Conveyance (PC).
- `allow_adverse_driving` (boolean, optional, nullable) — Indicates whether the user can apply the Adverse Driving exemption.
- `default_time_zone` (enum, optional, nullable) — IANA time zone ID (e.g., America/Chicago); used as the user's default for UI/log normalization.
  - Allowed values: `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`, `Atlantic/Azores`, `Atlantic/Madeira`, `Atlantic/Canary`, `Atlantic/Faroe`, `Atlantic/Reykjavik`, `Europe/London`, `Europe/Dublin`, `Europe/Lisbon`, `Europe/Madrid`, `Europe/Gibraltar`, `Europe/Malta`, `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/Bratislava`, `Europe/Helsinki`, `Europe/Tallinn`, `Europe/Riga`, `Europe/Vilnius`, `Europe/Belgrade`, `Europe/Tirane`, `Europe/Sofia`, `Europe/Athens`, `Europe/Bucharest`, `Europe/Zagreb`, `Europe/Ljubljana`, `Europe/Sarajevo`, `Europe/Skopje`, `Europe/Podgorica`, `Europe/Kyiv`, `Europe/Chisinau`, `Europe/Minsk`, `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`