> For the complete documentation index, see [llms.txt](https://docs.drivequant.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.drivequant.com/vehicle/ios/vehicle-management.md).

# Vehicle management

{% hint style="info" %}
Methods presented in this part are available in the `DriveKitVehicle` class
{% endhint %}

## Create a custom vehicle

It is possible to create a custom vehicle from your own data. Create your vehicle using the method:

```swift
func createCustomVehicle(
    characteristics: DKVehicleCharacteristics,
    name: String? = nil,
    id: String,
    completionHandler: @escaping (DKVehicleManagerStatus, DKVehicle?) -> Void
)
```

Each vehicle will have a unique identifier and this unique ID will be added into the trip synchronization response.

This method have the following parameters:

| Name            | Type                                                                                | Description                                                                                  |
| --------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| characteristics | [DKVehicleCharacteristics](/vehicle/ios/references-ios.md#dkvehiclecharacteristics) | Characteristics of the vehicle you want to create. Model is detailed in the References part. |
| name            | String                                                                              | The name of the vehicle you want to create                                                   |
| id              | String                                                                              | The unique identifier of the vehicle you want to create                                      |

Check the `DKVehicleManagerStatus` value to ensure your vehicle is correctly created:

| Value                    | Description                                                                                                                                                      |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| success                  | Vehicle is successfully created and saved in the local database.                                                                                                 |
| invalidCharacteristics   | Vehicle is not created and **not** saved in the local database because provided characteristics are not valid.                                                   |
| vehicleIdAlreadyUsed     | Vehicle is not created and **not** saved in the local database because the provided vehicleId already exists.                                                    |
| onlyOneGpsVehicleAllowed | This value is not returned for this service.                                                                                                                     |
| error                    | <p>Vehicle is not created and <strong>not</strong> saved in the local database because there was an unexpected error.</p><p>e.g: User not logged to DriveKit</p> |

[DKVehicle](/vehicle/ios/references-ios.md#dkvehicle) model is described in the References part.

## **Synchronize vehicle list**

You can retrieve the user’s vehicle list from the DriveQuant servers by calling the following method:

```swift
func getVehiclesOrderByNameAsc(
    type: DKVehicleSynchronizationType = .defaultSync, 
    completionHandler: @escaping (DKVehicleSyncStatus, [DKVehicle]) -> Void
) 
```

This method have the following parameter:

<table><thead><tr><th width="170.33333333333331">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>type</td><td>DKVehicleSynchronizationType</td><td><p>Can be <code>defaultSync</code> or <code>cache</code>.</p><p>- <code>defaultSync</code> will synchronize the vehicles by calling the DriveQuant servers</p><p>- <code>cache</code> will retrieve the vehicles already synchronized in the local database.</p></td></tr></tbody></table>

[DKVehicleSyncStatus](/vehicle/ios/references-ios.md#dkvehiclesyncstatus) and [DKVehicle](/vehicle/ios/references-ios.md#dkvehicle) models are described in the References part.

## **Retrieve local vehicle list**

You can retrieve the list of vehicles stored in the DriveKit local database by calling the previous method but with the type parameter to `.cache`.

## **Replace a vehicle**

Instead of deleting and then creating a new vehicle, you can use only one method to replace an existing vehicle.

{% hint style="info" %}
A previously paired beacon to that vehicle is automatically paired to the new vehicle.
{% endhint %}

### **Replace a car**

```swift
func replaceWithCarVehicle(
        oldVehicleId: String,
        characteristics: DKCarVehicleCharacteristics,
        name: String? = nil,
        liteConfig: Bool = false,
        completionHandler: @escaping (DKVehicleReplaceStatus, DKVehicle?) -> Void
)
```

This method have the following parameters:

| Name            | Type                                                                                      | Description                                              |
| --------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| oldVehicleId    | String                                                                                    | The unique identifier of the car you want to replace     |
| characteristics | [DKCarVehicleCharacteristics](/vehicle/ios/references-ios.md#dkcarvehiclecharacteristics) | Characteristics of the car you want to create            |
| name            | String                                                                                    | The name of the car                                      |
| liteConfig      | Boolean                                                                                   | Advanced configuration. Leave this parameter as `false`. |

[DKVehicleReplaceStatus](/vehicle/ios/references-ios.md#dkvehiclereplacestatus) and [DKVehicle](/vehicle/ios/references-ios.md#dkvehicle) models are described in the References part.

**Replace a truck**

```swift
func replaceWithTruckVehicle(
        oldVehicleId: String,
        characteristics: DKTruckVehicleCharacteristics,
        name: String? = nil,
        completionHandler: @escaping (DKVehicleReplaceStatus, DKVehicle?) -> Void
)
```

This method have the following parameters:

<table><thead><tr><th width="221.33333333333331">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>oldVehicleId</td><td>String</td><td>The unique identifier of the truck you want to replace</td></tr><tr><td>characteristics</td><td><a href="/pages/emVdreTs9oK5wf722cPq#dktruckvehiclecharacteristics">DKTruckVehicleCharacteristics</a></td><td>Characteristics of the truck you want to create</td></tr><tr><td>name</td><td>String</td><td>The name of the truck</td></tr></tbody></table>

[DKVehicleReplaceStatus](/vehicle/ios/references-ios.md#dkvehiclereplacestatus) and [DKVehicle](/vehicle/ios/references-ios.md#dkvehicle) models are described in the References part.

## **Delete a vehicle**

{% hint style="info" %}
When you delete a vehicle, a previously paired beacon or Bluetooth device to that vehicle is automatically unpaired and released from the vehicle. By this way, you can immediately pair the beacon or the Bluetooth device to another vehicle.
{% endhint %}

To delete a vehicle, you have to call the following method:

```swift
func deleteVehicle(
    vehicleId: String,
    completionHandler: @escaping (DKVehicleManagerStatus) -> Void
)
```

This method have the following parameter:

| Name      | Type   | Description                                            |
| --------- | ------ | ------------------------------------------------------ |
| vehicleId | String | The identifier of the vehicle that you want to delete. |

Check the `DKVehicleManagerStatus` value to ensure your vehicle is successfully deleted:

| Value                    | Description                                                                                                                                |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| success                  | Vehicle is successfully deleted and changes are saved in the local database.                                                               |
| unknownVehicle           | The specified vehicle could not be deleted because the vehicle id is not a vehicle or belongs to another user account.                     |
| invalidCharacteristics   | *This value is not returned for this service.*                                                                                             |
| vehicleIdAlreadyUsed     | *This value is not returned for this service.*                                                                                             |
| onlyOneGpsVehicleAllowed | *This value is not returned for this service.*                                                                                             |
| error                    | <p>Vehicle is not deleted and changes are not saved in the local database because there was an unexpected error.</p><p>e.g: No network</p> |

## **Rename a vehicle**

To rename a vehicle, you have to call the following method:

```swift
func renameVehicle(
    name: String,
    vehicleId: String,
    completionHandler: @escaping (DKVehicleManagerStatus) -> Void
) 
```

This method have the following parameters:

| Name      | Type   | Description                                           |
| --------- | ------ | ----------------------------------------------------- |
| name      | String | The new name for the vehicle                          |
| vehicleId | String | The identifier of the vehicle that you want to rename |

Check the `DKVehicleManagerStatus` value to ensure your vehicle is successfully deleted:

| Value                    | Description                                                                                                                                |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| success                  | Vehicle is successfully renamed and changes are saved in the local database.                                                               |
| unknownVehicle           | The specified vehicle could not be renamed because the vehicle id is not valid.                                                            |
| invalidCharacteristics   | *This value is not returned for this service.*                                                                                             |
| vehicleIdAlreadyUsed     | *This value is not returned for this service.*                                                                                             |
| onlyOneGpsVehicleAllowed | *This value is not returned for this service.*                                                                                             |
| error                    | <p>Vehicle is not renamed and changes are not saved in the local database because there was an unexpected error.</p><p>e.g: No network</p> |

## **Change the detection mode of a vehicle**

When you have a vehicle, it is necessary to set its DetectionMode type. The following function is used to select the DetectionMode of a vehicle:

```swift
func updateDetectionMode(
    vehicleId: String,
    detectionMode: DKDetectionMode,
    forceGPSVehicleUpdate: Bool = false,
    completionHandler: @escaping (DKDetectionModeStatus) -> Void
)
```

This method have the following parameters:

<table><thead><tr><th width="239.33333333333331">Name</th><th width="174">Type</th><th>Description</th></tr></thead><tbody><tr><td>vehicleId</td><td>String</td><td>The vehicle which you want to update the DetectionMode</td></tr><tr><td>detectionMode</td><td><a href="/pages/emVdreTs9oK5wf722cPq#dkdetectionmode">DKDetectionMode</a></td><td>The detection mode you want for the vehicle</td></tr><tr><td>forceGPSVehicleUpdate</td><td>Boolean</td><td><p>Optional parameter to force the <em>GPS</em> detection mode for a new vehicle if there is already a vehicle with this mode.</p><p>The default setting is false. In this case, the response of this service request will be <code>gpsModeAlreadyExists</code> and the new vehicle will not be configured in <em>GPS</em> mode. If this setting is true, the vehicle will inherit the <em>GPS</em> trigger mode and the existing vehicle that had this mode will be switched to the <code>.disabled</code> mode.</p></td></tr></tbody></table>

[DKDetectionModeStatus](/vehicle/ios/references-ios.md#dkdetectionmodestatus) model is described in the References part.

{% hint style="warning" %}
Information: If a driver has more than one vehicle, only one can be configured in `GPS` mode. If you choose a `GPS` trigger mode for a vehicle while there is already another vehicle with this trigger mode, then you must specify the appropriate action with the `forceGPSVehicleUpdate` parameter to `true`. The other vehicle will have its detection mode updated to `.disabled`.
{% endhint %}

## Get Vehicle Last Location

This function returns the location of the end of the last trip for a given vehicle.&#x20;

The returned location type is [DKTripLocation](/trip-analysis/ios/references.md#dktriplocation)

To retrieve the location at which the last recorded trip for the vehicle ended, use the following method:

```swift
func getVehicleLocation(_ vehicleId: String) -> DKTripLocation?
```

## Get Vehicle Timeline

Each time a trip is analyzed for a given vehicle, some data are aggregated in its timeline.

To get the timeline for a given vehicle, you have to call the following method:

```swift
public func getTimeline(
        vehicleId: String,
        periods: [DKPeriod],
        type: SynchronizationType = .defaultSync,
        completionHandler: @escaping (TimelineSyncStatus, [DKVehicleTimeline]?) -> Void)

```

This method have the following parameters:

<table><thead><tr><th width="187">Name</th><th width="195">Type</th><th>Description</th></tr></thead><tbody><tr><td>vehicleId</td><td>String</td><td>The unique identifier of the driver’s vehicle.</td></tr><tr><td>periods</td><td>[<code>DKPeriod</code>]</td><td><p>Get timeline data in a specific period of time.</p><p>Possible values are : <code>.week,</code> <code>.month</code>, <code>.year</code></p></td></tr><tr><td>synchronizationType</td><td><code>SynchronizationType</code></td><td><p>Define the source of the timelines data you want to retrieve.<br><br>Possible values are:<br><code>.cache</code>: No sync will be performed and the data retrieved during the last sync will be returned via the completionHandler.</p><p><code>.defaultSync</code>: the SDK will try to synchronize timelines with DriveQuant backend and then return them via the <code>completionHandler</code>.</p></td></tr></tbody></table>

The `TimelineSyncStatus` enum values are:

<table><thead><tr><th width="243">Value</th><th>Description</th></tr></thead><tbody><tr><td>success</td><td>Synchronization has been successfully performed</td></tr><tr><td>drivekitNotInitialized</td><td>DriveKit has not been initialized yet.</td></tr><tr><td>userNotConnected</td><td>No authenticated user was found.</td></tr><tr><td>vehicleNotFound</td><td>The identifier of the vehicle passed as parameter is not associated with any of the user's vehicles.</td></tr><tr><td>timelineNotFound</td><td><p>There was no timeline for the related vehicle.</p><p>This rare situation occurs only if the vehicle was created several years ago and has not yet analyzed trips.</p></td></tr><tr><td>cacheDataOnly</td><td><code>SynchronizationType</code> has been set to <code>.cache</code>.</td></tr><tr><td>failedToSyncTimelineCacheOnly</td><td>Synchronization has failed, only data retrieved during the last sync are returned.</td></tr></tbody></table>

The second argument in the `completionHandler` is a list of `DKVehicleTimeline` object, one per requested period.

`DKVehicleTimeline` model is described in the [References](/vehicle/ios/references-ios.md#dkvehicletimeline) part.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.drivequant.com/vehicle/ios/vehicle-management.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.