> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ctechnology.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/developer/getting-started/data-upload).

## 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

<Warning>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.</Warning>

## Registration

Using the API, you can register vehicles programmatically.
<Note>For single vehicle registrations, it may be more convenient to use the [c.technology web application](https://app.ctechnology.io).</Note>

Execute the following API call to register a new vehicle:

```bash theme={null}
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.

<Warning>For OEMs, the `organization_vehicle_id` has a maximum length limit. Ensure your custom IDs don't exceed this limit to avoid validation errors.</Warning>

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)

```json theme={null}
{
  "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)

```json theme={null}
{
  "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"
    }
  ]
}
```

<Info>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.</Info>

### 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:

```json theme={null}
{
  "vehicle_parts": [
    {
      "organization_part_id": "part_123",
      "instance_id": "instance_001"
    }
  ]
}
```

<Note>The field `organization_vehicle_part_id` is also supported for backwards compatibility, but `organization_part_id` is the recommended field name.</Note>

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](/api-reference/introduction) 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:

```json theme={null}
{
  "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.

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

### 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](https://app.ctechnology.io) or use the API to register multiple vehicles in a loop.

## Troubleshooting

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

<Card title="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.
</Card>

<Card title="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).
</Card>

<Card title="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.
</Card>