Bulk Input Files

This article provides detailed information and examples for preparing inputs for all available Bulk API and Vault Loader actions. Learn about Vault Loader.

Available Bulk API & Vault Loader Actions Bulk API Vault Loader CSV Input JSON Input Name-Value Pair Input
Documents: Create Documents S S See input NS NS
Documents: Update Documents S S See input NS See input
Documents: Delete Documents S NS See input See input NS
Document Versions: Add Document Versions S S See input NS NS
Document Versions: Delete Document Versions S NS See input See input NS
Document Renditions: Add Document Renditions S S See input NS NS
Document Renditions: Delete Document Renditions S NS See input See input NS
Document Roles: Assign Users & Groups to Document Roles S S See input NS See input
Document Roles: Remove Users & Groups from Document Roles S S See input NS See input
Documents, Versions, & Roles (together in one input) NS S See input NS NS
Document Relationships: Create Document Relationships S NS See input See input NS
Document Relationships: Delete Document Relationships S NS See input See input NS
Object Records: Create Object Records S S See input See input NS
Object Records: Update Object Records S S See input See input NS
Object Records: Upsert Object Records NS S See input NS NS
Object Records: Delete Object Records S S See input See input NS
Users: Create Users S S See input See input NS
Users: Update Users S S See input See input NS
Users: Upsert Users S S See input See input NS
Groups: Create Groups NS S See input NS NS
Groups: Update Groups NS S See input NS NS
Groups: Upsert Groups NS S See input NS NS

| S = Supported | NS = Not Supported |

Input File Requirements

  • The maximum input file size is 1 GB.
  • The values in the input must be UTF-8 encoded.
  • The data format as specified in http://tools.ietf.org/html/rfc4180 is strictly enforced.
  • The number of records in the input cannot exceed the maximum number allowed for the request.
  • The input must include all required fields and values for the request.
  • When adding multiple values to a field, separate them in a comma-delimited string. Since the field value itself contains a comma, double quotes must surround string.
  • When editing multibyte characters with Microsoft Excel, do not use "Save As" to save the file as a CSV file in a different location or save it as a native Excel file. To move or rename the file, use your operating system.

Top

CSV: Create Documents

  • Supported in the Bulk API: YES (See request)
  • Supported in Vault Loader: YES (See request)
  • Other supported input formats: NO

Available Options

The API supports the following bulk create document actions:

  • Create Documents from Uploaded Files - See below.
  • Create Documents from Templates - See below.
  • Create Content Placeholder Documents - See below.
  • Create Unclassified Documents - See below.

Learn about adding documents to Vault.

Required Standard Fields

When creating new documents, the following standard fields are required in all vaults:

  • name__v - Name of the new document.
  • type__v - Name of the document type to assign to the new document.
  • subtype__v - Name of the document subtype (if one exists on the document type).
  • classification__v - Name of the document classification (if one exists on the document subtype).
  • lifecycle__v - Name of the document lifecycle to assign to the new document.
  • major_version_number__v - Major version number to assign to the new document.
  • minor_version_number__v - Minor version number to assign to the new document.

These do not apply to unclassified documents.

Additional Required & Editable Fields

Admin may set other standard or custom document fields to required in your vault.

  • Use the Document Metadata API to retrieve all fields configured on documents. In the field specifications: Required fields: required:true / Editable fields: editable:true.
  • Use Loader Document Extract to retrieve fields and values configured on specific documents.
  • Go to Admin > Configuration > Document Fields and find all fields marked "Required" and those which are editable. Learn more.

If a required field is not included in the input, Vault returns a PARAMETER_REQUIRED error with the name of the missing field. When this occurs, Vault does not process any records in the input.

You can include any editable document field and value in the input.

Referencing Vault Objects (Lookups)

When assigning objects to documents, you can use either of the following methods:

file name__v type__v subtype__v classification__v lifecycle__v major_version_number__v minor_version_number__v product__v country__v
doc1.doc Alterin Doc Claim Claim 0 1 0PR0101 0CT0555

Where 0PR0101 and 0CT0555 are the system-managed IDs of the product__v and country__v object records Alterin and United States, respectively.

Alternatively, you can use dot-notation with the object name and the name__v field to call out the object record names directly, as shown below.

file name__v type__v subtype__v classification__v lifecycle__v major_version_number__v minor_version_number__v product__v.name__v country__v.name__v
doc1.doc Alterin Doc Claim Claim 0 1 Alterin United States

Suppress Generation of Viewable Rendition

  • By default the viewable rendition is generated at the time the document is created.
  • To suppress generation of the viewable rendition, include the parameter suppressRendition in the input and set its values to true.

For example (abridged CSV input):

file name__v suppressRendition
docs/doc1.doc Alterin Doc true
docs/doc2.doc CholeCap Doc true

Top

Create Documents from Uploaded Files

Learn about supported file types.

Uploading Source Files

  • Before loading your input, you must upload the document source files to your vault's staging server. Learn more.
  • In your input, include the file field name and enter the path/name of each document source file.

Example Input

file name__v type__v subtype__v classification__v lifecycle__v major_version_number__v minor_version_number__v product__v.name__v external_id__v
docs/doc1.doc Alterin Doc Resource General Lifecycle 0 1 Alterin ALT-DOC-0771
docs/doc2.doc CholeCap Doc Promotional Piece Convention Item Promotional Piece 0 1 CholeCap CHO-DOC-0772
docs/doc3.doc Gludacta Doc Promotional Piece Advertisement Web Promotional Piece 0 1 Gludacta GLU-DOC-0773
docs/doc4.doc Nyaxa Doc Claim Claim 0 1 Nyaxa NYA-DOC-0774

This example includes:

  • The file field parameter and four document source files located in the "docs" directory of our vault's staging server.
  • All required fields to create new documents of the specified document types in our vault.
  • Optional (in our vault) product__v field. When associating documents with objects, use the object record id or dot-notation (shown above) to use the name__v value.
  • Optional (in our vault) external_id__v field. You can use document external ID field values for document update actions.

Download Input File

Top

Create Documents from Templates

  • When you create a new document from a template, Vault copies the template file in your vault and uses that copy as the source file for the new document.
  • To retrieve available document templates in your vault, use the Document Types API or go to Admin > Business Admin > Templates.
  • Learn about managing document templates.

Uploading Source Files

  • Not required.
  • In your input, include fromTemplate and enter the names of the document templates.

Example Input

fromTemplate name__v type__v subtype__v classification__v lifecycle__v major_version_number__v minor_version_number__v product__v.name__v external_id__v
resource_doc_template__c Alterin DOC Resource General Lifecycle 0 1 Alterin ALT-DOC-0771
promo_doc_template__c CholeCap Doc Promotional Piece Convention Item Promotional Piece 0 1 CholeCap CHO-DOC-0772
promo_doc_template__c Gludacta Doc Promotional Piece Advertisement Web Promotional Piece 0 1 Gludacta GLU-DOC-0773
claim_doc_template__c Nyaxa Doc Claim Claim 0 1 Nyaxa NYA-DOC-0774

This example includes:

  • The fromTemplate field parameter and four document templates in our vault.
  • All required fields to create new documents of the specified document types in our vault.
  • Optional (in our vault) product__v field. When associating documents with objects, use the object record id or dot-notation (shown above) to use the name__v value.
  • Optional (in our vault) external_id__v field. You can use document external ID field values for document update actions.

Download Input File

Top

Create Content Placeholder Documents

  • Vault allows you to create content placeholders when the associated file is not yet available and then, add the source document at a later date.
  • Learn about content placeholders.

Uploading Source Files

  • Not required.
  • In your input, include file but leave the values blank (empty-string).

Example Input

file name__v type__v subtype__v classification__v lifecycle__v major_version_number__v minor_version_number__v product__v external_id__v
Alterin Doc Resource General Lifecycle 0 1 0PR0101 ALT-DOC-0771
CholeCap Doc Promotional Piece Convention Item Promotional Piece 0 1 0PR0202 CHO-DOC-0772
Gludacta Doc Promotional Piece Advertisement Web Promotional Piece 0 1 0PR0303 GLU-DOC-0773
Nyaxa Doc Claim Claim 0 1 0PR0404 NYA-DOC-0774

This example includes:

  • The file field parameter with no files specified. This tells Vault to create the new documents as content placeholders.
  • All required fields to create new documents of the specified document types in our vault.
  • Optional (in our vault) product__v field. When associating documents with objects, use the object record id or dot-notation (shown in the previous example) to use the name__v value.
  • Optional (in our vault) external_id__v field. You can use document external ID field values for document update actions.

Download Input File

Top

Create Unclassified Documents

  • Unclassified documents are documents which have a source file, but no document type.
  • Bypassing the steps to classify the document and populate document properties allows you to upload source files and create documents more quickly.
  • Learn about unclassified documents.

