Vehicle registration

Step-by-step guide to registering vehicles in the c.technology platform.

Vehicle registration is the process of creating a new digital twin for a vehicle on the c.technology platform. The digital twin can then be fed data via the different endpoints, as described in the data upload section.

Prerequisites

Before registering a vehicle, ensure you have:

• Valid c.technology API credentials with appropriate permissions
• Vehicle identification information (VIN, registration, etc.)
• IoT device details if you are using an IoT device (IMEI, ICCID, etc.)
• Set up your organization’s vehicle taxonomy and parts, if applicable

If you have purchased IoT devices and SIM cards from c.technology, they are pre-configured to work with the platform. You will only need your device ID to associate the vehicle with your organization.

Registration

Using the API, you can register vehicles programmatically.

Execute the following API call to register a new vehicle:

curl -X POST https://api.ctechnology.io/api/v2.2/organization/{organization_id}/vehicle/ \
  -H "Authorization: Api-key YOUR_ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My vehicle name",
    "organization_vehicle_id": "FLEET001",
    "organization_vehicle_type_id": "vtpe_1234",
    "organization_vehicle_name": "Fleet Vehicle 001",
    "organization_location_main_desc": "North Depot",
    "vehicle_identification_number": "ABC123",
    "vehicle_registration_id": "XYZ789",
    "drivetrain_type": "ELECTRIC",
    "hardware_type": "BLUETOOTH",
    "vehicle_type": "CAR",
    "iot_name": "device_001",
    "vehicle_parts": [
      {
        "organization_part_id": "part_123",
        "instance_id": "instance_001"
      }
    ]
  }'

Required and optional fields

The only required field is name, which is the display name for the vehicle in the c.technology platform.

However, depending on your organization type, additional fields may be effectively required or behave differently:

OEM organizations

If your organization is an OEM (vehicle manufacturer), you must provide organization_vehicle_type_id, which references a vehicle type defined in your organization’s taxonomy. OEMs can also specify a custom organization_vehicle_id (your internal identifier for the vehicle), which will be uppercased and used as the vehicle’s unique identifier in the system. If not provided or left empty, a random 8-character ID will be generated.

For OEMs, the organization_vehicle_id has a maximum length limit. Ensure your custom IDs don’t exceed this limit to avoid validation errors.

OEMs are automatically assigned the VEHICLE_MANUFACTURER role for vehicles they register, regardless of any role field provided.

Professional and other organizations

For professional organizations (dealers, service providers, fleet operators) and other organization types:

• organization_vehicle_id is optional and will be automatically generated as a random 8-character ID if not provided.
• organization_vehicle_type_id is optional (not required unlike for OEMs).
• You can specify the organization’s relationship to the vehicle using the role field with values VEHICLE_MAINTAINER or VEHICLE_OWNER.

Input methods

The API supports two methods for providing organization-specific vehicle data:

Method 1: Direct properties (recommended for single organization scenarios)

{
  "name": "My vehicle",
  "organization_vehicle_type_id": "vtpe_1234",
  "organization_vehicle_id": "FLEET001",
  "organization_vehicle_name": "Fleet Vehicle 001",
  "organization_location_main_desc": "North Depot",
  "role": "VEHICLE_OWNER"
}

Method 2: Nested organization_vehicles array (useful for multi-organization scenarios)

{
  "name": "My vehicle",
  "organization_vehicles": [
    {
      "organization_id": "{organization_id}",
      "vehicle_type_id": "vtpe_1234",
      "organization_vehicle_id": "FLEET001",
      "organization_vehicle_name": "Fleet Vehicle 001",
      "location_main_desc": "North Depot",
      "role": "VEHICLE_OWNER"
    }
  ]
}

When using the nested method, the organization_id in the nested object must match the one in the URL path. Values in the nested object will override any direct properties.

Additional parameters

Beyond the core identification fields, you can provide:

