# Create a client

> Add a client to your Quenza workspace through the API. Quenza sends their invitation email and assigns them to the token's professional.

Source: https://quenza.com/help/api/clients/create-a-client/

Creates the client and sends them an invitation email to set up their account, in the language you choose. Until they accept it, their `status` is `pending`.

What else happens:

- The client is assigned to the professional who owns the API token.
- The **Client Created** [webhook](https://quenza.com/help/integrations/webhooks/) fires, like for a client you add by hand.
- The client counts towards your plan's client limit. When all places are taken, the request fails with `422` and `Limit reached`; see [Errors](https://quenza.com/help/api/errors/#422-validation-error).

An email address can belong to only one client in your workspace. [Sync clients from your CRM](https://quenza.com/help/api/guides/sync-clients/#handle-clients-who-already-exist) shows what to do when it is taken.

## Request

`POST https://developers.quenza.com/v1/clients`

### Request body

- `email` (string, required): Quenza sends the invitation to this address. It must not belong to another client in your workspace. Up to 255 characters. A valid email address
- `first_name` (string, required): First name. Up to 255 characters
- `last_name` (string, required): Last name. Up to 255 characters
- `phone` (string, or null): Phone number as free text, such as `+31 6 1234 5678`, or `null`. Up to 50 characters
- `gender` (string): Gender. One of `male`, `female`, `other`
- `gender_identity` (string, or null): How the client describes their gender, as free text. Up to 255 characters
- `birthdate` (string, or null): Date of birth as `YYYY-MM-DD`, before today. Format `YYYY-MM-DD`
- `timezone` (string, or null): Time zone as an IANA name, such as `Europe/Amsterdam`. Defaults to the time zone of the professional who owns the API token. One of 419 values, listed in the [OpenAPI file](https://quenza.com/help/api/openapi.json)
- `language_code` (string, or null): Language of the invitation and the client app. Defaults to English (`en`). One of `de`, `nl`, `en`, `es`, `fr`, `it`, `pt`, `fi`

### Example

```bash
curl -X POST https://developers.quenza.com/v1/clients \
  -H "Authorization: Bearer $QUENZA_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "emma.clarke@example.com",
    "first_name": "Emma",
    "last_name": "Clarke",
    "timezone": "Europe/Amsterdam",
    "language_code": "en"
  }'
```

## Response

201 Created.

### Fields of data

- `id` (string): The client’s ID. Use it in the URL of the other client endpoints and to add the client to a group.
- `email` (string): Email address, unique in your workspace.
- `first_name` (string): First name.
- `last_name` (string): Last name.
- `status` (string): `pending` until the client accepts the invitation, then `active`. `archived` after you archive the client. One of `active`, `pending`, `archived`
- `is_guest` (boolean): Whether the client is a guest without a login. Clients created through the API are never guests.
- `timezone` (string): Time zone as an IANA name, such as `Europe/Amsterdam`.
- `phone` (string, or null): Phone number as free text, such as `+31 6 1234 5678`, or `null`.
- `gender` (string, or null): Gender, or `null`. One of `male`, `female`, `other`
- `gender_identity` (string, or null): How the client describes their gender, as free text, or `null`.
- `birthdate` (string, or null): Date of birth as `YYYY-MM-DD`, or `null`. Format `YYYY-MM-DD`
- `invited_at` (string, or null): When the invitation email was sent. ISO 8601 date and time in UTC
- `invitation_accepted_at` (string, or null): When the invitation was accepted, or `null` while it is pending. ISO 8601 date and time in UTC
- `archived_at` (string, or null): When it was archived, or `null`. ISO 8601 date and time in UTC
- `created_at` (string): When it was created. ISO 8601 date and time in UTC
- `updated_at` (string): When it was last changed. ISO 8601 date and time in UTC

```json
{
  "data": {
    "id": "8GJ4D9KQ",
    "email": "emma.clarke@example.com",
    "first_name": "Emma",
    "last_name": "Clarke",
    "status": "pending",
    "is_guest": false,
    "timezone": "Europe/Amsterdam",
    "phone": null,
    "gender": null,
    "gender_identity": null,
    "birthdate": null,
    "invited_at": "2026-11-15T10:00:00.000000Z",
    "invitation_accepted_at": null,
    "archived_at": null,
    "created_at": "2026-11-15T10:00:00.000000Z",
    "updated_at": "2026-11-15T10:00:00.000000Z"
  }
}
```

Status codes: 201 Created, 401 Unauthenticated, 402 Workspace not active, 403 Not on your plan, 406 Not acceptable, 415 Wrong content type, 422 Validation error. See /help/api/errors/.
