Bulk Users

The Bulk Users API allows you to create and update multiple users.

Bulk Users API Method API Endpoint Input Output Batch Size Available in API
Create Users POST /api/{version}/objects/users CSV, JSON CSV, JSON 1-500 v12.0 or later
Update Users PUT /api/{version}/objects/users CSV, JSON CSV, JSON 1-500 v12.0 or later
Upsert Users POST /api/{version}/objects/users CSV, JSON CSV, JSON 1-500 v12.0 or later

Create Users

Request

Send a POST request to the /api/{version}/objects/users endpoint.

Inputs

Prepare a CSV input file. Learn more.
Or, prepare a JSON input file. Learn more.

To create cross-domain users, you need to include vault_membership.

Headers

To specify the input file format, set the HTTP Request Header Content-Type to text/csv (CSV input) or application/json (JSON input).
JSON is the default response format. To request a CSV response, set the HTTP Request Header Accept to text/csv.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \ 
--data-binary @"C:\Vault\Users\create_users.csv" \
https://myvault.veevavault.com/api/v12.0/objects/users

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 v12.0 (earliest available for this request).

Response (CSV)

responseStatus,id,errors
SUCCESS,12021,
SUCCESS,12022,
SUCCESS,12023,
FAILURE,,"""INVALID_DATA|Error message describing why this user was not created."""

Response (JSON)

{
   "responseStatus":"SUCCESS",
   "data":[
      {
         "responseStatus":"SUCCESS",
         "id":"12021"
      },
      {
         "responseStatus":"SUCCESS",
         "id":"12022"
      },
      {
         "responseStatus":"SUCCESS",
         "id":"12023"
      },      
      {
         "responseStatus":"FAILURE",
         "errors":[
            {
               "type":"INVALID_DATA",
               "message":"Error message describing why this user was not created."
            }
         ]
      }
   ]
}

After submitting the input, the Vault response will list the id value of each user.
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 Comments
INSUFFICIENT_ACCESS User does not have sufficient privileges to perform the action. The logged-in API user has not been assigned permission to complete this request.
INVALID_DATA Invalid request body content : at least [1] record is expected. The CSV or JSON input must include at least one user.
INVALID_DATA Cannot process the request : max 500 records expected. More than 500 users are included in the input (not allowed).
INVALID_DATA Cannot parse the request body. Check your CSV or JSON input format and the HTTP Request Header Content-Type setting.

History

Since v12

Top

Update Existing Users

Request

Send a PUT request to the /api/{version}/objects/users endpoint.

Inputs

Prepare a CSV input file. Learn more.
Or, prepare a JSON input file. Learn more.

Headers

To specify the input file format, set the HTTP Request Header Content-Type to text/csv (CSV input) or application/json (JSON input).
JSON is the default response format. To request a CSV response, set the HTTP Request Header Accept to text/csv.

Example

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \ 
--data-binary @"C:\Vault\Users\update_users.csv" \
https://myvault.veevavault.com/api/v12.0/objects/users

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 v12.0 (earliest available for this request).

Response (CSV)

responseStatus,id,errors
SUCCESS,12021,
SUCCESS,12022,
SUCCESS,12023,
FAILURE,22124,"""INVALID_DATA|Error message describing why this user was not updated."""

Response (JSON)

{
   "responseStatus":"SUCCESS",
   "data":[
      {
         "responseStatus":"SUCCESS",
         "id":"12021"
      },
      {
         "responseStatus":"SUCCESS",
         "id":"12022"
      },
      {
         "responseStatus":"SUCCESS",
         "id":"12023"
      },      
      {
         "responseStatus":"FAILURE",
         "id":"22124"
         "errors":[
            {
               "type":"INVALID_DATA",
               "message":"Error message describing why this user was not updated."
            }
         ]
      }
   ]
}

After submitting the input, the Vault response will list the id value of each user.
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 Comments
INSUFFICIENT_ACCESS User does not have sufficient privileges to perform the action. The logged-in user has not been assigned privileges to update users.
INVALID_DATA Invalid request body content : at least [1] record is expected. The batch input is blank. The CSV or JSON input must contain at least one user row/record.
INVALID_DATA Cannot process the request : max 500 records expected. More than 500 user rows/records are included in the CSV or JSON input.
INVALID_DATA Cannot parse the request body. The batch input cannot be parsed. Check your CSV or JSON input format and the HTTP Request Header Content-Type setting.
INVALID_DATA User [{ID}] not found. The Vault User ID specified in the CSV or JSON input does not match any existing users. The error message includes the id of the unknown user.
PARAMETER_REQUIRED Missing identifier parameter [id]. The Vault User ID field name is a required parameter in the CSV or JSON input.
INVALID_DATA Identifier parameter [id] must contain a value. The Vault User ID field value is required in the CSV or JSON input.
INVALID_DATA The input already defines another user with [id={id}]. If the CSV or JSON input contains more than one user record containing the same user id, the first user record is processed but all subsequent (duplicate) records are not and return this error.

