---
title: "Invite team members"
method: POST
path: "/v1/team/invitations"
tags: ["team"]
---

# Invite team members

`POST /v1/team/invitations`

## Request

- Base URL: `https://api.pomerado.ai`
- URL: `https://api.pomerado.ai/v1/team/invitations`
- Auth: HTTP bearer

Invites people to your team by email; each invitation lasts 7 days.

- Send one address as email, or up to 500 as invitations or as a CSV file's text in csv.
- An address already on the team, in another team or repeated in the request is refused on its own row. One already invited returns its pending invitation.
- Only an owner can invite an owner.
- With an Idempotency-Key, repeating the same request returns the first answer.

## Headers

- `Idempotency-Key` string: 1 to 200 letters, digits, _ or -, such as a UUID

## Request body

- object
  - `email` string: One address to invite; answers its Invitation
  - `role` 'owner' | 'admin' | 'member': With email: its role (default member)
  - `invitations` object[]: Up to 500 addresses, each with an optional role; answers each row's result
    - `email` string, required: a string at most 320 character(s) long
    - `role` 'owner' | 'admin' | 'member': Default: member
  - `csv` string: A CSV file's text: an email column and an optional role column, with or without a header row, up to 500 rows; answers each row's result

## Response `200`

With invitations or csv: each row's invitation or error, by index

- InvitationResults
  - `results` object[], required
    - `index` integer, required: an integer
    - `email` string, required
    - `invitation` Invitation
      - `id` string, required: The invitation's ID (invitation_…)
      - `email` string, required
      - `role` 'owner' | 'admin' | 'member', nullable, required: The role the invitee gets; null when it isn't one Pomerado knows
      - `status` 'pending' | 'expired', required
      - `invited_by` string, nullable, required: The inviter's user ID, when recorded
      - `created_at` string, required: a string to be decoded into a Date
      - `expires_at` string, required: a string to be decoded into a Date
    - `error` object
      - `code` string, required
      - `message` string, required
      - `retryable` boolean, required
      - `docs_url` string, required

## Other responses

- `201`: With email: the invitation
- `400`: invalid_request, invalid_email
- `401`: unauthorized, reauthentication_required
- `403`: role_not_allowed, role_permission_missing, team_unavailable, forbidden
- `409`: already_member, already_invited, in_another_team, idempotency_conflict
- `413`: request_too_large
- `500`: internal_error
- `503`: acceptance_unknown, temporarily_unavailable

---

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