---
title: "Invite user to a project by email"
method: POST
path: "/projects/{project_id}/invitations"
tags: ["Project Invitations"]
---

# Invite user to a project by email

`POST /projects/{project_id}/invitations`

Creates an invitation to a project for a user with the specified email address.

## Request body

- object
  - `role` 'admin' | 'viewer' — The role the invitee should be given on the project.
  - `email` string, email, required — The email address of the invitee.
  - `permissions` object[] — Specifying the role on each environment type.
    - `type` 'production' | 'staging' | 'development' — The environment type.
    - `role` 'admin' | 'viewer' | 'contributor' — The role the invitee should be given on the environment type.
  - `environments` object[] — (Deprecated, use permissions instead) Specifying the role on each environment.
    - `id` string — The ID of the environment.
    - `role` 'admin' | 'viewer' | 'contributor' — The role the invitee should be given on the environment.
  - `force` boolean — Whether to cancel any pending invitation for the specified invitee, and create a new invitation.

## Response `201`

Created

- ProjectInvitation
  - `id` string, uuid — The ID of the invitation.
  - `state` 'pending' | 'processing' | 'accepted' | 'cancelled' | 'error' — The invitation state.
  - `project_id` string — The ID of the project.
  - `role` 'admin' | 'viewer' — The project role.
  - `email` string, email — The email address of the invitee.
  - `owner` object — The inviter.
    - `id` string, uuid — The ID of the user.
    - `display_name` string — The user's display name.
  - `created_at` string, date-time — The date and time when the invitation was created.
  - `updated_at` string, date-time — The date and time when the invitation was last updated.
  - `finished_at` string, date-time, nullable — The date and time when the invitation was finished.
  - `environments` object[]
    - `id` string — The ID of the environment.
    - `type` string — The environment type.
    - `role` 'admin' | 'viewer' | 'contributor' — The environment role.
    - `title` string — The environment title.

## Other responses

- `400` — Bad Request
- `402` — Payment Required when the number of users exceeds the subscription limit
- `403` — Forbidden
- `404` — Not Found
- `409` — Conflict when there already is a pending invitation for the invitee

---

[API](https://skmtc.net/upsun/apis/upsun-com-rest-api.md) · [All operations](https://skmtc.net/upsun/apis/upsun-com-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/upsun/upsun-com-rest-api/revisions/6cc88fde6435/schema)