Bulk Object Records

The Bulk Object Records API allows you to create and update multiple object records.

Bulk Object Records API Method API Endpoint Input Output Batch Size Available in API
Create Object Records POST /api/{version}/vobjects/{object_name} CSV, JSON CSV, JSON 1-500 v8.0 or later
Update Object Records PUT /api/{version}/vobjects/{object_name} CSV, JSON CSV, JSON 1-500 v8.0 or later
Delete Object Records DELETE /api/{version}/vobjects/{object_name} CSV, JSON CSV, JSON 1-500 v14.0 or later

Create Object Records

Request

Send a POST request to the /api/{version}/vobjects/{object_name} 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 POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \ 
--data-binary @"C:\Vault\Object Records\create_object_records.csv" \
https://myvault.veevavault.com/api/v8.0/vobjects/product__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 Vault object (object_name) is set to product__v.
  • The API {version} is set to v8.0 (earliest available for this request).

Response (CSV)

responseStatus,id,url,errors
SUCCESS,0PR0771,api/v8.0/vobjects/product__v/0PR0771,
SUCCESS,0PR0772,api/v8.0/vobjects/product__v/0PR0772,
SUCCESS,0PR0773,api/v8.0/vobjects/product__v/0PR0773,
FAILURE,,,"""INVALID_DATA|Error message describing why this object record was not created."""

Response (JSON)

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS"
            "data": {
                "id": "0PR0771",
                "url": "api/v8.0/vobjects/product__v/0PR0771"
            }
        },
        {
            "responseStatus": "SUCCESS"
            "data": {
                "id": "0PR0772",
                "url": "api/v8.0/vobjects/product__v/0PR0772"
            }
        },
        {
            "responseStatus": "SUCCESS"
            "data": {
                "id": "0PR0773",
                "url": "api/v8.0/vobjects/product__v/0PR0773"
            }
        },        
        {
            "responseStatus": "FAILURE"
            "errors": [
                {
                    "type": "INVALID_DATA",
                    "message": "Error message describing why this object record was not created."
                }
            ]
        }
    ]
}

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 must be assigned the appropriate privileges.
METHOD_NOT_SUPPORTED Requested method [{METHOD}] not supported. When creating object records in bulk, you must use the HTTP POST method.
INVALID_DATA Invalid request body content : at least [1] record is expected. The batch input is blank. The input must contain at least one object record.
INVALID_DATA Cannot process the request : max 500 records expected. More than 500 object records are included in the input.
INVALID_DATA Cannot parse the request body. The batch input cannot be parsed. Check the input format and the HTTP Request Header Content-Type setting.
INVALID_DATA Invalid value [{FIELD_VALUE}] specified for parameter [{FIELD_NAME}]. One of the field values entered does not exist. Verify the available field values for the object. The error message includes the field name and invalid value.
PARAMETER_REQUIRED Missing required parameter [{FIELD_NAME}]. A required field is missing from the input. The error message includes the missing field name.
OPERATION_NOT_ALLOWED Another resource already exists with the name entered. A name in input is already assigned to another object record in Vault.

History

Since v8

Top

Update Object Records

Request

Send a PUT request to the /api/{version}/vobjects/{object_name} 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\Object Records\update_object_records.csv" \
https://myvault.veevavault.com/api/v8.0/vobjects/product__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 Vault object (object_name) is set to product__v.
  • The API {version} is set to v8.0 (earliest available for this request).

Response (CSV)

responseStatus,errors
SUCCESS,
SUCCESS,
FAILURE,"""INVALID_DATA|Error message describing why this object record was not updated."""

Response (JSON)

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS"
        },
        {
            "responseStatus": "SUCCESS"
        },        
        {
            "responseStatus": "FAILURE"
            "errors": [
                {
                    "type": "INVALID_DATA",
                    "message": "Error message describing why this object record was not updated."
                }
            ]
        }
    ]
}

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
METHOD_NOT_SUPPORTED The requested method [{METHOD}] is not supported. You must use a PUT method for this request and set the correct parameters.
INVALID_DATA Invalid value [{FIELD_VALUE}] specified for parameter [{OBJECT_FIELD}]. One of the field values entered does not exist. Verify the available field values for the object.
MALFORMED_URL The resource {ID} does not exist. Verify that the object record id is correct.

History

Since v8

Top

Delete Object Records

Delete object records in bulk. Admins can also define special deletion rules for objects, which affects how Vault behaves when you attempt to delete an object record. Learn more about limitations on object record deletion in Vault Help. If you need to delete a parent record along with all of its children and granchildren, use the Cascade Delete endpoint.

Request

Send a DELETE request to the /api/{version}/vobjects/{object_name} 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

idParam - If using external_id__v field values instead of id to identify object records in your input, add ?idParam=external_id__v to the request endpoint.

Example 1

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \ 
--data-binary @"C:\Vault\Object Records\delete_object_records.csv" \
https://myvault.veevavault.com/api/v14.0/vobjects/product__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 API {version} is set to v14.0 (earliest available for this request).
  • The Vault object (object_name) is set to product__v.

Example 2

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/json" \
--data-binary @"C:\Vault\Object Records\delete_object_records.json" \
https://myvault.veevavault.com/api/v14.0/vobjects/product__v?idParam=external_id__v

In this example:

  • The input file format is set to JSON.
  • The response format is not set and will default to JSON.
  • The path\name of the JSON input file is specified.
  • The API {version} is set to v14.0 (earliest available for this request).
  • The Vault object (object_name) is set to product__v.
  • The idParam is set to external_id__v. This tells Vault to look for external IDs instead of IDs.

Response (CSV)

responseStatus,errors
SUCCESS,
SUCCESS,
FAILURE,"""INVALID_DATA|Error message describing why this object record was not deleted."""

Response (JSON)

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS"
        },
        {
            "responseStatus": "SUCCESS"
        },        
        {
            "responseStatus": "FAILURE"
            "errors": [
                {
                    "type": "INVALID_DATA",
                    "message": "Error message describing why this object record was not deleted."
                }
            ]
        }
    ]
}

Errors

Error Type Error Message Comments
METHOD_NOT_SUPPORTED The requested method [{METHOD}] is not supported. Use the HTTP method DELETE.
INSUFFICIENT_ACCESS User does not have sufficient privileges to perform the action. The logged-in user must be assigned the appropriate privileges.
INVALID_DATA Invalid value [{FIELD_VALUE}] specified for parameter [{OBJECT_FIELD}]. One of the field values entered does not exist. Verify the available field values for the object.
INVALID_DATA Invalid request body content : at least [1] record is expected. The batch input is blank. The input must contain at least one object record.
INVALID_DATA Cannot process the request : max 500 records expected. More than 500 object records are included in the input.
INVALID_DATA Cannot parse the request body. The batch input cannot be parsed. Check the input format and the HTTP Request Header Content-Type setting.
INVALID_DATA Record not found. One or more of the object record IDs specified in the input could not be found in your vault.
INVALID_DATA External identifier not found. One or more of the object record external IDs specified in the input could not be found in your vault.
OPERATION_NOT_ALLOWED Object record cannot be deleted due to an external reference. You are trying to delete a parent object record with active child object records (not allowed).

History

Since v14

Top