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 format.
The maximum batch size is 1000.

POST/api/{version}/objects/documents/roles/batch

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

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

Body Parameters

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

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.

For example,

`id`	`reviewer__v.users`	`reviewer__v.groups`	`approver__v.users`	`approver__v.groups`
771	"12021,12022"	"3311303,3311404"	22124	4411606

Request

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/v17.1/objects/documents/roles/batch

Response

{
    "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.."
              }
           ]
        }
    ]
}

Response Details

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