Uploading Source Files

  • Before loading your input, you must upload the document source files to your vault's staging server. Learn more.
  • In your input, include the file field name and enter the path/name of each document source file.

Required Fields

When creating unclassified documents, the following fields are required in all vaults:

  • name__v - Name of the new unclassified document.
  • type__v - Use the document type "Undefined".
  • lifecycle__v - Use the document lifecycle "Unclassified".

You can include any editable document field and value in the input.

Example Input

file name__v type__v lifecycle__v product__v.name__v external_id__v
docs/doc1.doc Alterin Doc Undefined Unclassified Alterin ALT-DOC-0771
docs/doc2.doc CholeCap Doc Undefined Unclassified CholeCap CHO-DOC-0772
docs/doc3.doc Gludacta Doc Undefined Unclassified Gludacta GLU-DOC-0773
docs/doc4.doc Nyaxa Doc Undefined Unclassified Nyaxa NYA-DOC-0774

This example includes:

  • The file field parameter and four document source files located in the "docs" directory of our vault's staging server.
  • All required fields to create unclassified documents.
  • Optional (in our vault) product__v field. When associating documents with objects, use the object record id or dot-notation (shown above) to use the name__v value.
  • Optional (in our vault) external_id__v field. You can use document external ID field values for document update actions.

Download Input File

Top

CSV: Update Documents

Required Fields

  • When updating documents, the system-managed document id is the only required field in all vaults.
  • Vault matches document IDs in the input with existing documents in your vault.

Updating Fields

  • You can add and update values of any editable document field.
  • To clear existing field values, include the field name and set its value to null.
  • Field names and values not included in the input remain unchanged on the document.

To retrieve document information:

  • Use the Document Metadata API to retrieve all fields configured on documents. In the field specifications: Editable fields: editable:true.
  • Use Vault Loader Document Extract to retrieve fields and values configured on specific documents.
  • Go to Admin > Configuration > Document Fields and find all fields which are editable. Learn more.

Example Input

id product__v.name__v country__v.name__v language__v audience__vs
771 Alterin United States English Consumer
772 CholeCap France French Healthcare Provider
773 Gludacta Japan Japanese Managed Markets
774 Nyaxa China Chinese (Traditional) Public Affairs

This example includes:

  • The document id field name and the system-managed values of each document being updated.
  • The editable product__v and country__v document field. When associating documents with objects, use the object record id or dot-notation (shown above) to use the name__v value.
  • The editable language__v and audience__vs document field and values.

Download Input File

Top

CSV: Delete Documents

  • Supported in the Bulk API: YES (See request)
  • Supported in Vault Loader: NO
  • Other supported input formats: JSON (See input)

Referencing Existing Documents

When deleting documents, you can use one of two standard document ID fields in the input:

  • id - System-assigned document ID. This numeric field value exists on all documents. It is non-editable.
  • external_id__v - User-defined document external ID. This alphanumeric field is not always configured with values. It is editable.

By default, Vault looks for the id field in the input. To use external_id__v instead, add the idParam=external_id__v parameter to the request endpoint..

Example Inputs

Using the document id field:

id
771
772
773
774

Using the document external_id__v field:

external_id__v
ALT-DOC-0771
CHO-DOC-0772
GLU-DOC-0773
NYA-DOC-0774

Top

CSV: Add Document Versions

  • Supported in the Bulk API: YES (See request)
  • Supported in Vault Loader: YES (See request)
  • Other supported input formats: NO

Uploading Source Files

  • Before loading your input, you must upload the document source files to your vault's staging server. Learn more.
  • In your input, include the file field name and enter the path/name of each source file.

Referencing Existing Documents

When using the Bulk API to add versions, you can use one of two standard document ID fields in the input:

  • id - System-assigned document ID. This numeric field value exists on all documents. It is non-editable.
  • external_id__v - User-defined document external ID. This alphanumeric field is not always configured with values. It is editable.

By default, Vault looks for the id field in the input. To use external_id__v instead, add the idParam=external_id__v parameter to the request endpoint.

Required Standard Fields

When adding document versions, the following standard fields are required in all vaults:

  • name__v - Enter a name for the new document. This may be the same name as the existing document/version or a different name.
  • type__v - Enter the name of the document type to assign to the new document.
  • subtype__v - Enter the name of the document subtype (if one exists on the document type).
  • classification__v - Enter the name of the document classification (if one exists on the document subtype).
  • lifecycle__v - Enter the name of the document lifecycle to assign to the new document. This may be the same lifecycle as the existing document/version or a different lifecycle.
  • major_version_number__v - Enter the major version number to assign to the new document version. This must be a version that does not yet exist on the document being updated.
  • minor_version_number__v - Enter the minor version number to assign to the new document. This must be a version that does not yet exist on the document being updated.
  • status__v - Enter a status for the new document, e.g., Draft, In Review, Approved, etc.

Referencing Vault Objects (Lookups)

When assigning objects to documents, you can use either of the following methods:

file id type__v subtype__v classification__v lifecycle__v major_version_number__v minor_version_number__v product__v country__v status__v
doc1.doc 771 Claim Claim 0 1 0PR0101 0CT0555 Draft

Where 0PR0101 and 0CT0555 are the system-managed IDs of the product__v and country__v object records Alterin and United States, respectively.

Alternatively, you can use dot-notation with the object name and the name__v field to call out the object record names directly, as shown below.

file id type__v subtype__v classification__v lifecycle__v major_version_number__v minor_version_number__v product__v.name__v country__v.name__v status__v
doc1.doc 771 Claim Claim 0 1 Alterin United States Draft

Additional Requirements

Example Inputs

Using the document id field:

file id name__v type__v subtype__v classification__v lifecycle__v major_version_number__v minor_version_number__v status__v
docs/doc1-v2.doc 771 Alterin Doc Resource General Lifecycle 0 2 Draft
docs/doc2-v2.doc 772 CholeCap Doc Promotional Piece Convention Item Promotional Piece 0 2 In Review
docs/doc3-v1-0.doc 773 Gludacta Doc Promotional Piece Advertisement Web Promotional Piece 1 0 Approved

Using the document external_id__v field:

file external_id__v name__v type__v subtype__v classification__v lifecycle__v major_version_number__v minor_version_number__v status__v
docs/doc1-v2.doc ALT-DOC-0771 Alterin Doc Resource General Lifecycle 0 2 Draft
docs/doc2-v2.doc CHO-DOC-0772 CholeCap Doc Promotional Piece Convention Item Promotional Piece 0 2 In Review
docs/doc3-v1-0.doc GLU-DOC-0773 Gludacta Doc Promotional Piece Advertisement Web Promotional Piece 1 0 Approved

These examples include:

  • The file field parameter with three document version source files located in the "docs" directory of our vault's staging server.
  • The document id/external_id__v field with the values of each document to which we're adding a new version.
  • All required fields to add document versions of the specified document types in our vault.
  • The major and minor document version numbers being assigned to the new versions.
  • The document status__v field with valid values for the selected document lifecycle.

Download Input File

Top

CSV: Delete Document Versions

  • Supported in the Bulk API: YES (See request)
  • Supported in Vault Loader: NO
  • Other supported input formats: JSON (See input)

Referencing Existing Documents

When deleting versions, you can use one of two standard document ID fields in the input:

  • id - System-assigned document ID. This numeric field value exists on all documents. It is non-editable.
  • external_id__v - User-defined document external ID. This alphanumeric field is not always configured with values. It is editable.

By default, Vault looks for the id field in the input. To use external_id__v instead, add the idParam=external_id__v parameter to the request endpoint.

Required Fields

When deleting versions, the following standard fields are required in all vaults:

  • major_version_number__v - Major version number of the document version to remove.
  • minor_version_number__v - Minor version number of the document version to remove.

Example Inputs

Using the document id field:

id major_version_number__v minor_version_number__v
771 0 2
772 0 2
773 1 1
774 1 2

Using the document external_id__v field:

external_id__v major_version_number__v minor_version_number__v
ALT-DOC-0771 0 2
CHO-DOC-0772 0 2
GLU-DOC-0773 1 1
NYA-DOC-0774 1 2

Download Input File

Top

CSV: Add Document Renditions

  • Supported in the Bulk API: YES (See request)
  • Supported in Vault Loader: YES (See request)
  • Other supported input formats: NO

Uploading Source Files

  • Before loading your input, you must upload the document source files to your vault's staging server. Learn more.
  • In your input, include the file field name and enter the path/name of each source file.

Referencing Existing Documents

When using the Bulk API to add renditions, you can use one of two standard document ID fields in the input:

  • id - System-assigned document ID. This numeric field value exists on all documents. It is non-editable.
  • external_id__v - User-defined document external ID. This alphanumeric field is not always configured with values. It is editable.

