Invite a team member

Invites a new user to the team. If the user is already a member, it returns the existing member's details with a 200 OK status.

Inviting a user with the admin role is not permitted via the API.

POST https://betterstack.com/api/v2/team-members

Query parameters

team_name

string

Required if using a global API token to specify the team.

Headers

Authorization

required string

Bearer $TOKEN

Content-Type

required string

application/json

Body parameters

required string

The email address of the user to invite.

role

string

The role to assign to the user. Defaults to responder. Allowed values: responder, member, team_lead, billing_admin.

201

An invitation was sent to the user.

Response body

{
  "message": "Invitation sent",
  "data": {
    "id": "inv_202",
    "type": "team_member_invitation",
    "attributes": {
      "email": "new.user@example.com",
      "invited_at": "2023-10-29T14:00:00.000Z",
      "role": "member"
    }
  }
}

200

The user is already a member of the team.

Response body

{
  "message": "User is already a member of the team",
  "data": {
    "id": "101",
    "type": "team_member",
    "attributes": {
      "email": "alice@example.com",
      "first_name": "Alice",
      "last_name": "Smith",
      "created_at": "2023-10-26T10:00:00.000Z",
      "role": "admin"
    }
  }
}

422

The request was invalid (e.g., invalid email or role).

Response body

{
  "errors": "Invalid role. Allowed roles: responder, member, team_lead, billing_admin"
}

403

Inviting an admin is forbidden.

Response body

{
  "errors": "Inviting admins is not allowed via API. Allowed roles: responder, member, team_lead, billing_admin"
}

Example cURL

Invite with default role Invite with specific role

Copied!

curl --request POST \
  --url "https://betterstack.com/api/v2/team-members" \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "email": "new.user@example.com"
  }'

curl --request POST \
  --url "https://betterstack.com/api/v2/team-members" \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "email": "another.user@example.com",
    "role": "member"
  }'

Looking for the details of a specific parameter?

Explore [the list of all Team Members API parameters][docs-uptime-api-team-members-response-params].

Explore documentation

Invite a team member

Example cURL

Looking for the details of a specific parameter?

Please accept cookies