# Invite a team member

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

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

[info]
Inviting users as the `admin` role is not permitted via the API.
[/info]

[endpoint]
base_url = "https://betterstack.com"
path = "/api/v2/team-members"
method = "POST"

[[query_param]]
name = "team_name"
description = "Required if using a [global API token](https://betterstack.com/docs/uptime/api/getting-started-with-uptime-api/#get-a-global-api-token) to specify the team."
required = false
type = "string"

[[body_param]]
name = "email"
description = "The email address of the user to invite."
required = true
type = "string"

[[body_param]]
name = "role"
description = "The role to assign to the user. Allowed values: `responder`, `member`, `team_lead`, `billing_admin`. Defaults to `responder`."
required = false
type = "string"

[[header]]
name = "Authorization"
description = "Bearer `$TOKEN`"
required = true
type = "string"

[[header]]
name = "Content-Type"
description = "application/json"
required = true
type = "string"
[/endpoint]

[responses]
[[response]]
status = 201
description = '''An invitation was sent to the user.'''
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"
    }
  }
}'''

[[response]]
status = 200
description = '''The user is already a member of the team.'''
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"
    }
  }
}'''

[[response]]
status = 422
description = '''The request was invalid (e.g., invalid email or role, or quota limits reached).'''
body = '''{
  "errors": "Invalid role. Allowed roles: responder, member, team_lead, billing_admin"
}'''

[[response]]
status = 422
description = '''The provided email address is invalid.'''
body = '''{
  "errors": "Email is not a valid email address"
}'''

[[response]]
status = 422
description = '''The email field is missing or blank.'''
body = '''{
  "errors": "Email is required"
}'''

[[response]]
status = 422
description = '''Quota limits prevent inviting more members.'''
body = '''{
  "errors": "Cannot invite organization members due to quota limits."
}'''

[[response]]
status = 429
description = '''Too many invitations sent, rate limit exceeded.'''
body = '''{
  "errors": "Too many invitations sent. Please try again later."
}'''

[[response]]
status = 403
description = '''Inviting an admin is forbidden.'''
body = '''{
  "errors": "Inviting admins is not allowed via API. Allowed roles: responder, member, team_lead, billing_admin"
}'''
[/responses]

#### Example cURL

[code-tabs]
```shell
[label Invite team member]
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"
  }'
```
```shell
[label 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",
    "role": "team_lead"
  }'
```
[/code-tabs]