By default, Vault looks for the id field in the input. To use external_id__v instead, add the idParam=external_id__v parameter to the request endpoint.

Required Fields

When adding versions, the following standard fields are required in all vaults:

  • rendition_type__v - Document rendition type to assign to the new rendition. Only one rendition of each type may exist on each document.
  • major_version_number__v - Major version number to assign to the new document version.
  • minor_version_number__v - Minor version number to assign to the new document version.

Referencing Vault Objects (Lookups)

When assigning objects to documents, you can use either of the following methods:

file id rendition_type__v major_version_number__v minor_version_number__v product__v country__v
docs/doc1-r2.pdf 771 imported_rendition__vs 0 2 0PR0101 0CT0555

Where 0PR0101 and 0CT0555 are the system-managed IDs of the product__v and country__v object records Alterin and United States, respectively.

Alternatively, you can use dot-notation with the object name and the name__v field to call out the object record names directly, as shown below.

file id rendition_type__v major_version_number__v minor_version_number__v product__v.name__v country__v.name__v
docs/doc1-r2.pdf 771 imported_rendition__vs 0 2 Alterin United States

Additional Requirements

Example Inputs

Using the document id field:

file id rendition_type__v major_version_number__v minor_version_number__v
docs/doc1-r2.pdf 771 imported_rendition__vs 0 2
docs/doc2-r2.pdf 772 imported_rendition__vs 0 2
docs/doc3-r2.pdf 773 imported_rendition__vs 0 2

Using the document external_id__v field:

file external_id__v rendition_type__v major_version_number__v minor_version_number__v
docs/doc1-r2.pdf ALT-DOC-0771 imported_rendition__vs 0 2
docs/doc2-r2.pdf CHO-DOC-0772 imported_rendition__vs 0 2
docs/doc3-r2.pdf GLU-DOC-0773 imported_rendition__vs 0 2

These examples include:

  • The file field parameter with three document rendition source files located in the "docs" directory of our vault's staging server.
  • The document id/external_id__v field with values of each document to which we're adding a new rendition.
  • The document rendition_type__v field with values for rendition types in our vault.
  • The major and minor document version numbers being assigned to the new rendition.

Download Input File

Top

CSV: Delete Document Renditions

  • Supported in the Bulk API: YES (See request)
  • Supported in Vault Loader: NO
  • Other supported input formats: JSON (See input)

Referencing Existing Documents

When deleting renditions, you can use one of two standard document ID fields in the input:

  • id - System-assigned document ID. This numeric field value exists on all documents. It is non-editable.
  • external_id__v - User-defined document external ID. This alphanumeric field is not always configured with values. It is editable.

By default, Vault looks for the id field in the input. To use external_id__v instead, add the idParam=external_id__v parameter to the request endpoint.

Required Fields

When deleting renditions, the following standard fields are required in all vaults:

  • rendition_type__v - Document rendition type to delete from the document.
  • major_version_number__v - Major version number of the document rendition to delete.
  • minor_version_number__v - Minor version number of the document rendition to delete.

Example Inputs

Using the document id field:

id rendition_type__v major_version_number__v minor_version_number__v
771 imported_rendition__vs 0 2
772 imported_rendition__vs 0 2
773 imported_rendition__vs 0 2

Using the document external_id__v field:

external_id__v rendition_type__v major_version_number__v minor_version_number__v
ALT-DOC-0771 imported_rendition__vs 0 2
CHO-DOC-0772 imported_rendition__vs 0 2
GLU-DOC-0773 imported_rendition__vs 0 2

Top

CSV: Update Document Roles

Available Options

  • Add users and groups to document roles. See below
  • Remove users and groups from document roles. See below

Retrieving Document Roles

  • Vault documents are configured with a set of roles that provide the assigned users and groups with specific permissions to view and perform actions on each document.
  • The roles available for a document are configurable and depend on the document’s lifecycle. Some roles are included by default. Admins can also create custom roles that are unique to a particular document type and lifecycle. Learn more.
  • Both default and available roles are configured by Admin for each document type and lifecycle. When a document is created or changes workflows, Vault automatically assigns users and groups to roles based on the default roles set for the lifecycle. Learn more.
  • The vault’s configuration determines the permissions available to each role and permissions can change based on the document’s status. Security profiles may also override role assignments by giving users more or fewer permissions. Learn more.

Document Role Assignment Rules

  • 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. Vault provides an error message describing the failure.
  • If a role specified in the input is not available on a particular document, the API will not assign that user or group to the role but will attempt to assign other users and groups in the request. You need to confirm the list of role:ID pairs returned in the results to ensure all users and groups were successfully added.
  • To see all roles configured on a lifecycle, go to Admin > Configuration > Lifecycles & Workflows. Click into a lifecycle and then click the Roles tab.

Required Fields

  • When updating document roles, the system-managed document id is the only required field in all vaults.
  • Vault matches document IDs in the input with existing documents in your vault.

Assigning Users and Groups to Roles

  • To assign users to roles, include the {role__v}.users field with a string of user id field values.
  • To assign users to roles, include the {role__v}.groups field with a string of group id field values.
  • Separate multiple id values in a comma-delimited string within the role field value. Since the value itself contains a comma, double quotes must surround it.
  • Field names and values not included in the input remain unchanged on the document.

To retrieve document role information:

  • Use the Retrieve Roles API to retrieve all available roles, users, and groups assigned to documents.
  • Use Vault Loader Document Extract to retrieve fields and values configured on specific documents.
  • Go to Admin > Configuration > Lifecycles & Workflows > [Lifecycle] > Roles to find all available roles on each lifecycle. Learn more.

Top

CSV: Assign Users and Groups to Document Roles

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

Top

CSV: Remove Users and Groups from Document Roles

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

Top

CSV: Documents, Versions, and Roles using a Single Input File

Vault Loader supports the use of a single CSV file to create documents, assign users/groups to roles, and create document versions.

  • Supported in the Bulk API: NO
  • Supported in Vault Loader: YES (See request)
  • Other supported input formats: NO

Uploading Source Files

  • Before loading your input, you must upload the document source files to your vault's staging server. Learn more.
  • In your input, include the file field name and enter the path/name of each source file.

Referencing Documents

This request requires you use the external_id__v document field to reference documents in your input.

Additional Requirements

Example Input

file external_id__v name__v type__v subtype__v classification__v lifecycle__v major_version_number__v minor_version_number__v reviewer__v.users reviewer__v.groups
docs/doc1-v1.doc ALT-DOC-0771 Alterin Doc Resource General Lifecycle 0 1 "12021,12022" "3311303,3311404"
docs/doc1-v2.doc ALT-DOC-0771 Alterin Doc Resource General Lifecycle 0 2 "12021,12022" "3311303,3311404"
docs/doc2-v1.doc CHO-DOC-0772 CholeCap Doc Promotional Piece Convention Item Promotional Piece 0 1 "12021,12022" "3311303,3311404"
docs/doc2-v2.doc CHO-DOC-0772 CholeCap Doc Promotional Piece Convention Item Promotional Piece 0 2 "12021,12022" "3311303,3311404"

Top

CSV: Create Document Relationships

  • Supported in the Bulk API: YES (See request)
  • Supported in Vault Loader: NO
  • Other supported input formats: JSON (See input)

Required Fields

When creating document relationships, the following fields are required in all vaults:

  • source_doc_id__v - Document id value of the document on which the relationship is being created.
  • target_doc_id__v - Document id value of the document which is being associated with the source document as a related document.

The following fields may also be required, depending on the relationship being created.

  • source_major_version__v - Major version number of the source document.
  • source_minor_version__v - Minor version number of the source document.
  • target_major_version__v - Major version number of the target document.
  • target_minor_version__v - Minor version number of the target document.
  • relationship_type__v - The type of relationship the target document will have with the source document.

Example CSV Input

source_doc_id__v source_major_version__v source_minor_version__v target_doc_id__v target_major_version__v target_minor_version__v relationship_type__v
101 0 1 251 1 0 basedon__vs
102 0 2 252 1 1 related_pieces__vs
103 1 0 253 1 2 supporting_documents__vs

After submitting the input, the Vault response will list the id value of each new relationship.

Top

CSV: Delete Document Relationships

  • Supported in the Bulk API: YES (See request)
  • Supported in Vault Loader: NO
  • Other supported input formats: JSON (See input)

Required Fields

When deleting document relationships, the relationship id is the only required field.

Example CSV Input

id
10
11
12

After submitting the input, the Vault response will list the id value of each deleted relationship.

Top

CSV: Create Object Records

Required Standard Fields

  • When creating new object records for standard Vault Objects (ending in __v), the object record name__v is the only default required field in all vaults.
  • When creating new object records for custom Vault Objects (ending in __c), the name__v field may be set to system-managed. In this case, the name__v is not required.

System-Managed Object Record Naming

