Assign user to customer

PUT

/users/assignments/customers

const url = 'https://api-uat.flinkey.de/v3/users/assignments/customers';
const options = {
  method: 'PUT',
  headers: {
    'Customer-ID': 'example',
    'flinkey-API-Key': '<flinkey-API-Key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"emailAddress":"user@example.com","userId":54321}'
};

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/users/assignments/customers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Customer-ID: example' \
  --header 'flinkey-API-Key: <flinkey-API-Key>' \
  --data '{ "emailAddress": "user@example.com", "userId": 54321 }'

Purpose

Assign an existing user to the selected customer context.

A user represents the access identity that can receive assignments for cars.

This operation links an existing user to the customer identified by the Customer-ID header.

For standard full partner integrations, the partner backend usually creates or resolves anonymous flinkey users directly in the intended customer context.

Use this operation when an existing user must be assigned to an additional customer context.

When to use this operation

Use this operation when the partner backend needs to assign an existing flinkey user to the selected customer.

Typical situations:

assigning an existing user to another customer context,
resolving a user that already exists but is not yet assigned to the selected customer,
recovering from a 409 CONFLICT during user creation,
reconciling user records between partner systems and flinkey,
preparing an existing user for assignment creation in the selected customer context.

In most integrations, the partner backend should persist a mapping between the partner customer or driver and the flinkey userId.

Do not assign users to customer contexts without a clear business reason.

Do not use this operation as a replacement for proper user lifecycle handling.

Validation notes

PROD validation result:

PUT /users/assignments/customers with a numeric userId returned 204 No Content when the existing user was not assigned to the selected customer.
The user was visible again through the customer-scoped user endpoints after the successful assignment.
Repeating the operation for a user already assigned to the customer returned 409 Conflict with the message Could not assign user to customer because the user is already assigned to the customer.
The positive and conflict paths were validated with userId. The alternative emailAddress request form was not separately validated.

Async behavior

Synchronous.

The assignment to the customer is completed directly by the API operation.

Webhook result

No.

This operation does not produce a webhook result.

Security notes

Never log:

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

User identifiers are environment-specific.

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

application/json

object

emailAddress

E-mail address of the user to assign

string | null

userId

Database ID of the user to assign

number | null

Example

{
  "emailAddress": "user@example.com",
  "userId": 54321
}

Responses

204

User was assigned to the customer successfully

400

Invalid e-mail address and userId given, or no valid identifier was provided

Recommended handling: Provide either a valid emailAddress or a valid userId

401

Invalid subscription key or missing / invalid access token

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

404

API Manager or user was not found

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

409

User is already assigned to the customer

Recommended handling: Treat as already assigned after reconciliation

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