Docs

Clients

Create a client company

POST/v1/integration/platform/clients

Creates a company for one of your clients, connected to your platform and ready to use: send its `companyId` in `Alfa-Company-Id` from then on. Clients have no Alfa logins, and their AI Interviews use your credits. Sending the same `externalClientId` again answers 200 with the client created earlier. Requires an API key with the `clients:write` scope.

Requires an Alfa API key as a bearer token. How API keys work

Headers

  • Idempotency-Keystring

    A unique value, such as a UUID, sent unchanged on every retry of one request. A retry after the request succeeded returns the same response, marked `Idempotent-Replayed: true`, without running the operation again. Reusing a key for a different request is a 422.

    at least 1 characters · at most 255 characters

Request body

  • externalClientIdstringrequired

    Your id for the client. Sending the same one again returns the client created earlier.

    at least 1 characters · at most 200 characters

  • namestringrequired

    The client company name.

    at least 1 characters · at most 200 characters

  • countrystring | null

    Where the client is based.

Response body

  • companyIdstringrequired

    The Company ID to send in `Alfa-Company-Id` for this client.

  • externalClientIdstringrequired

    Your id for the client.

  • namestringrequired

    The client company name.

  • countrystring | nullrequired

    Where the client is based.

  • createdAtstring | nullrequired

    When the client was created.

Responses

  • 200Success.
  • 201Created.
  • 400The request is malformed: invalid JSON, an unexpected body or an unknown query parameter. Problem details
  • 401The bearer token is missing, expired or invalid. Problem details
  • 403The caller may not perform this operation, or has no active organisation. Problem details
  • 404The resource does not exist or is not visible to the caller. Problem details
  • 409The resource is not in a state that allows this, or a request with the same `Idempotency-Key` is still running. Problem details
  • 422The request failed validation; `errors` lists each invalid field. Problem details
  • 429Too many requests, or the AI service is busy. Retry after a short wait. Problem details
  • 500An unexpected error. Quote the `correlationId` to support. Problem details