---
title: "Invite a person by email, as an owner (owners only), member or viewer. A pending invitation to the same address is replaced. The link lasts seven days"
method: POST
path: "/v1/organization/invitations"
---

# Invite a person by email, as an owner (owners only), member or viewer. A pending invitation to the same address is replaced. The link lasts seven days

`POST /v1/organization/invitations`

## Request

- Base URL: `https://api.evictionsapi.com`
- URL: `https://api.evictionsapi.com/v1/organization/invitations`
- Auth: HTTP bearer

## Request body

- object
  - `email` string, email, required
  - `role` 'owner' | 'member' | 'viewer', required

## Response `201`

The invitation was emailed; the answer is the list. An `Idempotency-Key` header is ignored.

- object
  - `items` object[], required: Pending invitations, and those accepted, revoked or expired in the last 30 days, newest first.
    - `id` string, required
    - `email` string, required: Lower-cased.
    - `role` 'owner' | 'member' | 'viewer', required
    - `status` 'pending' | 'accepted' | 'revoked' | 'expired', required: A replaced or resent invitation is `revoked`: only the newest link to an address works.
    - `invitedBy` object, required
      - `id` string, required
      - `name` string, nullable, required
    - `createdAt` string, date-time, required
    - `expiresAt` string, date-time, required
  - `link` string: The invitation's link, returned only in local development; elsewhere it is only emailed.

## Other responses

- `400`: The request is invalid.
- `401`: The credential is missing or invalid.
- `403`: `forbidden`: an API key (sessions only). `permission_denied`: the person cannot manage the organization's people; or is not an owner and invites an owner (only an owner does); or is not an owner and does not hold every permission of the role (nobody grants what they do not hold: a person with only `people.manage` invites viewers).
- `404`: Not found.
- `409`: `already_member`: the address belongs to a member of the organization. `member_limit`: the organization already has 50 people.
- `422`: The case did not pass a check.
- `429`: `invitation_rate_limited`: the organization sent 20 invitations in the last 24 hours, or the person sent 20 across all their organizations, resent and replaced ones included. Nothing was sent. Please try again later.

---

[API](https://skmtc.dev/evictionsapi/apis/evictions-api.md) · [All operations](https://skmtc.dev/evictionsapi/apis/evictions-api/llms.txt) · [OpenAPI document](https://skmtc.dev/evictionsapi/apis/evictions-api/revisions/28459213a1a3?raw)