Explore documentation
  1. Welcome to Uptime 👋
  2. Frequently Asked Questions
  3. On-call scheduling and alerting
    1. Get started
    2. Slack and other integrations ↗
    3. Connecting external calendars
    4. Advanced guide
  4. Incidents
    1. Get started
    2. Advanced guide
    3. Reporting ↗
  5. Monitoring
    1. Get started
    2. Working with monitors
    3. Customizing monitors
    4. Monitor types
  6. Status pages
    1. Get started
    2. Advanced guide
  7. Uptime API
    1. Getting an API token
    2. Monitors
    3. Heartbeats
    4. On-call & incidents
    5. Status pages
    6. Metadata
    7. Integrations
    8. Team members
      1. List all team members GET
      2. Get a single team member GET
      3. Invite a team member POST
      4. Remove a team member by ID DELETE
      5. Remove a team member by e-mail DELETE

Invite a team member

Invites a member of your organization or completely new team member to your 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

email
required string

The email 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.

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"
    }
  }
}
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, or quota limits reached).

Response body

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

The provided email address is invalid.

Response body

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

The email field is missing or blank.

Response body

{
  "errors": "Email is required"
}
422

Quota limits prevent inviting more members.

Response body

{
  "errors": "Cannot invite organization members due to quota limits."
}
429

Too many invitations sent, rate limit exceeded.

Response body

{
  "errors": "Too many invitations sent. Please try again later."
}
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 team member Invite as 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"
  }'
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"
  }'


Previous article

Get a single team member

Next article

Remove a team member from team by ID