• vehicle_identification_number: The vehicle’s VIN (Vehicle Identification Number)
• vehicle_registration_id: The vehicle’s license plate or registration number
• drivetrain_type: The vehicle’s drivetrain type (e.g., GASOLINE, ELECTRIC, DIESEL, HYBRID)
• hardware_type: The IoT hardware type installed (e.g., BLUETOOTH, NONE)
• vehicle_type: The general vehicle classification (defaults to your organization’s primary vehicle type if not specified)
• iot_name: The IoT device identifier
• vehicle_parts: An array of vehicle parts to associate with the vehicle

Vehicle parts

If your organization has defined a parts taxonomy, you can assign parts to vehicles during registration:

{
  "vehicle_parts": [
    {
      "organization_part_id": "part_123",
      "instance_id": "instance_001"
    }
  ]
}

The field organization_vehicle_part_id is also supported for backwards compatibility, but organization_part_id is the recommended field name.

Each part requires:

• organization_part_id: The ID of the part type as defined in your organization’s parts taxonomy
• instance_id (optional): A unique identifier for this specific instance of the part

Please refer to the API reference for the complete list of parameters and their descriptions.

Response

Upon successful registration, you will receive a HTTP 200 response with the complete vehicle profile:

{
  "header": {
    "api_version": "v2.2",
    "status": "success"
  },
  "data": {
    "id": "veh_12345",
    "seaborne_id": "FLEET001",
    "name": "My vehicle name",
    "organization_id": "org_123",
    ...
  }
}

The response includes the vehicle’s unique identifier (id), the internal identifier (seaborne_id), and all other vehicle properties.

After successful registration, permission caches are automatically refreshed to ensure the vehicle appears immediately in your queries.

Updating vehicles

If you need to change the vehicle type or other details later, you can use the PUT /organization/{organization_id}/vehicle/{vehicle_id} endpoint. Similarly, you can manage vehicle part assignments using the /vehicle/{vehicle_id}/vehicle-part/ endpoints after registration.

Bulk registration

For bulk registrations, you may upload CSV files via the c.technology web app or use the API to register multiple vehicles in a loop.

Troubleshooting

This section may help you resolve common issues during vehicle registration.

SIM card configuration errors

If you encounter SIM card configuration issues, log into your carrier’s portal (e.g., 1nce, 1ot, emnify, etc.) and verify the SIM card ICCID is correct and the SIM is active.

Device communication issues

If you experience problems with device connectivity, ensure the device is powered on and has a stable cellular connection. Often, devices may take several minutes to register on the network after initial power-up. Similarly, GPS modules may take time to acquire a satellite fix, and upon initial startup may not send data before a fix is acquired (due to aquiring a correct timestamp via GPS).

API validation failures

Common validation errors and their solutions:

Organization-related errors:

• Organization does not exist: Verify the organization_id in the URL is correct and the organization exists.
• Missing organization_vehicle_type_id for OEMs: OEM organizations must provide a valid vehicle type ID. Verify the vehicle type exists in your organization’s taxonomy.
• Vehicle type does not exist: The provided organization_vehicle_type_id doesn’t match any vehicle type in your organization. Check your organization’s vehicle type definitions.

Field validation errors:

• Invalid drivetrain type: Ensure the drivetrain_type is one of the supported values (e.g., GASOLINE, ELECTRIC, DIESEL, HYBRID).
• Invalid hardware type: Verify the hardware_type is a valid option (e.g., BLUETOOTH, NONE).
• organization_vehicle_id too long: For OEMs, custom vehicle IDs have a maximum length. Use shorter identifiers or let the system generate one.

Vehicle parts errors:

• Vehicle part does not exist: The specified organization_part_id doesn’t exist in your organization’s parts taxonomy. Verify the part ID is correct.

Transaction failures:

• If vehicle creation fails mid-process, all changes are automatically rolled back to maintain data consistency. Check the error message for specific details about what failed.

Permissions:

• Missing permissions: Your API key or user token lacks vehicle creation permissions for the specified organization.