Create assignment

PUT

/assignments

curl --request PUT \
  --url https://api-uat.flinkey.de/v3/assignments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Customer-ID: example' \
  --header 'flinkey-API-Key: <flinkey-API-Key>' \
  --data '{ "carId": 12345, "userId": 54321, "start": "2026-01-31T10:00:00Z", "end": "2026-01-31T18:00:00Z", "lifetime": 604800, "renewableAfter": 302400 }'

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

Purpose

Create a new assignment in the selected customer context.

An assignment grants access from a user to a car for a defined time range.

This operation is used to create the access permission that allows a user to access a car.

Assignment creation is asynchronous.

The API request confirms that the assignment creation request was accepted.

The final operation result is delivered through webhook.

When to use this operation

Use this operation when the partner backend needs to grant vehicle access to a user.

Typical situations:

• creating access for a booking,
• granting a driver access to a car,
• preparing mobile access for the partner app,
• creating an unrestricted assignment,
• creating a time-limited assignment for a defined access window.

Before creating an assignment, the partner backend should have resolved:

• the correct Customer-ID,
• the flinkey carId,
• the flinkey userId,
• the intended assignment start time,
• the intended assignment end time or unrestricted assignment behavior.

Do not treat the assignment as active only because this API operation returned successfully.

Wait for the assignment created result webhook before marking the local assignment state as active.

Validation notes

PROD validation result:

• PUT /assignments returned 204 No Content without a response body.
• The direct API response represented request acceptance only.
• A configured HTTPS webhook endpoint received the assignment created result as an HTTP POST.
• The webhook contained the final numeric assignmentId, carId, userId, customerId, checksum, operationSucceeded and errorMessage fields.
• operationSucceeded was true and errorMessage was null in the successful validation.
• The created assignment was retrievable through the assignment read endpoints after successful webhook processing.

Async behavior

Asynchronous.

The API response does not represent the final assignment creation result.

The partner backend must wait for the assignment created result webhook.

The local assignment should remain in a pending state until the webhook has been processed.

Webhook result

Yes.

This operation produces an assignment created result webhook.

The webhook result determines whether assignment creation succeeded or failed.

Use operationSucceeded from the webhook payload to update the local assignment state.

Security notes

Never log:

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

Assignment identifiers are environment-specific.

Do not mix UAT and PROD assignment 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

Media typeapplication/json

object

carId

required

Database ID of the car

number

userId

required

Database ID of the user

number

start

required

Assignment start time in date-time format

string

end

required

Assignment end time in date-time format, or null for unrestricted assignment end

string | null

lifetime

Assignment lifetime in seconds

number | null

renewableAfter

Renewal timing in seconds

number | null

Example

{
  "carId": 12345,
  "userId": 54321,
  "start": "2026-01-31T10:00:00Z",
  "end": "2026-01-31T18:00:00Z",
  "lifetime": 604800,
  "renewableAfter": 302400
}

Responses

204

Assignment creation request was accepted

401

Invalid subscription key or missing / invalid access token

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

404

API Manager was not found

Recommended handling: Check credentials, token context and Customer-ID

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