# Inviting Employees

Use the Company invitation API to send one or more people an email invitation
to join an existing Cheqi company.

Client applications can use this endpoint to simplify customer onboarding. The
permission is intentionally limited: an application can invite ordinary
company members, but it cannot create administrators or grant receipt
permissions.

## Who Can Send Invitations

| Caller | Required authorization | Allowed role and permissions |
|  --- | --- | --- |
| Company administrator | Authenticated administrator of the target company | `COMPANY_USER` or `COMPANY_ADMIN`; receipt permissions may be configured |
| Company API key | API key belonging to the exact target company, with the `company:members:invite` scope | `COMPANY_USER` or `COMPANY_ADMIN`; receipt permissions may be configured |
| Client application | Active Company Grant containing `company:members:invite`, and a Company-bound access token requested with that scope | `COMPANY_USER` only; `receiptRecipient` and `receiptWriter` must be omitted or `false` |


An application cannot invite a user to a different Company by changing the
Company ID in the URL. Cheqi resolves the authorized Company from the Grant
bound to the access token and rejects a mismatch.

No Administrator Delegation
A client application cannot invite `COMPANY_ADMIN` members. Administrator
access must be granted by an existing Company administrator using first-party
Company management.

## Obtain a Company-Bound Token

The customer must first authorize the client application for the
`company:members:invite` scope. Request a short-lived access token for that active
Grant:

```bash
curl -X POST https://api.cheqi.io/oauth2/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "grant_id": "grant-uuid",
    "scope": "company:members:invite"
  }'
```

Keep the client secret and this operation in a trusted backend. Do not send a
client secret to browser or mobile application code.

## Send an Invitation

Call `POST /company/{companyId}/invite/employees` with the Company-bound access
token:

```bash
curl -X POST \
  https://api.cheqi.io/company/company-uuid/invite/employees \
  -H "Authorization: Bearer opaque-access-token" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      "alex@example.com",
      "sam@example.com"
    ],
    "role": "COMPANY_USER",
    "receiptRecipient": false,
    "receiptWriter": false
  }'
```

For client applications, the two receipt permission fields may be omitted;
they default to `false` for `COMPANY_USER`. Sending `true` for either field, or
sending `COMPANY_ADMIN`, returns `403 Forbidden`.

The endpoint returns `200 OK` without a response body after the invitations
have been created and the emails have been sent.

## Request Fields

| Field | Required | Description |
|  --- | --- | --- |
| `emails` | Yes | A non-empty collection of valid email addresses. Cheqi trims, lowercases, and deduplicates the addresses. |
| `role` | Yes | Use `COMPANY_USER` for client-application invitations. |
| `receiptRecipient` | No | Whether the member may receive receipts for the Company. Must be omitted or `false` for client applications. |
| `receiptWriter` | No | Whether the member may write receipts for the Company. Must be omitted or `false` for client applications. |


## Invitation Lifecycle

- Each invitation is valid for seven days.
- Cheqi sends each recipient an email containing the acceptance link.
- Sending another invitation to the same normalized email address and Company
revokes the previous pending invitation and creates a new one.
- Accepting the invitation creates the Company membership with the role and
permissions from the invitation.


## Errors

| Status | Meaning |
|  --- | --- |
| `400 Bad Request` | The email collection is empty, an email is invalid, the role is missing, or the request body is otherwise invalid. |
| `401 Unauthorized` | The access token is missing, invalid, or expired. Request a new Company-bound token when it has expired. |
| `403 Forbidden` | The Grant or scope is invalid, the Company does not match, or a client application attempted to invite an administrator or grant receipt permissions. |
| `404 Not Found` | The target Company does not exist. |


## Related Guides

- [OAuth 2.0 Authentication](/authentication/oauth)
- [API Key Authentication](/authentication/api-keys)
- [Companies, Child Companies, and Stores](/companies/structure)