---
title: "Add users to a role"
method: POST
path: "/structures/v1/roles/{role_id}/members"
tags: ["Structures"]
---

# Add users to a role

`POST /structures/v1/roles/{role_id}/members`

## Request

- Base URL: `https://api.mitti.com`
- URL: `https://api.mitti.com/structures/v1/roles/{role_id}/members`
- Auth: HTTP bearer

Assigns up to 100 users to a role, each against its own set of structures. This endpoint supports partial success: the memberships that were created are returned in `structure_memberships`, and any assignment that failed is reported in `errors` with a status code and a reason. A response with a populated `errors` array is still a 200.

## Path parameters

- `role_id` string, required

## Request body

- S12StructuresMembershipV1StructureMembershipServiceAddUsersToRoleBody: Request message to add users to a role. Each entry assigns one user to the role on its own set of structures.
  - `user_structure_pairs` S12StructuresMembershipV1UserStructurePairs[], required: The user-to-structures assignments to apply for the role. Limited to 100 entries per request.
    - `user_id` string, required: The unique identifier of the user to assign.
    - `structure_ids` string[], required: The unique identifiers of the structures to assign the role on for this user. Limited to 10 structures per entry.

## Response `200`

A successful response.

- S12StructuresMembershipV1AddUsersToRoleResponse: Response message for adding users to a role. Supports partial success: the memberships that were created are returned alongside per (user, structure) failures.
  - `structure_memberships` S12StructuresMembershipV1StructureMembership[]: The structure memberships that were successfully created.
    - `user_id` string: The unique identifier of the user.
    - `structure_id` string: The unique identifier of the structure.
    - `role_id` string: The unique identifier of the role assigned to the user within the structure.
    - `created_at` string, date-time: The timestamp when the user was added to the structure.
    - `modified_at` string, date-time: The timestamp when the membership was last modified.
    - `assignment_type` 'ASSIGNMENT_TYPE_UNSPECIFIED' | 'ASSIGNMENT_TYPE_MANUAL' | 'ASSIGNMENT_TYPE_RULE_BASED': AssignmentType classifies how this membership was assigned: explicitly by a user, or computed by a dynamic-structure rule. - ASSIGNMENT_TYPE_UNSPECIFIED: Unspecified assignment type value. - ASSIGNMENT_TYPE_MANUAL: The membership was explicitly assigned by a user. - ASSIGNMENT_TYPE_RULE_BASED: The membership was computed by a dynamic-structure rule.
  - `errors` S12StructuresMembershipV1AddUsersToRoleError[]: The (user, structure) assignments that failed, each with a reason. Empty when every assignment succeeded.
    - `user_id` string: The unique identifier of the user that could not be assigned.
    - `structure_id` string: The unique identifier of the structure the assignment targeted.
    - `code` integer: The gRPC status code (google.rpc.Code) describing the failure.
    - `message` string: A human-readable, actionable description of why the assignment failed.
    - `user_name` string: The display name of the user that could not be assigned, for surfacing the failure in the UI without a separate lookup. Best-effort: may be empty if the name could not be resolved.

## Other responses

- `default`: An unexpected error response.

## Changes

- **2026-11-03** `eb6bb843bf18`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/safetyculture/apis/safetyculture-api/changes/structures/v1/roles/:role_id/members/post.md)

---

[API](https://skmtc.dev/safetyculture/apis/safetyculture-api.md) - [All operations](https://skmtc.dev/safetyculture/apis/safetyculture-api/llms.txt) - [OpenAPI document](https://skmtc.dev/safetyculture/apis/safetyculture-api/revisions/eb6bb843bf18?raw)
