Bulk Document Relationships

The Bulk Document Relationships API allows you to create and delete relationships on multiple documents.

Bulk Document Relationships API Method API Endpoint Input Output Batch Size Available in API
Create Document Relationships POST /api/{version}/objects/documents/relationships/batch CSV, JSON CSV, JSON 1-1000 v15.0 or later
Delete Document Relationships DELETE /api/{version}/objects/documents/relationships/batch CSV, JSON CSV, JSON 1-1000 v15.0 or later

About Document Relationships

Document relationships create a connection between two documents. For example, you could create relationships on a promotional piece to connect documents like drug study results. In that example, the relationship type might be called "Supporting Documents" (supporting_documents__vs). Vault includes standard relationship types, but does not currently support custom relationship types. Learn about Document Relationships in Vault Help.

Vault's API Reference includes endpoints to Retrieve Document Relationships.

Create Document Relationships

Request

Send POST to /api/{version}/objects/documents/relationships/batch

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\Document Relationships\document_relationships.csv" \
https://myvault.veevavault.com/api/v15.0/objects/documents/relationships/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 v15.0 (earliest available for this request).

Response (CSV)

responseStatus,id,errors
SUCCESS,10,
SUCCESS,11,
FAILURE,,"""INVALID_DATA|Error message describing why this relationship was not created."""

Response (JSON)

Success
{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "id": 10
        },
        {
            "responseStatus": "SUCCESS",
            "id": 11
        },       
    ]
}
Failure
{
    "responseStatus": "FAILURE",
    "errors": [
        { "type": "INVALID_DATA", "message": "Cannot process batch : Duplicate rule: relationship already exists" }
    ]
}

After submitting the input, the Vault response will list the id value of each relationship.
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 v15

Top

Delete Document Relationships

Request

Send a DELETE request to the /api/{version}/objects/documents/relationships/batch 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 DELETE -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \ 
--data-binary @"C:\Vault\Document Relationships\document_relationships.csv" \
https://myvault.veevavault.com/api/v15.0/objects/documents/relationships/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 v15.0 (earliest available for this request).

Response (CSV)

responseStatus,id,errors
SUCCESS,10,
SUCCESS,11,
FAILURE,,"""INVALID_DATA|Error message describing why this relationship was not deleted."""

Response (JSON)

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "id": 10
        },
        {
            "responseStatus": "SUCCESS",
            "id": 11
        },       
        {
            "responseStatus": "FAILURE"
            "errors": [
                {
                    "type": "INVALID_DATA",
                    "message": "Error message describing why this relationship was not deleted."
                }
            ]
        }
    ]
}

After submitting the input, the Vault response will list the id value of each deleted relationship.
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 v15

Top