---
title: "Invite someone to join an organization."
method: POST
path: "/organizations/{organizationId}/invitations"
tags: ["organizations"]
---

# Invite someone to join an organization.

`POST /organizations/{organizationId}/invitations`

## Request

- Base URL: `https://api.shorebird.dev/api/v1`
- URL: `https://api.shorebird.dev/api/v1/organizations/{organizationId}/invitations`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Emails an invitation to join the team organization with the given
role. The invitation is valid for 14 days; the invitee accepts it
with `POST /invitations/{invitationId}/accept`. Requires the
`invitations.create` permission, which the `admin` and `owner`
roles hold.

The `owner` role cannot be granted by invitation. Inviting anyone
needs the organization's plan to include collaboration, and roles
other than `developer` must be offered by that plan. When the
organization restricts members to allowed email domains, the email
must be in one of them. An organization holds at most 50 pending
invitations.

When the organization belongs to an enterprise and the email is an
account already in that enterprise's directory, no invitation is
sent: the account is added as a member at the role at once, and the
response's `type` is `member` rather than `invitation`.

## Request body

- CreateOrganizationInvitationRequest: The request body for POST /organizations/{organizationId}/invitations.
  - `email` string, email, required: The email address to send the invitation to.
  - `role` 'owner' | 'admin' | 'appManager' | 'developer' | 'viewer' | 'auditor' | 'scim' | 'none', required: A role that a user can have relative to an Organization or App.

## Response `201`

The invitation was created and sent (`type` `invitation`), or the
account, being in the directory of the organization's
enterprise, was added as a member (`type` `member`).

- union
  - CreateInvitationResponse: The response body for creating an invitation to an organization or an app.
    - `type` 'invitation', required: Always `invitation`: what was created is a pending invitation, not a membership.
    - `email` string, required: The email the invitation was sent to.
  - AddedMemberResponse: The response body for inviting an account that is already in the directory of the organization's enterprise: it was added as a member at once, and no invitation was sent.
    - `type` 'member', required: Always `member`: what was created is a membership, not a pending invitation.
    - `email` string, required: The email the request named.
    - `role` 'owner' | 'admin' | 'appManager' | 'developer' | 'viewer' | 'auditor' | 'scim' | 'none', required: A role that a user can have relative to an Organization or App.

## Other responses

- `400`: The organization id is not an integer (`organization_id_malformed`), or the body could not be parsed (`organization_invitations_create_error`).
- `403`: The caller lacks the `invitations.create` permission; the role is `owner`, or the email's domain is not allowed (`organization_invitations_create_error`); or the organization's plan does not include collaboration, or does not offer the role (`shorebird_plan_insufficient_tier`).
- `404`: No such organization, or the caller is not a member of it (`organization_membership_guard_error`).
- `409`: The invitee is already a member (`organization_invitations_already_member`), or an invitation to this email is already pending (`organization_invitations_already_pending`).
- `424`: Reading the plan, the allowed domains or the membership, or creating the invitation, failed (`organization_invitations_create_error` or `shorebird_plan_lookup_error`).
- `429`: The organization already has 50 pending invitations (`organization_invitations_cap_reached`).
- `default`: Standard error response. Emitted for any non-2xx status where a body can be decoded into an [ErrorResponse].

---

[API](https://skmtc.dev/shorebird/apis/shorebird-codepush-api.md) - [All operations](https://skmtc.dev/shorebird/apis/shorebird-codepush-api/llms.txt) - [OpenAPI document](https://skmtc.dev/shorebird/apis/shorebird-codepush-api/revisions/941da8871d10?raw)