Invite a team member

Invites a new user to your organization. Invites existing team members to more teams.

Assign a role by name with role, or by ID with role_id — role_id also supports custom roles (get IDs from the List roles API).

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

Inviting users as the admin role is not permitted via the API, whether by role or role_id. Inviting a billing_admin requires a global API token, because Billing admin applies to every team in your organization.

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 e-mail address of the user to invite.

role

string

The role to assign to the user. Allowed values: responder, member, team_lead, billing_admin. Defaults to responder. Use role_id to assign a custom role. Assigning billing_admin requires a global API token.

role_id

string

The ID of the role to assign, including custom roles, as returned by the List roles API. Provide either role or role_id. If both are given they must reference the same role.

201

An invitation was sent to the user.

Response body

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

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",
      "role_id": 101,
      "mobile_app_platforms": []
    }
  }
}

401

Authentication failed due to a missing or invalid token.

Response body

{
  "errors": "We could not authenticate your request. Please provide a valid Global API token or Uptime API token."
}

403

Inviting an admin is forbidden.

Response body

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

422

The provided e-mail address is invalid.

Response body

{
  "errors": "Email is not a valid email address"
}

429

Too many invitations sent, rate limit exceeded.

Response body

{
  "errors": "Too many invitations sent. Please try again later."
}

Example cURL

Invite team member Invite as team lead Invite into a custom role by ID

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": "new.user@example.com",
    "role": "team_lead"
  }'

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",
    "role_id": 206
  }'

Get a single team member

Update team member role

Explore documentation

Invite a team member

Example cURL

Please accept cookies