Bulk Document Roles

The Bulk Document Roles API allows you to edit users and groups assigned to roles on documents.

Bulk Document Roles API Method API Endpoint Input Output Batch Size Available in API
Assign Users & Groups to Document Roles POST /api/{version}/objects/documents/roles/batch CSV, Name-Value Pair CSV, JSON 1-1000 v9.0 or later
Remove Users & Groups from Document Roles DELETE /api/{version}/objects/documents/roles/batch CSV, Name-Value Pair CSV, JSON 1-1000 v9.0 or later

Assign Users and Groups to Document Roles

Request

Send a POST request to the /api/{version}/objects/documents/roles/batch endpoint.

Inputs

Prepare a CSV input file. Learn more.
Or, prepare a Name-Value Pair input. Learn more.

Headers

To specify the input format, set the HTTP Request Header Content-Type to text/csv (CSV input) or application/x-www-form-urlencoded (Name-Value Pair input).
JSON is the default response format. To request a CSV response, set the HTTP Request Header Accept to text/csv.

Example 1

$ 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

In this example:

  • The input file format is set to CSV.
  • The response format is set to CSV.
  • The path/name of the CSV input file is specified.
  • The API {version} is set to v9.0 (earliest available for this request).

Example 2

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "docIds=771,772,773" \
-d "reviewer__v.groups=3311303,4411606" \
-d "reviewer__v.users=12021,12022,12023,22124" \ 
https://myvault.veevavault.com/api/v12.0/objects/documents/roles/batch

In this example:

  • The input format is set for name-value pairs.
  • The response format is not set and will default to JSON.
  • The docIds name-value pair key includes three document id values.
  • The reviewer__v.groups name-value pair key includes two group id values.
  • The reviewer__v.users name-value pair key includes four user id values.
  • The API {version} is set to v9.0 (earliest available for this request).

Response (CSV)

responseStatus,id,errors,reviewer__v.groups,reviewer__v.users
SUCCESS,"771",,"3311303,4411606","12021,12022,12023,22124"
SUCCESS,"772",,"3311303,4411606","12021,12022,12023,22124"
FAILURE,,"""INVALID_DATA|Error message describing why the users and groups were not assigned to roles on this document.""",,,

Response (JSON)

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

The order in which results are displayed in the response is the same as the order of records in the input.

Errors

Error Type Error Message Description
METHOD_NOT_SUPPORTED Message: "Requested method {METHOD} not supported". You must use the HTTP POST Method.
INSUFFICIENT_ACCESS Message: "User does not have sufficient privileges to perform the action". You must be assigned privileges in Vault to perform bulk API actions.
INVALID_DATA Message: "Cannot parse request body". The input contains information which cannot be parsed by the API. Check your input format.
INVALID_DATA Message: "Cannot process the request : max 1000 records expected". The input has more than 1000 records (not allowed).
INVALID_DATA Message: "Cannot parse the request body : at least 1 record is expected". The input has no records (at least one is required).

History

Since v9

Top

Remove Users and Groups from Document Roles

Request

Send a DELETE request to the /api/{version}/objects/documents/roles/batch endpoint.

Inputs

Prepare a CSV input file. Learn more.
Or, prepare a Name-Value Pair input. Learn more.

Headers

To specify the input file format, set the HTTP Request Header Content-Type to text/csv (CSV input) or application/x-www-form-urlencoded (Name-Value Pair input).
JSON is the default response format. To request a CSV response, set the HTTP Request Header Accept to text/csv.

Example 1

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \ 
--data-binary @"C:\Vault\Document Roles\remove_document_roles.csv" \
https://myvault.veevavault.com/api/v9.0/objects/documents/roles/batch

In this example:

  • The input file format is set to CSV.
  • The response format is set to CSV.
  • The path/name of the CSV input file is specified.
  • The API {version} is set to v9.0 (earliest available for this request).

Example 2

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "docIds=771,772,773" \
-d "reviewer__v.groups=4411606" \
-d "reviewer__v.users=22124" \ 
https://myvault.veevavault.com/api/v12.0/objects/documents/roles/batch

In this example:

  • The input format is set for name-value pairs.
  • The response format is not set and will default to JSON.
  • The docIds name-value pair key includes three document id values.
  • The reviewer__v.groups name-value pair key includes one group id value.
  • The reviewer__v.users name-value pair key includes one user id values.
  • The API {version} is set to v9.0 (earliest available for this request).

Response (CSV)

responseStatus,id,errors,reviewer__v.groups,reviewer__v.users
SUCCESS,"771",,4411606,22124
SUCCESS,"772",,4411606,22124
FAILURE,,"""INVALID_DATA|Error message describing why the users and groups were not removed from roles on this document.""",,

Response (JSON)

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "id": 771,
            "reviewer__v.groups": [
                4411606
            ],
            "reviewer__v.users": [
                12124
            ]           
        },
        {
            "responseStatus": "SUCCESS",
            "id": 772,
            "reviewer__v.groups": [
                4411606
            ],
            "reviewer__v.users": [
                12124
            ]           
        },        
        {
           "responseStatus":"FAILURE",
           "id":"773",
           "errors":[
              {
                 "type":"INVALID_DATA",
                 "message":"Error message describing why the users and groups were not removed from roles on this document."
              }
           ]
        }
    ]
}

The order in which results are displayed in the response is the same as the order of records in the input.

Errors

Error Type Error Message Description
METHOD_NOT_SUPPORTED Message: "Requested method {METHOD} not supported". You must use the HTTP DELETE Method.
INSUFFICIENT_ACCESS Message: "User does not have sufficient privileges to perform the action". You must be assigned privileges in Vault to perform bulk API actions.
INVALID_DATA Message: "Cannot parse request body". The input contains information which cannot be parsed by the API. Check your input format.
INVALID_DATA Message: "Cannot process the request : max 1000 records expected". The input has more than 1000 records (not allowed).
INVALID_DATA Message: "Cannot parse the request body : at least 1 record is expected". The input has no records (at least one is required).

History

Since v9

Top