History

Since v12

Top

Upsert New & Existing Users

Upsert is a combination of create and update. Use one input file to create new users and update existing users at the same time.

Request

Send a POST request to the /api/{version}/objects/users endpoint.

Inputs

Prepare a CSV input file. Learn more.
Or, prepare a JSON input file. Learn more.

Headers

To specify the input file format, set the HTTP Request Header Content-Type to text/csv (CSV input) or application/json (JSON input).
JSON is the default response format. To request a CSV response, set the HTTP Request Header Accept to text/csv.

Parameters

operation - You must include the operation=upsert parameter to the request endpoint.
idParam - You must include either the idParam=id or idParam=user_name__v to the request endpoint.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \ 
--data-binary @"C:\Vault\Users\upsert_users.csv" \
https://myvault.veevavault.com/api/v12.0/objects/users?operation=upsert&idParam=user_name__v

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 operation request parameter is set to upsert.
  • The idParam request parameter is set to user_name__v.
  • The API {version} is set to v12.0 (earliest available for this request).

Response (CSV)

responseStatus,id,errors
SUCCESS,22124,
SUCCESS,22125,
FAILURE,,"""INVALID_DATA|Error message describing why this user was not created."""
SUCCESS,12021,
SUCCESS,12022,
FAILURE,12023,"""INVALID_DATA|Error message describing why this user was not updated."""

Response (JSON)

{
   "responseStatus":"SUCCESS",
   "data":[
      {
         "responseStatus":"SUCCESS",
         "id":"22124"
      },
      {
         "responseStatus":"SUCCESS",
         "id":"22125"
      },
      {
         "responseStatus":"FAILURE",
         "errors":[
            {
               "type":"INVALID_DATA",
               "message":"Error message describing why this user was not created."
            }
         ]
      },      
      {
         "responseStatus":"SUCCESS",
         "id":"12021"
      },
      {
         "responseStatus":"SUCCESS",
         "id":"12022"
      },
      {
         "responseStatus":"FAILURE",
         "id":"12023",
         "errors":[
            {
               "type":"INVALID_DATA",
               "message":"Error message describing why this user was not updated."
            }
         ]
      }
   ]
}

After submitting the input, the Vault response will list the id value of each user.
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 Comments
INSUFFICIENT_ACCESS User does not have sufficient privileges to perform the action. The logged-in user has not been assigned privileges to update users.
INVALID_DATA Invalid request body content : at least [1] record is expected. The batch input is blank. The CSV or JSON input must contain at least one user row/record.
INVALID_DATA Cannot process the request : max 500 records expected. More than 500 user rows/records are included in the CSV or JSON input.
INVALID_DATA Cannot parse the request body. The batch input cannot be parsed. Check your CSV or JSON input format and the HTTP Request Header Content-Type setting.
INVALID_DATA Invalid value specified for parameter [idParam] : one of [id,user_name__v] is expected. The idParam request parameter is included but not set. You must set this to either id or user_name__v depending on how the users are being referenced in your CSV or JSON input.
INVALID_DATA Invalid value [{FIELD_VALUE}] specified for parameter [idParam] : one of [id,user_name__v] is expected. The idParam request parameter is included but not set to a valid value. You must set this to either id or user_name__v depending on how the users are being referenced in your CSV or JSON input.
PARAMETER_REQUIRED Missing identifier parameter [{id or user_name__v}]. The idParam request parameter is set to a valid value but the CSV input does not include this value. This error applies only to CSV input. Make sure your CSV file has a column for either id or user_name__v, whichever is set in the request parameter.
INVALID_DATA User [{ID}] not found. The Vault User ID specified in the CSV or JSON input does not match any existing users. The error message includes the id of the unknown user.
PARAMETER_REQUIRED Missing identifier parameter [id]. The Vault User ID field name is a required parameter in the CSV or JSON input.
INVALID_DATA Identifier parameter [id] must contain a value. When the idParam request parameter is not included in the request or is included and set to id, the Vault User ID field value is required in the CSV or JSON input for users being updated.
INVALID_DATA The input already defines another user with [id={id}]. If the CSV or JSON input contains more than one user record containing the same user id, the first user record is processed but all subsequent (duplicate) records are not and return this error. This error applies only when the idParam request parameter is set to id.
INVALID_DATA The input already defines another user with [user_name_v={user_name_v}]. If the CSV or JSON input contains more than one user record containing the same user user_name__v, the first user record is processed but all subsequent (duplicate) records are not and return this error. This error applies only when the idParam request parameter is set to user_name__v.
INVALID_DATA Cannot create user : source file [{file}] not found. When adding a picture to the user profile, the image file must first be uploaded to the FTP staging server. If the image file is specified in the CSV or JSON input and cannot be found, this error is returned.

History

Since v12

Top