Install product into car

PUT

/installations

const url = 'https://api-uat.flinkey.de/v3/installations';
const options = {
  method: 'PUT',
  headers: {
    'Customer-ID': 'example',
    'flinkey-API-Key': '<flinkey-API-Key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"carId":12345,"productId":67890,"serialNumber":null,"uniqueId":null}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request PUT \
  --url https://api-uat.flinkey.de/v3/installations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Customer-ID: example' \
  --header 'flinkey-API-Key: <flinkey-API-Key>' \
  --data '{ "carId": 12345, "productId": 67890, "serialNumber": null, "uniqueId": null }'

Purpose

Install a product into a car in the selected customer context.

A product represents a flinkey hardware product.

A car is the API abstraction used for vehicle-related access flows.

This operation links a product to a car.

Use this operation for operational setup workflows where a flinkey product must be assigned to a vehicle record.

When to use this operation

Use this operation when the partner backend or operational backend needs to install a product into a car.

Typical situations:

assigning a flinkey product to a car,
completing vehicle setup,
linking a physical product to a vehicle record,
preparing a car for assignment-based access flows,
correcting product-to-car setup after reconciliation,
operational support or installation workflows.

Before calling this operation, the partner backend should have resolved:

the correct Customer-ID,
the flinkey carId,
the product identifier,
whether the product already has an assigned service,
whether another product of the same type is already installed in the car.

The public API catalog does not expose an operation for creating the required service-to-product or service-to-Box relation.

In the validated UAT operating model, this relation was established by the responsible sales or administrative process before installation. Treat it as an external operational prerequisite and verify it through the product and service lookup operations before calling PUT /installations.

If the relation is missing, the installation can return 409 Conflict; do not retry the write automatically without first reconciling the product and service state.

For standard access flows, assignments are created between User and Car.

Product installation is an operational setup step and should not be treated as an access permission.

Validation notes

The controlled PROD request returned 204 No Content with an empty response body.
The product-to-car relation was immediately visible through Get products of car.
Get product returned the same product with the target carId.
Product identity fields remained unchanged.
The resulting installation was also confirmed in the Admin Portal.

Async behavior

Synchronous.

The installation result is represented by the API response.

Webhook result

No.

This operation does not produce a webhook result.

Security notes

Never log:

flinkey-API-Key,
bearer token,
full request headers.

Product and car identifiers are environment-specific.

Do not mix UAT and PROD product IDs, serial numbers, unique IDs or car IDs.

Use placeholders in documentation, examples, screenshots and AI prompts.

For standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the flinkey-API-Key.

Authorizations

apiKey
bearerAuth

Parameters

Header Parameters

Customer-ID

required

string

Customer database ID

Request Body^required

application/json

object

carId

required

Database ID of the car

number

productId

Database ID of the product

number | null

serialNumber

Product serial number

string | null

uniqueId

Unique product identifier

string | null

Example

{
  "carId": 12345,
  "productId": 67890,
  "serialNumber": null,
  "uniqueId": null
}

Responses

204

Product was installed into the car successfully

400

Invalid carId or no valid product identifier was provided

Recommended handling: Check carId, productId, serialNumber and uniqueId

401

Invalid subscription key or missing / invalid access token

Recommended handling: Check flinkey-API-Key, bearer token and environment configuration

404

API Manager, car or product was not found

Recommended handling: Check credentials, Customer-ID, car assignment and product identifier

409

Product cannot be installed because of current product, service or car state

Recommended handling: Check whether the product is already installed, has no service assigned or another product of the same type is already installed in the car

415

Request content type is missing or incorrect

Recommended handling: Ensure Content-Type: application/json is used

500

Server-side error

Recommended handling: Retry later if appropriate and escalate if persistent