**Source URL:** https://limited.veevavault.dev/safety/vault-api/api-reference/21.3/document-roles/assign-users-groups-to-roles-on-multiple-documents.md

# Assign Users & Groups to Roles on Multiple Documents



Assign users and groups to roles on a document or binder in bulk.

* The maximum CSV input file size is 1GB.

* The values in the input must be UTF-8 encoded.

* CSVs must follow the standard RFC 4180 format, with some [exceptions](/vault-api/references/csv-rfc-deviations).

* The maximum batch size is 1000.

<Endpoint path="/api/{version}/objects/documents/roles/batch" method="POST"></Endpoint>
Assigning users and groups to document roles is additive. For example, if groups 1, 2, and 3 are currently assigned to a particular role and you assign groups 3, 4, and 5 to the same role, the final list of groups assigned to the role will be 1, 2, 3, 4, and 5. Users and groups (IDs) in the input that are either invalid (not recognized) or cannot be assigned to a role due to permissions are ignored and not processed.

## Headers {#headers}

<FieldTable>
| Name | Description |
| --- | --- |
| `Content-Type` | `text/csv` or `application/x-www-form-urlencoded` |
| `Accept` | `application/json` (default) or `application/xml` |
</FieldTable>

## Body Parameters {#body-parameters}

You can add parameters in the request body, or upload them as a CSV file.

<FieldTable>
| Name | Description |
| --- | --- |
| `id` | The document ID. |
| `role__v.users` | A string of user `id` values for the new role. |
| `role__v.groups` | A string of user `id` values for the new group. |
</FieldTable>
For example,

<FieldTable>
| `id` | `reviewer__v.users` | `reviewer__v.groups` | `approver__v.users` | `approver__v.groups` |
| --- | --- | --- | --- | --- |
| 771 | "12021,12022" | "3311303,3311404" | 22124 | 4411606 |
</FieldTable>

## Request {#request}

<CodeExample title="">
```
curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \
--data-binary @"C:\Vault\Document Roles\assign_document_roles.csv" \
https://myvault.veevavault.com/api/v9.0/objects/documents/roles/batch

```
</CodeExample>

## Response {#response}

<CodeExample title="">
```
{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "id": 771,
            "reviewer__v.groups": [
                3311303,
                4411606
            ],
            "reviewer__v.users": [
                12021,
                12022,
                12023,
                12124
            ]
        },
        {
            "responseStatus": "SUCCESS",
            "id": 772,
            "reviewer__v.groups": [
                3311303,
                4411606
            ],
            "reviewer__v.users": [
                12021,
                12022,
                12023,
                12124
            ]
        },
        {
           "responseStatus":"FAILURE",
           "id":"773",
           "errors":[
              {
                 "type":"INVALID_DATA",
                 "message":"Error message describing why the users and groups were not assigned to roles on this document.."
              }
           ]
        }
    ]
}

```
</CodeExample>

## Response Details {#response-details}

The response includes `role:id` pairs for the users and groups successfully assigned to roles.



---

**Previous:** [Assign Users & Groups to Roles on a Single Document](/safety/vault-api/api-reference/21.3/document-roles/assign-users-groups-to-roles-on-a-single-document)  
**Next:** [Remove Users & Groups from Roles on a Single Document](/safety/vault-api/api-reference/21.3/document-roles/remove-users-groups-from-roles-on-a-single-document)