---
title: "Invite a person to join the firm"
method: POST
path: "/invitations"
tags: ["Invitations"]
---

# Invite a person to join the firm

`POST /invitations`

## Request

- Base URL: `https://api.smokeball.com`
- URL: `https://api.smokeball.com/invitations`
- Auth: API key in header `x-api-key` and API key in header `Authorization`

Invites a person who has no login yet to the firm associated with the authenticated client;
accepting the invitation creates their login. The invitation is recorded asynchronously, so
the returned link answers 404 for a few seconds. Set `sendEmail` to false to deliver it yourself.

## Request body

- InvitationDto: An invitation to create.
  - `email` string, email, required: Email address of the person being invited to join the firm.
  - `sendEmail` boolean: Whether the platform emails the invitation (default true); false to deliver it yourself.

## Response `202`

When the request is accepted. Returns a hypermedia 'Link' object of the invitation.

- Link
  - `id` string, nullable
  - `href` string, nullable
  - `relation` string, nullable
  - `method` string, nullable

## Other responses

- `400`: When the email address is invalid, the authenticated client carries no user id ('Inviting user is required'), a login for the email address already belongs to this firm ('Already registered with this firm') or to another firm ('Registered with another firm'), or an invitation for it has not expired yet ('An unexpired invitation already exists for this email address').
- `403`: When the inviting user is not a member of the firm ('User is not associated to the specified account'), or the authenticated client lacks the `invitations/write` scope or carries no firm account (bodyless).

## Changes

- **2026-10-02** `2f6c7f5744a8`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/smokeball/apis/smokeball-api/changes/invitations/post.md)

---

[API](https://skmtc.dev/smokeball/apis/smokeball-api.md) - [All operations](https://skmtc.dev/smokeball/apis/smokeball-api/llms.txt) - [OpenAPI document](https://skmtc.dev/smokeball/apis/smokeball-api/revisions/6e350cf667d4?raw)