Skip to navigation
TelematicsFleet Operations & Tracking

🧪 Create Vehicle

Create a new vehicle. By default, the vehicle will be created asynchronously, and you can check the status of the operation using the returned operation ID.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Query parameters

is_syncbooleanOptionalDefaults to false

Whether to process the request synchronously. If true, Catena will attempt to create or update the resource immediately with the TSP and return the result in the response. When performing synchronous operations, you are responsible for handling any necessary retries in case of transient failures.If false (default), Catena will create an asynchronous operation, and you can check the status of the operation using the returned operation ID.

Request

This endpoint expects an object.
connection_idstringRequiredformat: "uuid"

Unique identifier of the connection at Catena Telematics which will be used to create this resource. A connection represents a Fleet/TSP pairing.

vehicle_namestring or nullOptional
Display name or unit number for the vehicle.
oemstring or nullOptional

Manufacturer (OEM) of the vehicle.

model_typestring or nullOptional

Manufacturer model or type designation (e.g., ‘Class 8 Tractor’, ‘Pickup’).

model_yearinteger or nullOptional

Model year (four-digit, e.g., 2022).

vinstring or nullOptional

Vehicle Identification Number (VIN), typically 17 characters; if available.

engine_vinstring or nullOptional
Engine serial number or engine VIN, if available.
license_plate_regionstring or nullOptional

Plate region/subdivision (state/province code, e.g., ‘CA’, ‘ON’).

license_plate_countrystring or nullOptionalformat: "^\w{3}$"

Plate country code (ISO-3166-1 alpha-3, e.g., ‘USA’, ‘CAN’).

license_plate_numberstring or nullOptional

License plate number (e.g., ‘HMT-3570’).

is_activeboolean or nullOptional

Indicates whether the vehicle is currently active/in service.

statusenum or nullOptional

Operational status label (e.g., ‘IN_SERVICE’, ‘OUT_OF_SERVICE’, ‘MAINTENANCE’).

notesstring or nullOptional

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

eld_idstring or nullOptional

Telematics/ELD device identifier associated with this vehicle, if any.

eld_serial_numberstring or nullOptional

Telematics/ELD device serial number, if any.

eld_device_typestring or nullOptional

Telematics/ELD device type or model family (vendor-specific).

eld_product_idstring or nullOptional

Telematics/ELD vendor product identifier (catalog/model code).

total_axlesinteger or nullOptional
Total number of axles on the vehicle.
external_idstring or nullOptional
External vehicle identifier as known in the TSP or customer's system.
speed_unitstring or nullOptional

Unit of measure for speed metrics (e.g., ‘km/h’, ‘mph’).

odometer_unitstring or nullOptional

Unit of measure for odometer readings (e.g., ‘km’, ‘mi’).

fuel_unitstring or nullOptional

Unit of measure for fuel quantities (e.g., ‘gallons’, ‘liters’).

fuel_capacitystring or nullOptional

Fuel capacity as provided by the source (text with units, e.g., ‘100 gallons’).

engine_typeenum or nullOptional

Engine/fuel type (e.g., ‘diesel’, ‘gasoline’, ‘electric’, ‘hybrid’).

Response

The vehicle was created successfully.
partner_idstringformat: "uuid"
The ID of the partner that created the operation.
connection_idstringformat: "uuid"
The ID of the connection
resourceenum

The type of resource to operate on (e.g., vehicle, driver).

operation_typeenum

The type of operation to perform (e.g., create, update).

Allowed values:
payloadmap from strings to any
The payload of the operation, containing the resource attributes to be created or updated.
idstringOptionalformat: "uuid"
Unique identifier for the resource operation.
created_atdatetimeOptional

Immutable: The datetime the record was created in Catena Telematics.

updated_atdatetimeOptional
The datetime the record was last modified in Catena Telematics.
deleted_atdatetime or nullOptional
The datetime the record was logically deleted from Catena Telematics.
resource_idstring or nullOptionalformat: "uuid"

Unique identifier of the record. Can be null for create operations where the source does not exist yet.

source_idstring or nullOptional
The unique identifier of the resource in the source system. Required for update operations.
statusenumOptional
The status of the operation
Allowed values:
logslist of objectsOptional
Log entries for each attempt to execute this operation.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
405
Method Not Allowed Error
409
Conflict Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error
501
Not Implemented Error
502
Bad Gateway Error