Create car

PUT

/cars

curl --request PUT \
  --url https://api-uat.flinkey.de/v3/cars \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Customer-ID: example' \
  --header 'flinkey-API-Key: <flinkey-API-Key>' \
  --data '{ "name": "VW Golf Fleet-01" }'

• UAT — start all integrations here (Portal: https://portal-uat.flinkey.com)
• PROD — available after validation (Portal: https://portal.flinkey.com)

Purpose

Create a new car in the selected customer context.

A car represents the vehicle access object used by the flinkey API.

For developer integrations, the flinkey BLE Box is abstracted behind the Car concept.

The returned car ID can be used to inspect, update or assign access to the created car.

When to use this operation

Use this operation when the partner backend needs to create a new flinkey car for a partner vehicle.

Typical situations:

• initial vehicle setup,
• adding a new vehicle to the partner fleet,
• creating a flinkey car after no existing mapping was found,
• preparing a vehicle before assignment creation,
• onboarding a new vehicle type or fleet segment.

In most integrations, the partner backend should first check whether a flinkey car already exists for the partner vehicle.

Do not create duplicate cars for the same partner vehicle without reconciliation.

After successful creation, persist the mapping between the partner vehicle ID and the flinkey carId.

Validation notes

PROD validation result:

• PUT /cars with the minimal body { "name": "{{CAR_NAME}}" } returned 201 Created.
• The response body contained only a numeric id.
• A subsequent GET /cars/{carId} returned the supplied name.
• Optional fields omitted during creation were returned as empty strings in the validated lookup response: description, vin, licensePlate, brand and model.
• The operation completed synchronously and produced no webhook.

Async behavior

Synchronous.

The new car ID is returned directly in the API response. Retrieve the complete car object with GET /cars/{carId}.

Webhook result

No.

This operation does not produce a webhook result.

Security notes

Never log:

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

Car identifiers are environment-specific.

Do not mix UAT and PROD car IDs.

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

Authorizations

• apiKey
• bearerAuth

Parameters

Header Parameters

Customer-ID

required

string

Customer database ID

Request Body^required

Media typeapplication/json

object

name

required

Car name

string

description

Optional car description

string | null

vin

Vehicle identification number

string | null

licensePlate

Vehicle license plate

string | null

brand

Vehicle brand

string | null

model

Vehicle model

string | null

Example

{
  "name": "VW Golf Fleet-01"
}

Responses

201

Car was created successfully

Media typeapplication/json

object

id

Newly created car database ID

number

Example

{
  "id": 12345
}

401

Invalid subscription key or missing / invalid access token

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

500

Server-side error

Recommended handling: Retry later if appropriate and escalate if persistent