API

Invites

Invites are pending membership requests sent to an email address. When an invite is accepted through the Phase console, the recipient becomes an organisation member with the assigned role. On this page, we'll look at the API endpoints for listing and cancelling pending invites.

To send an invite, use the Members API (POST /v1/members/).

The Invite model

Properties

Name
id
Type
string
Description
Unique identifier for the invite.
Name
inviteeEmail
Type
string
Description
The email address the invite was sent to.
Name
role
Type
object
Description
The role that will be assigned on acceptance, with id and name.
Name
invitedBy
Type
object
Description
Who sent the invite. Contains type ("member" or "service_account") and either email (for members) or name (for service accounts). null if the sender has since been removed.
Name
createdAt
Type
timestamp
Description
Timestamp of when the invite was created.
Name
expiresAt
Type
timestamp
Description
Timestamp of when the invite expires. Invites are valid for 14 days.
Name
valid
Type
boolean
Description
Whether the invite is still valid (has not been cancelled or accepted).

GET/v1/invites

List Invites

Retrieve all pending (valid, non-expired) invites for the organisation, ordered by most recent first.

Request

GET

/v1/invites

curl https://api.phase.dev/v1/invites/ \
  -H "Authorization: Bearer {token}"

Response

[
    {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "inviteeEmail": "bob@example.com",
        "role": {
            "id": "6aec9df5-cd75-4645-a9d0-8b6f6aff78d6",
            "name": "Developer"
        },
        "invitedBy": {
            "type": "member",
            "email": "alice@example.com"
        },
        "createdAt": "2024-06-02T10:00:00Z",
        "expiresAt": "2024-06-16T10:00:00Z",
        "valid": true
    },
    {
        "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "inviteeEmail": "carol@example.com",
        "role": {
            "id": "d3a2124c-9770-42d5-abf8-599b4a372e9d",
            "name": "Manager"
        },
        "invitedBy": {
            "type": "service_account",
            "name": "deploy-bot"
        },
        "createdAt": "2024-06-01T08:00:00Z",
        "expiresAt": "2024-06-15T08:00:00Z",
        "valid": true
    }
]

DELETE/v1/invites/:id

Cancel Invite

Cancel a pending invite. The invite is immediately invalidated and the invitee can no longer use the invite link to join the organisation.

URL parameters

Name
id
Type
string
Description
The unique identifier of the invite.

Request

DELETE

/v1/invites/:id

curl -X DELETE https://api.phase.dev/v1/invites/a1b2c3d4-e5f6-7890-abcd-ef1234567890/ \
  -H "Authorization: Bearer {token}"

Response

204 No Content