# Update team member role

Changes a team member's role. Reference the target role by its ID, which you can get from the [List roles API](https://betterstack.com/docs/uptime/api/roles/list/).

Authenticate with a [global API token](https://betterstack.com/docs/uptime/api/getting-started-with-uptime-api/#get-a-global-api-token) (pass `team_name` to choose the team) or an Uptime API token (already scoped to its team).

Organization-wide roles (`admin` and `billing_admin`) apply across every team in the organization, so assigning `billing_admin` updates the member in all of their teams. See [Manage roles
](https://betterstack.com/docs/uptime/team-management/manage-roles/) for what each role can access.

Assigning a role the member already has is a no-op that still returns `200` with the member, so this endpoint is safe to call repeatedly — for example from an automation that syncs roles on every on-call rotation change.

[info]
Changing a role **to** or **from** `admin` is not permitted via the API. Manage admins in [Settings → Team members](https://betterstack.com/settings/members).
[/info]

[endpoint]
base_url = "https://betterstack.com"
path = "/api/v2/team-members/{id}/change-role/{role_id}"
method = "POST"

[[path_param]]
name = "id"
description = "The ID of the team member, as returned by the [List](https://betterstack.com/docs/uptime/api/team-members/list/) or [Get](https://betterstack.com/docs/uptime/api/team-members/get/) team members API. Pending invitations cannot have their role changed this way — cancel and re-invite them instead."
required = true
type = "string"

[[path_param]]
name = "role_id"
description = "The ID of the role to assign, as returned by the [List roles API](https://betterstack.com/docs/uptime/api/roles/list/). Custom roles are supported. The response returns `role` as `custom` for a custom role."
required = true
type = "string"

[[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. Ignored for team-scoped Uptime API tokens."
required = false
type = "string"

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

[responses]
[[response]]
status = 200
description = '''The role was changed (or already matched). Returns the updated team member.'''
body = '''{
  "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": "team_lead",
      "role_id": 103,
      "mobile_app_platforms": []
    }
  }
}'''

[[response]]
status = 401
description = '''Authentication failed due to a missing or invalid token.'''
body = '''{
  "errors": "We could not authenticate your request. Please provide a valid Global API token or Uptime API token."
}'''

[[response]]
status = 403
description = '''The API token is read-only.'''
body = '''{
  "errors": "This API token is read-only and cannot be used for write operations."
}'''

[[response]]
status = 403
description = '''The target role is `admin`.'''
body = '''{
  "errors": "Assigning the admin role is not allowed via API."
}'''

[[response]]
status = 403
description = '''The team member currently has the `admin` role.'''
body = '''{
  "errors": "Changing an admin's role is not allowed via API."
}'''

[[response]]
status = 404
description = '''No role with the given ID exists in the organization.'''
body = '''{
  "errors": "Resource type role with id = 999 was not found"
}'''

[[response]]
status = 404
description = '''The team member with the specified ID was not found in the team.'''
body = '''{
  "errors": "Resource type user with id = 999 was not found"
}'''

[[response]]
status = 409
description = '''Another role change for this user is already in progress.'''
body = '''{
  "errors": "Another role change for this user is in progress. Please try again."
}'''
[/responses]

#### Example cURL

```shell
[label Change role]
curl --request POST \
  --url "https://betterstack.com/api/v2/team-members/101/change-role/103" \
  --header "Authorization: Bearer $TOKEN"
```