As of v14.0, Admins may set the name__v field on any custom object to be system-managed. This means that Vault, not the users creating new records for the object, adds the name__v value.

  • When creating new records for custom objects in which the name is system-managed, do not include the name__v value in the input.
  • If there are no other fields set to required on the custom object, you do not need to include anything in the input.
  • You may include other optional, editable fields in the input.

This only applies to custom Vault Objects and must first be configured by Admin. Standard Vault Objects (product__v, country__v, etc.) cannot be set to use system-managed naming.

  • To find out if an object uses system-managed naming, retrieve its name__v field and look for the system_managed_name property set to true or false.

Learn more about system-managed object record naming.

Additional Required & Editable Fields

Admin may set other standard or custom object fields to required.

  • Use the Retrieve Object Metadata API to retrieve all fields configured on objects. In the field specifications: Required fields: required:true / Editable fields: editable:true.
  • Use Vault Loader Object Record Extract to retrieve fields and values configured on specific object records.
  • Go to Admin > Business Admin to see objects, object records, and fields. Learn more.
  • As of v14, you can create a copy of an existing object record. Add the source_record_id field with the id of the existing record you wish to copy. Any values specified for other fields will override the copied values. If you want to make a deep copy of a record, see the Deep Copy endpoint.

If a required field is not included in the input, Vault returns a PARAMETER_REQUIRED error with the name of the missing field. When this occurs, Vault does not process any records in the input.

You can include any editable document field and value in the input.

Example Input

name__v generic_name__vs external_id__v
Alterin alterol nitrate ALT-PROD-0771
CholeCap cholepriol phosphate CHO-PROD-0772
Gludacta glucerin sulfate GLU-PROD-0773
Nyaxa nitroprinaline oxalate NYA-PROD-0774

Example Input

name__v generic_name__vs product_family__vs abbreviation__vs external_id__v therapeutic_area__vs manufacturer_name__v regions__c
Alterin alterol nitrate aldinadol__c ALT ALT-PROD-0771 psychiatry__vs Veeva Labs "asia_pacific__c,australasia__c"
CholeCap cholepriol phosphate cholepriol__c CHO CHO-PROD-0772 cardiology__vs Veeva Labs north_america__c
Gludacta glucerin sulfate "glucine__c,gerdactine__c" GLU GLU-PROD-0773 neurology__vs Veeva Labs south_america__c
Nyaxa nitroprinaline oxalate nitroprinaline__c NYA NYA-PROD-0774 veterinary__c Veeva Labs europe__c

Download Input File

Top

CSV: Update Object Records

Required Fields

When updating object records, the object record id is the only required field in all vaults.

Updating Fields

You can include any editable object field and value in the input.

  • Use the Retrieve Object Metadata API to retrieve all fields configured on objects. In the field specifications: Required fields: Editable fields: editable:true.
  • Use Vault Loader Object Record Extract to retrieve fields and values configured on specific object records.
  • Go to Admin > Business Admin to see objects, object records, and fields. Learn more.

Note: If the object records being updated are on an object that is a "parent" in a parent-child relationship with another object, you cannot update its status__v field in bulk.

Example Input

id generic_name__vs external_id__v
0PR0101 alterol nitrate ALT-PROD-0771
0PR0202 cholepriol phosphate CHO-PROD-0772
0PR0303 glucerin sulfate GLU-PROD-0773
0PR0404 nitroprinaline oxalate NYA-PROD-0774

Example Input

id generic_name__vs product_family__vs abbreviation__vs external_id__v therapeutic_area__vs manufacturer_name__v regions__c
0PR0101 alterol nitrate aldinadol__c ALT ALT-PROD-0771 psychiatry__vs Veeva Labs "asia_pacific__c,australasia__c"
0PR0202 cholepriol phosphate cholepriol__c CHO CHO-PROD-0772 cardiology__vs Veeva Labs north_america__c
0PR0303 glucerin sulfate "glucine__c,gerdactine__c" GLU GLU-PROD-0773 neurology__vs Veeva Labs south_america__c
0PR0404 nitroprinaline oxalate nitroprinaline__c NYA NYA-PROD-0774 veterinary__c Veeva Labs europe__c

Download Input File

Updating Object Record Roles

When Dynamic Security (Custom Sharing Rules) is configured on an object, you can add or remove users and groups on manually assigned roles on up to 500 object records at a time. This is available in API v11.0 or later.

Learn more about Dynamic Security (Custom Sharing Rules):

Input

The following fields are allowed:

id - [Required] The object record id field value.
owner__v.users - Optional
owner__v.groups - Optional
editor__v.users - Optional
editor__v.groups - Optional
viewer__v.users - Optional
viewer__v.groups - Optional

You can assign one or more users or groups to each role. To do so, include a comma-separated list of user or group id field values.

This action is not additive. That is, if other users and groups are already assigned to a role, they will be overwritten by those in the input.

Note that only a user in the owner role can assign other users or groups to the owner role.

CSV Input Example:

id,owner__v.users,editor__v.users,editor__v.groups,viewer__v.users,viewer__v.groups
00PR0202,12022,"60145,70012,89546",4411606,"35551,48948,55002",3311303

Example Request (CSV Input)

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
-H "Accept: text/csv" \ 
--data-binary @"C:\Vault\Object Records\update_object_record_users_groups.csv" \
https://myvault.veevavault.com/api/v11.0/vobjects/product__v

Example Response (CSV)

responseStatus,id,url,errors
SUCCESS,00PR0202,api/v8.0/api/v11.0/vobjects/product__v/00PR0202,

Errors

Error Type Error Message Description
INSUFFICIENT_ACCESS User does not have sufficient privileges to perform the action. Vault restricts some users from changing role assignments (learn more). Note that only users who are in the owner role can add or remove other owners.
INVALID_DATA Invalid value(s) [{list of invalid IDs}] specified for parameter [{role name}] : user IDs do not resolve to a valid active [user] objects. The user IDs included in the input could not be found in your vault. Only active users can be assigned to the roles.
INVALID_DATA Invalid value(s) [{list of invalid IDs}] specified for parameter [{role name}] : group IDs do not resolve to a valid active [group] objects. The group IDs included in the input could not be found in your vault. Only active groups can be assigned to the roles.

History

Since v11

Top

CSV: Upsert Object Records

  • Supported in the Bulk API: NO
  • Supported in Vault Loader: YES (See request)
  • Other supported input formats: NO

About the Upsert Action

  • The upsert action combines update and create (insert).
  • If a matching object record is found in your vault, it is updated with the field values specified in the input.
  • If no matching object record is found, a new object record is created using values in the input.

Example Input

id name__v
Alterin
Gludacta
Sintrolet
00P1110 CholeCap
00P2220 Nyaxa
00P3330 VeevaProm

Example Input

id name__v generic_name__vs product_family__vs abbreviation__vs external_id__v therapeutic_area__vs manufacturer_name__v regions__c
00P1110 CholeCap cholepriol phosphate cholepriol__c CHO CHO-1110 cardiology__vs Veeva Labs north_america__c
00P2220 Nyaxa nitroprinaline__c NYA NYA-2220 veterinary__c Veeva Labs europe__c
00P3330 VeevaProm veniladrine sulfate "veniladrine__c,vendolepene__c" VPR VPR-3330 psychiatry__vs Veeva Labs "north_america__c,south_america__c"
Alterin bodriophin bodriophin__c ALT ALT-4440 neurology__vs Veeva Labs australasia__c
Gludacta glucerin nitroprinaline__c GLU GLU-5550 hematology__vs Veeva Labs asia_pacific__c
Sintrolet sertropenol "sertropinol__c,sentrolepene__c" SNT SNT-6660 endocrinology__vs Veeva Labs middle_east__c

Download Input File

Top

CSV: Delete Object Records

Referencing Existing Object Records

When deleting object records, you can use one of two standard document ID fields in the input:

  • id - System-assigned object record ID. This numeric field value exists on all object records. It is non-editable. This can be used with the Bulk API and Vault Loader.
  • external_id__v - User-defined document external ID. This alphanumeric field is not always configured with values. It is editable. This can be used with the Bulk API only.

By default, Vault looks for the id field in the input. To use external_id__v instead, add the idParam=external_id__v parameter to the request endpoint.

Example Inputs

Bulk API & Vault Loader - Using the document id field:

id
0PR0101
0PR0202
0PR0303

Bulk API - Using the document external_id__v field:

external_id__v
CHO-1110
NYA-2220
VPR-3330

Top

CSV: Create Users

Required Fields

When creating new users, the following fields are required in all vaults:

  • user_name__v
  • user_first_name__v
  • user_last_name__v
  • user_email__v
  • user_timezone__v
  • user_locale__v
  • user_language__v
  • security_policy_id__v

Using only these fields will add users to your vault domain but will not assign them to individual vaults within your domain. See Vault Membership Assignments below.

Admins cannot create custom user fields nor can they set other standard user fields to required.

Editable Fields

You can include any editable user field and value in the input.

  • Use the Retrieve User Metadata API to retrieve all fields configured on the users object. In the field specifications: Editable fields: editable:true.
  • Go to Admin > Users & Groups > Users to see users, fields, and values. Learn more.

Vault Membership Assignments

To assign user permissions across vaults or create cross-domain users, you must include vault_membership column in the input and configure it with the following fields:

  • id - Include Vault ID to which the user is being assigned. This value is required. Learn how to Retrieve Domain Information.
  • active__v - Set the user to active or inactive in the vault (true or false). If not specified, this value defaults to true.
  • security_profile__v - Set the user's security profile in the vault (document_user__v, read_only_user__v, etc.). If not specified, this value defaults to document_user__v.
  • license_type__v - Set the user's license type in the vault (full__v, read_only__v, etc.). If not specified, this value defaults to full__v.

To understand default settings, consider these two examples. Each produces the same result:

id (user) vault_membership Discussion
11001 3003:true:document_user__v:full__v The user is assigned membership in Vault ID 3003.
11001 3003 Same as above. Remaining values are set to default.

The next two examples also produce the same result:

id (user) vault_membership Discussion
11002 3003:true:system_admin__v:`full__v The user is assigned a system_admin__v security profile.
11002 3003::system_admin__v Same as above. Remaining values are set to default.

The next two examples demonstrate adding users to multiple vaults in a domain. Both users are being assigned to vaults 3003, 4004, and 5005. The first user (11003) will be active in each vault with a document_user__v security profile and full__v license type. The second user (11004) will be an inactive read-only user in vault 3003 and an active administrator (system_admin__v and business_admin__v) with full__v license type in vaults 4004 and 5005.

id (user) vault_membership
11003 "3003,4004,5005"
11004 "3003:false:read_only_user__v:read_only__v,4004::system_admin__v,5005::business_admin__v"

Example Input

user_name__v user_first_name__v user_last_name__v user_email__v user_timezone__v user_locale__v user_language__v security_policy_id__v file vault_membership
ally@veevapharm.com Ally Abernathy ally@veevapharm.com America/Denver en_US en 821 images/ally.jpg 3003:true:business_admin__v:full__v
beth@veevapharm.com Beth Benedict beth@veevapharm.com Europe/London en_GB en 821 images/beth.jpg 3003:true:document_user__v:full__v
carl@veevapharm.com Carl Connors carl@veevapharm.com Australia/Sydney en_AU en 554 4114:true:system_admin__v:full__v
dean@veevapharm.com Dean Donovan dean@veevapharm.com Asia/Shanghai zh_CN zh_CN 554 5225:true:read_only_user__v:read_only__v

Download Input File

Top

CSV: Update Users

Required Fields

When updating existing user records, the user id is the only required field in all vaults.

Updating Fields

You can include any editable user field and value in the input.

  • Use the Retrieve User Metadata API to retrieve all fields configured on the users object. In the field specifications: Editable fields: editable:true.
  • Go to Admin > Users & Groups > Users to see users, fields, and values. Learn more.

Example Input

id user_title__v mobile_phone__v office_phone__v
12021 Senior Product Manager +1 (925) 452-6500
12022 "Director, Product Management" +1 (866) 478-9492

Download Input File

Deactivate User at the Domain Level

Sets the user (id:12022) status to inactive in all vaults within the domain.

id,domain_active__v
12022,false

Reactivate User at the Domain Level

Sets the user (id:12022) status to active at the domain-level.

Reactivating at the domain level may not make a user active on every vault. Some users may not be active in any vaults. If the user previously had membership in a given vault, they become active in that vault with their previously assigned license type and security profile. If the user did not have membership in a given vault, they will not have access until you've assigned them.

id,domain_active__v
12022,true

Deactivate User at the Vault Level

Sets the user (id:12022) status to inactive in the vault (id:3003).

They will still be active at the domain-level and within other vaults in which they are members.

id,vault_membership
12022,"3003:false"

To deactivate the user from more than one vault, format the input as follows:

id,vault_membership
12022,"3003:false,4004:false"

Reactivate User at the Vault Level

Sets the user (id:12022) status to active in the vault (id:3003).

They must first be active at the domain level. If using just the vault ID as shown below, the user automatically receives the Full User license type and Document User security profile, even if they had been previously assigned something different in the vault. To assign a different license type and security profile, include them in the input. See Vault Membership Assignments above.

id,vault_membership
12022,"3003"

To reactivate the user in more than one vault, format the input as follows:

id,vault_membership
12022,"3003,4004"

Top

CSV: Upsert Users

About the Upsert Action

  • The upsert action combines update and create (insert).
  • If a matching user record is found in your vault, it is updated with the field values specified in the input.
  • If no matching user record is found, a new user is created using values in the input.

Example Input

user_name__v user_first_name__v user_last_name__v user_email__v user_timezone__v user_locale__v user_language__v security_policy_id__v user_title__v
ally@veevapharm.com Ally Abernaty ally@veevapharm.com America/Denver en_US en 821 Senior Product Manager
beth@veevapharm.com Beth Benedict beth@veevapharm.com Europe/London en_GB en 821 "Director, Product Management"
carl@veevapharm.com Carl Connors carl@veevapharm.com Australia/Sydney en_AU en 554 Technical Writer
dean@veevapharm.com Dean Donovan dean@veevapharm.com Asia/Shanghai zh_CN zh_CN 554 "Director, Product Management"
etta@veevapharm.com Etta Everest etta@veevapharm.com Australia/Sydney en_AU en 202 Senior Product Manager
finn@veevapharm.com Finn Folley finn@veevapharm.com America/New_York en_US en 202 "VP, Technology"
greg@veevapharm.com Greg Gardner greg@veevapharm.com America/Los_Angeles en_US en 202 Senior Technical Writer
Hope@veevapharm.com Hope Harris hope@veevapharm.com America/Denver en_US en 202 "VP, Product Operations"

Download Input File

Top

CSV: Create Groups

  • Supported in the Bulk API: NO
  • Supported in Vault Loader: YES (See request)
  • Other supported input formats: NO

Required Fields

When creating new groups, the group label__v is the only default required field in all vaults.

Admins cannot create custom group fields nor can they set other standard group fields to required.

Editable Fields

You can include any editable group field and value in the input.

  • Use the Retrieve Group Metadata API to retrieve all fields configured on the groups object. In the field specifications: Editable fields: editable:true.
  • Go to Admin > Users & Groups > Groups to see groups, fields, and values. Learn more.

Example Input

label__v members__v group_description__v
Alterin Researchers "12021,12022,12023" Group responsible for Alterin documents
CholeCap Editors Group "22124,22125,22126" Group responsible for CholeCap documents

Top

CSV: Update Groups

  • Supported in the Bulk API: NO
  • Supported in Vault Loader: YES (See request)
  • Other supported input formats: NO

Required Fields

When updating existing group records, the group id is the only required field in all vaults.

Updating Fields

You can include any editable group field and value in the input.

  • Use the Retrieve Group Metadata API to retrieve all fields configured on the groups object. In the field specifications: Editable fields: editable:true.
  • Go to Admin > Users & Groups > Groups to see groups, fields, and values. Learn more.

Example Input

id members__v group_description__v active__v
3311303 "12021,12022,12023" Group responsible for Alterin documents
4411606 "22124,22125,22126" Group responsible for CholeCap documents

Top

CSV: Upsert Groups

  • Supported in the Bulk API: NO
  • Supported in Vault Loader: YES (See request)
  • Other supported input formats: NO

About the Upsert Action

  • The upsert action combines update and create (insert).
  • If a matching group record is found in your vault, it is updated with the field values specified in the input.
  • If no matching group record is found, a new group is created using values in the input.

Example Input

id members__v group_description__v
10010001 "11001,11002,11003,11004" Group responsible for Alterin documents
10200002 "22001,22002,22003,22004" Group responsible for CholeCap documents
10030003 "33001,33002,33003,33004" Group responsible for Gludacta documents

Example Input

name__v members__v group_description__v
alterin_researchers__c "11001,11002,11003,11004" Group responsible for Alterin documents
cholecap_editors_group__c "22001,22002,22003,22004" Group responsible for CholeCap documents
gludacta_requirements_group__c "33001,33002,33003,33004" Group responsible for Gludacta documents
veevaprom_documents_group__c "44001,44002,44003,44004" Group responsible for VeevaProm documents

Top

JSON: Delete Documents

  • Supported in the Bulk API: YES (See request)
  • Supported in Vault Loader: NO
  • Other supported input formats: CSV (See input)

Referencing Existing Documents

When deleting documents, you can use one of two standard document ID fields in the input:

  • id - System-assigned document ID. This numeric field value exists on all documents. It is non-editable.
  • external_id__v - User-defined document external ID. This alphanumeric field is not always configured with values. It is editable.

By default, Vault looks for the id field in the input. To use external_id__v instead, add the idParam=external_id__v parameter to the request endpoint.

Example Inputs

Using the document id field:

[
{
    "id": "771"
},
{
    "id": "772"
},
{
    "id": "773"
},
{
    "id": "774"
}
]

Using the document external_id__v field:

[
{
    "external_id__v": "ALT-DOC-0771"
},
{
    "external_id__v": "CHO-DOC-0772"
},
{
    "external_id__v": "GLU-DOC-0773"
},
{
    "external_id__v": "NYA-DOC-0774"
}
]

Top

JSON: Delete Document Versions

  • Supported in the Bulk API: YES (See request)
  • Supported in Vault Loader: NO
  • Other supported input formats: CSV (See input)

Referencing Existing Documents

When deleting versions, you can use one of two standard document ID fields in the input:

  • id - System-assigned document ID. This numeric field value exists on all documents. It is non-editable.
  • external_id__v - User-defined document external ID. This alphanumeric field is not always configured with values. It is editable.

By default, Vault looks for the id field in the input. To use external_id__v instead, add the idParam=external_id__v parameter to the request endpoint.

Required Fields

When deleting versions, the following standard fields are required in all vaults:

  • major_version_number__v - Major version number of the document version to remove.
  • minor_version_number__v - Minor version number of the document version to remove.

Example Inputs

Using the document id field:

[
{
    "id": "771",
    "major_version_number__v": "0",
    "minor_version_number__v": "2"
},
{
    "id": "772",
    "major_version_number__v": "0",
    "minor_version_number__v": "2"
},
{
    "id": "773",
    "major_version_number__v": "1",
    "minor_version_number__v": "1"
},
{
    "id": "774",
    "major_version_number__v": "1",
    "minor_version_number__v": "2"
}
]

Using the document external_id__v field:

[
{
    "external_id__v": "ALT-DOC-0771",
    "major_version_number__v": "0",
    "minor_version_number__v": "2"
},
{
    "external_id__v": "CHO-DOC-0772",
    "major_version_number__v": "0",
    "minor_version_number__v": "2"
},
{
    "external_id__v": "GLU-DOC-0773",
    "major_version_number__v": "1",
    "minor_version_number__v": "1"
},
{
    "external_id__v": "NYA-DOC-0774",
    "major_version_number__v": "1",
    "minor_version_number__v": "2"
}
]

Top

JSON: Delete Document Renditions

  • Supported in the Bulk API: YES (See request)
  • Supported in Vault Loader: NO
  • Other supported input formats: CSV (See input)

Referencing Existing Documents

When deleting renditions, you can use one of two standard document ID fields in the input:

  • id - System-assigned document ID. This numeric field value exists on all documents. It is non-editable.
  • external_id__v - User-defined document external ID. This alphanumeric field is not always configured with values. It is editable.

By default, Vault looks for the id field in the input. To use external_id__v instead, add the idParam=external_id__v parameter to the request endpoint..

Required Fields

When deleting renditions, the following standard fields are required in all vaults:

  • rendition_type__v - Document rendition type to delete from the document.
  • major_version_number__v - Major version number of the document rendition to delete.
  • minor_version_number__v - Minor version number of the document rendition to delete.

Example Inputs

Using the document id field:

[
{
    "id": "771",
    "rendition_type__v": "imported_rendition__vs",
    "major_version_number__v": "0",
    "minor_version_number__v": "2"
},
{
    "id": "772",
    "rendition_type__v": "imported_rendition__vs",
    "major_version_number__v": "0",
    "minor_version_number__v": "2"
},
{
    "id": "773",
    "rendition_type__v": "imported_rendition__vs",
    "major_version_number__v": "1",
    "minor_version_number__v": "1"
},
{
    "id": "774",
    "rendition_type__v": "imported_rendition__vs",
    "major_version_number__v": "1",
    "minor_version_number__v": "2"
}
]

Using the document external_id__v field:

[
{
    "external_id__v": "ALT-DOC-0771",
    "rendition_type__v": "imported_rendition__vs",
    "major_version_number__v": "0",
    "minor_version_number__v": "2"
},
{
    "external_id__v": "CHO-DOC-0772",
    "rendition_type__v": "imported_rendition__vs",
    "major_version_number__v": "0",
    "minor_version_number__v": "2"
},
{
    "external_id__v": "GLU-DOC-0773",
    "rendition_type__v": "imported_rendition__vs",
    "major_version_number__v": "1",
    "minor_version_number__v": "1"
},
{
    "external_id__v": "NYA-DOC-0774",
    "rendition_type__v": "imported_rendition__vs",
    "major_version_number__v": "1",
    "minor_version_number__v": "2"
}
]

Top

JSON: Create Document Relationships

  • Supported in the Bulk API: YES (See request)
  • Supported in Vault Loader: NO
  • Other supported input formats: CSV (See input)

Required Fields

When creating document relationships, the following fields are required in all vaults:

  • source_doc_id__v - Document id value of the document on which the relationship is being created.
  • target_doc_id__v - Document id value of the document which is being associated with the source document as a related document.

Depending on the relationship being created, the following fields may also be required:

  • source_major_version__v - Major version number of the source document.
  • source_minor_version__v - Minor version number of the source document.
  • target_major_version__v - Major version number of the target document.
  • target_minor_version__v - Minor version number of the target document.
  • relationship_type__v - The type of relationship the target document will have with the source document.

Example JSON Input

[
{
    "source_doc_id__v": "101",
    "source_major_version__v": "0",
    "source_minor_version__v": "1",
    "target_doc_id__v": "251",
    "target_major_version__v": "1",
    "target_minor_version__v": "0",
    "relationship_type__v": "basedon__vs"
},
{
    "source_doc_id__v": "102",
    "source_major_version__v": "0",
    "source_minor_version__v": "2",
    "target_doc_id__v": "252",
    "target_major_version__v": "1",
    "target_minor_version__v": "1",
    "relationship_type__v": "related_pieces__vs"
},
{
    "source_doc_id__v": "103",
    "source_major_version__v": "1",
    "source_minor_version__v": "0",
    "target_doc_id__v": "253",
    "target_major_version__v": "1",
    "target_minor_version__v": "2",
    "relationship_type__v": "supporting_documents__vs"
}
]

After submitting the input, the Vault response will list the id value of each new relationship.

Top

JSON: Delete Document Relationships

  • Supported in the Bulk API: YES (See request)
  • Supported in Vault Loader: NO
  • Other supported input formats: CSV (See input)

Required Fields

When deleting document relationships, the relationship id is the only required field.

Example CSV Input

[
{
    "id": "10"
},
{
    "id": "11"
},
{
    "id": "12"
}
]

After submitting the input, the Vault response will list the id value of each deleted relationship.

Top

JSON: Create Object Records

  • Supported in the Bulk API: YES (See request)
  • Supported in Vault Loader: YES (CSV input only)
  • Other supported input formats: CSV (See input)

Required Standard Fields

  • When creating new object records for standard Vault Objects (ending in __v), the object record name__v is the only default required field in all vaults.
  • When creating new object records for custom Vault Objects (ending in __c), the name__v field may be set to system-managed. In this case, the name__v is not required.

System-Managed Object Record Naming

As of v14.0, Admins may set the name__v field on any custom object to be system-managed. This means that Vault, not the users creating new records for the object, adds the name__v value.

  • When creating new records for custom objects in which the name is system-managed, do not include the name__v value in the input.
  • If there are no other fields set to required on the custom object, you do not need to include anything in the input.
  • You may include other optional, editable fields in the input.

This only applies to custom Vault Objects and must first be configured by Admin. Standard Vault Objects (product__v, country__v, etc.) cannot be set to use system-managed naming.

  • To find out if an object uses system-managed naming, retrieve its name__v field and look for the system_managed_name property set to true or false.

Learn more about system-managed object record naming.

Additional Required & Editable Fields

Admin may set other standard or custom object fields to required in your vault.

  • Use the Retrieve Object Metadata API to retrieve all fields configured on objects. In the field specifications: Required fields: required:true / Editable fields: editable:true.
  • Use Vault Loader Object Record Extract to retrieve fields and values configured on specific object records.
  • Go to Admin > Business Admin to see objects, object records, and fields. Learn more.
  • As of v14, you can create a copy of an existing object record. Add the source_record_id field with the id of the existing record you wish to copy. Any values specified for other fields will override the copied values. If you want to make a deep copy of a record, see the Deep Copy endpoint.

If a required field is not included in the input, Vault returns a PARAMETER_REQUIRED error with the name of the missing field. When this occurs, Vault does not process any records in the input.

You can include any editable document field and value in the input.

Example Input

[
{
    "name__v": "CholeCap"
},
{
    "name__v": "Nyaxa"
},
{
    "name__v": "VeevaProm"
},
]

Example Input

[
{
    "name__v": "CholeCap",
    "generic_name__vs": "cholepriol phosphate",
    "product_family__vs": "cholepriol__c",  
    "abbreviation__vs": "CHO",
    "external_id__v": "CHO-1110",
    "therapeutic_area__vs": "cardiology__vs",
    "manufacturer_name__v": "Veeva Labs",
    "regions__c": "north_america__c"
},
{
    "name__v": "Nyaxa",
    "generic_name__vs": "nitroprinaline oxalate",
    "product_family__vs": "nitroprinaline__c",  
    "abbreviation__vs": "NYA",
    "external_id__v": "NYA-2220",
    "therapeutic_area__vs": "veterinary__c",
    "manufacturer_name__v": "Veeva Labs",
    "regions__c": "europe__c"
},
{
    "name__v": "VeevaProm",
    "generic_name__vs": "veniladrine sulfate",
    "product_family__vs": "veniladrine__c,vendolepene__c",  
    "abbreviation__vs": "NYA",
    "external_id__v": "VPR-3330",
    "therapeutic_area__vs": "psychiatry__vs",
    "manufacturer_name__v": "Veeva Labs",
    "regions__c": "asia_pacific__c,australasia__c"  
}
]

Download Input File

Top

JSON: Update Object Records

  • Supported in the Bulk API: YES (See request)
  • Supported in Vault Loader: YES (CSV input only)
  • Other supported input formats: CSV (See input)

Required Fields

When updating object records, the object record id is the only required field in all vaults.

Updating Fields

You can include any editable object field and value in the input.

  • Use the Retrieve Object Metadata API to retrieve all fields configured on objects. In the field specifications: Required fields: required:true / Editable fields: editable:true.
  • Use Vault Loader Object Record Extract to retrieve fields and values configured on specific object records.
  • Go to Admin > Business Admin to see objects, object records, and fields. Learn more.

Note: If the object records being updated are on an object that is a "parent" in a parent-child relationship with another object, you cannot update its status__v field in bulk.

Example Input

[
{
    "id": "00P1110",
    "generic_name__vs": "cholepriol phosphate"
},
{
    "id": "00P2220",
    "generic_name__vs": ""
},
{
    "id": "00P3330",
    "regions__c": "north_america__c,south_america__c"
}
]

Example Input

[
{
    "id": "00P1110",
    "generic_name__vs": "cholepriol phosphate",
    "product_family__vs": "cholepriol__c",  
    "abbreviation__vs": "CHO",
    "external_id__v": "CHO-1110",
    "therapeutic_area__vs": "cardiology__vs",
    "manufacturer_name__v": "Veeva Labs",
    "regions__c": "north_america__c"
},
{
    "id": "00P2220",
    "generic_name__vs": "",
    "product_family__vs": "nitroprinaline__c",  
    "abbreviation__vs": "NYA",
    "external_id__v": "NYA-2220",
    "therapeutic_area__vs": "veterinary__c",
    "manufacturer_name__v": "Veeva Labs",
    "regions__c": "europe__c"
},
{
    "id": "00P3330",
    "generic_name__vs": "veniladrine sulfate",
    "product_family__vs": "veniladrine__c,vendolepene__c",  
    "abbreviation__vs": "NYA",
    "external_id__v": "VPR-3330",
    "therapeutic_area__vs": "psychiatry__vs",
    "manufacturer_name__v": "Veeva Labs",
    "regions__c": "north_america__c,south_america__c"
}
]

Download Input File

Updating Object Record Roles

When Dynamic Security (Custom Sharing Rules) is configured on an object, you can add or remove users and groups on manually assigned roles on up to 500 object records at a time. This is available in API v11.0 or later.

Learn more about Dynamic Security (Custom Sharing Rules):

Input

The following fields are allowed:

id - [Required] The object record id field value.
owner__v.users - Optional
owner__v.groups - Optional
editor__v.users - Optional
editor__v.groups - Optional
viewer__v.users - Optional
viewer__v.groups - Optional

You can assign one or more users or groups to each role. To do so, include a comma-separated list of user or group id field values.

This action is not additive. That is, if other users and groups are already assigned to a role, they will be overwritten by those in the input.

Note that only a user in the owner role can assign other users or groups to the owner role.

JSON Input Example:

[
{
    "id": "00PR0202",
    "owner__v.users": "12022",
    "editor__v.users": "60145,70012,89546",
    "editor__v.groups": "4411606",
    "viewer__v.users": "35551,48948,55002",
    "viewer__v.groups": "3311303"   
}
]

Example Request (JSON Input)

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/json" \
--data-binary @"C:\Vault\Object Records\update_object_record_users_groups.json" \
https://myvault.veevavault.com/api/v11.0/vobjects/product__v

Example Response (JSON)

{
    "responseStatus": "SUCCESS",
    "data": [
        {
        "id": "00PR0202",
        "url": "api/v11.0/vobjects/product__v/00PR0202"
        }
    ]
}

Errors

Error Type Error Message Description
INSUFFICIENT_ACCESS User does not have sufficient privileges to perform the action. Vault restricts some users from changing role assignments (learn more). Note that only users who are in the owner role can add or remove other owners.
INVALID_DATA Invalid value(s) [{list of invalid IDs}] specified for parameter [{role name}] : user IDs do not resolve to a valid active [user] objects. The user IDs included in the input could not be found in your vault. Only active users can be assigned to the roles.
INVALID_DATA Invalid value(s) [{list of invalid IDs}] specified for parameter [{role name}] : group IDs do not resolve to a valid active [group] objects. The group IDs included in the input could not be found in your vault. Only active groups can be assigned to the roles.

History

Since v11

Top

JSON: Delete Object Records

  • Supported in the Bulk API: YES (See request)
  • Supported in Vault Loader: YES (CSV input only)
  • Other supported input formats: CSV (See input)

Referencing Existing Object Records

When deleting object records, you can use one of two standard document ID fields in the input:

  • id - System-assigned object record ID. This numeric field value exists on all object records. It is non-editable. This can be used with the Bulk API and Vault Loader.
  • external_id__v - User-defined document external ID. This alphanumeric field is not always configured with values. It is editable. This can be used with the Bulk API only.

By default, Vault looks for the id field in the input. To use external_id__v instead, add the idParam=external_id__v parameter to the request endpoint.

Example Inputs

Using the document id field:

[
{
    "id": "00P1110",
},
{
    "id": "00P2220",
},
{
    "id": "00P3330"
}
]

Using the document external_id__v field:

[
{
    "id": "CHO-1110",
},
{
    "id": "NYA-2220",
},
{
    "id": "VPR-3330"
}
]

Top

JSON: Create Users

  • Supported in the Bulk API: YES (See request)
  • Supported in Vault Loader: YES (CSV input only)
  • Other supported input formats: CSV (See input)

Example Input

[
{
    "user_name__v": "ally@veevapharm.com",
    "user_first_name__v": "Ally",
    "user_last_name__v": "Abernathy",
    "user_email__v": "ally@veevapharm.com",    
    "user_timezone__v": "America/Denver",
    "user_locale__v": "en_US",
    "user_language__v": "en",
    "security_policy_id__v": "821",
    "file": "images/ally.jpg"    
},
{
    "user_name__v": "beth@veevapharm.com",
    "user_first_name__v": "Beth",
    "user_last_name__v": "Benedict",
    "user_email__v": "beth@veevapharm.com",    
    "user_timezone__v": "Europe/London",
    "user_locale__v": "en_GB",
    "user_language__v": "en",
    "security_policy_id__v": "821",
    "vault_membership": "3003:true:document_user__v:full__v"
},
{
    "user_name__v": "carl@veevapharm.com",
    "user_first_name__v": "Carl",
    "user_last_name__v": "Connors",
    "user_email__v": "carl@veevapharm.com",    
    "user_timezone__v": "Australia/Sydney",
    "user_locale__v": "en_AU",
    "user_language__v": "en",
    "security_policy_id__v": "554",
    "vault_membership": "3003,4004,5005"
},
{
    "user_name__v": "dean@veevapharm.com",
    "user_first_name__v": "Dean",
    "user_last_name__v": "Donovan",
    "user_email__v": "dean@veevapharm.com",    
    "user_timezone__v": "Asia/Shanghai",
    "user_locale__v": "zh_CN",
    "user_language__v": "zh_CN",
    "security_policy_id__v": "554",
    "vault_membership": "3003:true:document_user__v:full__v,4004:true:system_admin__v:full__v,5005:true:business_admin__v:full__v"      
}
]

See Vault Membership Assignments above for information about assigning users to vaults.

Download Input File

Top

JSON: Update Users

  • Supported in the Bulk API: YES (See request)
  • Supported in Vault Loader: YES (CSV input only)
  • Other supported input formats: CSV (See input)

Required Fields

When updating existing user records, the user id is the only required field in all vaults.

Updating Fields

You can include any editable user field and value in the input.

  • Use the Retrieve User Metadata API to retrieve all fields configured on the users object. In the field specifications: Editable fields: editable:true.
  • Go to Admin > Users & Groups > Users to see users, fields, and values. Learn more.

Example Input

[
{
    "id": "11001",
    "user_title__v": "Senior Product Manager",
    "is_domain_admin__v": true,
    "user_needs_to_change_password__v": true 
},
{
    "id": "11002",
    "mobile_phone__v": "+1 (866) 478-9492",
    "office_phone__v": ""    
},
{
    "id": "11003",
    "active__v": false
},
{
    "id": "11004",
    "vault_membership": "4004:true:system_admin__v:full__v"
}
]

Download Input File

Deactivate User at the Domain Level

Sets the user (id:12022) status to inactive in all vaults within the domain.

[
{
    "id": "12022",
    "domain_active__v": false
}
]

Reactivate User at the Domain Level

Sets the user (id:12022) status to active at the domain-level.

Reactivating at the domain level may not make a user active on every vault. Some users may not be active in any vaults. If the user previously had membership in a given vault, they become active in that vault with their previously assigned license type and security profile. If the user did not have membership in a given vault, they will not have access until you've assigned them.

[
{
    "id": "12022",
    "domain_active__v": true
}
]

Deactivate User at the Vault Level

Sets the user (id:12022) status to inactive in the vault (id:3003).

They will still be active at the domain-level and within other vaults in which they are members.

[
{
    "id": "12022",
    "vault_membership": "3003:false"
}
]

To deactivate the user from more than one vault, format the input as follows:

[
{
    "id": "12022",
    "vault_membership": "3003:false,4004:false"
}
]

Reactivate User at the Vault Level

Sets the user (id:12022) status to active in the vault (id:3003).

They must first be active at the domain level. If using just the vault ID as shown below, the user automatically receives the Full User license type and Document User security profile, even if they had been previously assigned something different in the vault. To assign a different license type and security profile, include them in the input. See Vault Membership Assignments above.

[
{
    "id": "12022",
    "vault_membership": "3003"
}
]

To reactivate the user in more than one vault, format the input as follows:

[
{
    "id": "12022",
    "vault_membership": "3003,4004"
}
]

Top

JSON: Upsert Users

  • Supported in the Bulk API: YES (See request)
  • Supported in Vault Loader: YES (CSV input only)
  • Other supported input formats: CSV (See input)

About the Upsert Action

  • The upsert action combines update and create (insert).
  • If a matching user record is found in your vault, it is updated with the field values specified in the input.
  • If no matching user record is found, a new user is created using values in the input.

Example Input

[
{
    "user_name__v": "ally@veevapharm.com",
    "user_first_name__v": "Ally",
    "user_last_name__v": "Abernathy",
    "user_email__v": "ally@veevapharm.com",    
    "user_timezone__v": "America/Denver",
    "user_locale__v": "en_US",
    "user_language__v": "en",
    "security_policy_id__v": "821",
    "file": "images/ally.jpg"
},
{
    "user_name__v": "beth@veevapharm.com",
    "user_first_name__v": "Beth",
    "user_last_name__v": "Benedict",
    "user_email__v": "beth@veevapharm.com",    
    "user_timezone__v": "Europe/London",
    "user_locale__v": "en_GB",
    "user_language__v": "en",
    "security_policy_id__v": "821",
    "file": "images/beth.jpg"
},
{
    "id": "11004",  
    "user_name__v": "carl@veevapharm.com",
    "user_first_name__v": "Carl",
    "user_last_name__v": "Connors",
    "user_email__v": "carl@veevapharm.com",    
    "user_timezone__v": "Australia/Sydney",
    "user_locale__v": "en_AU",
    "user_language__v": "en",
    "security_policy_id__v": "554"
},
{
    "id": "11006",  
    "user_name__v": "dean@veevapharm.com",
    "user_first_name__v": "Dean",
    "user_last_name__v": "Donovan",
    "user_email__v": "igor@veevapharm.com",    
    "user_timezone__v": "Asia/Shanghai",
    "user_locale__v": "zh_CN",
    "user_language__v": "zh_CN",
    "security_policy_id__v": "554"
},
{
    "id": "11005",
    "user_title__v": "Senior Product Manager",
    "mobile_phone__v": "+1 (925) 452-6500",
    "office_phone__v": 
},
{
    "id": "11006",
    "user_title__v": "Director, Product Management",
    "mobile_phone__v": "+1 (866) 478-9492"
}
]

Example Input

[
{
    "user_name__v": "ally@veevapharm.com",
    "user_title__v": "Senior Product Manager",
    "is_domain_admin__v": true,
    "user_needs_to_change_password__v": true 
},
{
    "user_name__v": "steve@veevapharm.com",
    "mobile_phone__v": "+1 (866) 478-9492",
    "office_phone__v": ""    
},
{
    "user_name__v": "carl@veevapharm.com",
    "active__v": false
},
{
    "user_name__v": "dean@veevapharm.com",
    "vault_membership": "3003,4004,5005"
}
]

Top

Name-Value Pair: Update Documents

  • Supported in the Bulk API: YES (See request)
  • Supported in Vault Loader: NO
  • Other supported input formats: CSV (See input)

Using Name-Value Pair Inputs

When formatting the input data as name-value pairs, you can pass the list of document IDs in the request parameter docIds.

Updating Fields

You can include any editable object field and value in the input.

Example Request

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "docIds=771,772" \
-d "product__v=0PR0101" \
-d "counry__v:0CR0011" \
-d "language__v=English" \
-d "audience__vs=Consumer" \
https://myvault.veevavault.com/api/v12.0/objects/documents/batch

This example includes:

  • The document id field name and the system-managed values of each document being updated.
  • The editable product__v and country__v document field. When associating documents with objects, you must use the object record id.
  • The editable language__v and audience__vs document field and values.

Example JSON Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "id": 211
        },
        {
            "responseStatus": "SUCCESS",
            "id": 212
        {
            "responseStatus": "SUCCESS",
            "id": 213
        },
        {
            "responseStatus": "SUCCESS",
            "id": 214
        },        
        {
            "responseStatus": "SUCCESS",
            "id": 215
        }                
    ]
}

Top

Name-Value Pair: Assign Users & Groups to Document Roles

  • Supported in the Bulk API: YES (See request)
  • Supported in Vault Loader: NO
  • Other supported input formats: CSV (See input)

Using Name-Value Pair Inputs

  • When formatting the input data as name-value pairs, you can pass the list of document IDs in the request parameter docIds.
  • Separate multiple document, user, and group field values with commas.
  • Learn more about updating document roles above.

Example Request

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

Example JSON Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "id": 771,
            "reviewer__v.users": [
                12021,
                12022
            ],
            "reviewer__v.groups": [
                3311303,
                3311404
            ],
            "approver.users": [
                22124
            ],
            "approver__v.groups": [
                4411606
            ]           
        },
        {
            "responseStatus": "SUCCESS",
            "id": 772,
            "reviewer__v.users": [
                12021,
                12022
            ],
            "reviewer__v.groups": [
                3311303,
                3311404
            ],
            "approver.users": [
                22124
            ],
            "approver__v.groups": [
                4411606
            ]   
        }
    ]
}

Top

Name-Value Pair: Remove Users & Groups from Document Roles

  • Supported in the Bulk API: YES (See request)
  • Supported in Vault Loader: NO
  • Other supported input formats: CSV (See input)

Using Name-Value Pair Inputs

  • When formatting the input data as name-value pairs, you can pass the list of document IDs in the request parameter docIds.
  • Separate multiple document, user, and group field values with commas.
  • Learn more about updating document roles above.

Example Request

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
-d "docIds=771,772" \
-d "reviewer__v.users=12021,12022" \
-d "reviewer__v.groups=3311303,3311404" \
-d "approver__v.users=22124" \ 
-d "approver__v.groups=4411606" \
https://myvault.veevavault.com/api/v12.0/objects/documents/roles/batch

Example JSON Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS",
            "id": 771,
            "reviewer__v.users": [
                12021,
                12022
            ],
            "reviewer__v.groups": [
                3311303,
                3311404
            ],
            "approver.users": [
                22124
            ],
            "approver__v.groups": [
                4411606
            ]           
        },
        {
            "responseStatus": "SUCCESS",
            "id": 772,
            "reviewer__v.users": [
                12021,
                12022
            ],
            "reviewer__v.groups": [
                3311303,
                3311404
            ],
            "approver.users": [
                22124
            ],
            "approver__v.groups": [
                4411606
            ]   
        }
    ]
}

Top