Authentication

To make API calls against Vault, you must include a sessionID header. To get a sessionID, you need a Vault user account with API access. Learn how to Authenticate and get a sessionId in the REST API Reference.

Execute MDL Script

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
--data-binary @"mdl.txt"
https://myvault.veevavault.com/api/mdl/execute

Example Body: RECREATE Picklist

RECREATE Picklist color__c (
   label('Color'),
   active(true),
   Picklistentry red__c(
      value('Red'),
      order(1),
      active(true)
   ),
   Picklistentry blue__c(
      value('Blue'),
      order(2),
      active(true)
   ),
   Picklistentry green__c(
      value('Green'),
      order(3),
      active(true)
   )
);

Example Body: RECREATE Java SDK Trigger

RECREATE Recordtrigger my_custom_trigger_name__c (
active (true),
source_code (<VeevaData>
...
</VeevaData>)
);

Response: RECREATE Picklist

{
    "responseStatus": "SUCCESS",
    "script_execution": {
        "code": "GEN-S-0",
        "message": "OK",
        "warnings": 0,
        "failures": 0,
        "exceptions": 0,
        "components_affected": 1,
        "execution_time": 0.028
    },
    "statement_execution": [
        {
            "vault": "promo-vee.vaultdev.com",
            "statement": 1,
            "command": "RECREATE",
            "component": "Picklist.color__c",
            "message": "[SUCCESS] RECREATE Picklist color__c",
            "response": "SUCCESS"
        }
    ]
}


This endpoint executes the given MDL script on a Vault.

POST /api/mdl/execute

Headers

Name Description
Accept application/json (default) or application/xml

Body Parameters

The body of the request should contain the MDL script to execute. Enter the body as raw data. The body must start with one of the following values:

Learn more in the MDL Commands documentation.

Example Body: RECREATE Picklist

In this example, we update our picklists using the RECREATE command. If a picklist exists with the name color__c, Vault updates it to conform to the definition provided. If not, Vault creates a new picklist with the definition provided.

Response Details

On SUCCESS, the response contains details of the execute.

Retrieve Component Types

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v18.3/metadata/components

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "url": "/api/v18.3/metadata/components/Tab",
            "name": "Tab",
            "class": "metadata",
            "abbreviation": "TAB",
            "active": true,
            "label": "Tab",
            "label_plural": "Tab",
            "vobject": "vof_tab_sys"
        },
        {
            "url": "/api/v18.3/metadata/components/Pagelayout",
            "name": "Pagelayout",
            "class": "metadata",
            "abbreviation": "LYT",
            "active": true,
            "label": "Page Layout",
            "label_plural": "Page Layout",
            "vobject": "vof_page_layout"
        },
        {
            "url": "/api/v18.3/metadata/components/Recordtrigger",
            "name": "Recordtrigger",
            "class": "code",
            "label": "Record Trigger",
            "label_plural": "Record Triggers",
            "abbreviation": "RTR",
            "active": true,
            "vobject": "recordtrigger__sys"
        }

    ]
}


Retrieve all component types.

GET /api/{version}/metadata/components

Headers

Name Description
Accept application/json (default) or application/xml

Response Details

On SUCCESS, the response contains metadata for all component types. Metadata returned varies for each component and subcomponent type. See Component Types for more information.

Retrieve Component Type Metadata

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v17.3/metadata/components/Picklist

Response

{
    "responseStatus": "SUCCESS",
    "data": {
        "name": "Picklist",
        "class": "metadata",
        "abbreviation": "PIL",
        "active": true,
        "attributes": [
            {
                "name": "label",
                "type": "String",
                "requiredness": "required",
                "max_length": 40,
                "editable": true,
                "multi_value": false
            },
            {
                "name": "active",
                "type": "Boolean",
                "requiredness": "required",
                "editable": false,
                "multi_value": false
            }
        ],
        "sub_components": [
            {
                "name": "Picklistentry",
                "json_collection_name": "Picklistentry",
                "attributes": [
                    {
                        "name": "value",
                        "type": "String",
                        "requiredness": "required",
                        "max_length": 128,
                        "editable": true,
                        "multi_value": false
                    },
                    {
                        "name": "order",
                        "type": "Number",
                        "requiredness": "required",
                        "max_value": 9223372036854775807,
                        "min_value": 0,
                        "scale": 0,
                        "editable": true,
                        "multi_value": false
                    },
                    {
                        "name": "active",
                        "type": "Boolean",
                        "requiredness": "required",
                        "editable": false,
                        "multi_value": false
                    }
                ]
            }
        ]
    }
}


Retrieve metadata of a specific component type.

GET /api/{version}/metadata/components/{component_type}

Headers

Name Description
Accept application/json (default) or application/xml

Response Details

On SUCCESS, the response contains metadata for the specified component type. Metadata returned varies for each component and subcomponent type. See Component Types for more information.

Retrieve Component Records

Component Record Collection

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v17.3/configuration/Picklist

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "name": "color__c",
            "label": "Color",
            "Picklistentry": [
                {
                    "name": "red__c",
                    "value": "Red",
                    "order": 1,
                    "active": true
                },
                {
                    "name": "blue__c",
                    "value": "Blue",
                    "order": 2,
                    "active": true
                },
                {
                    "name": "green__c",
                    "value": "Green",
                    "order": 3,
                    "active": true
                }
            ],
            "active": true,
            "used_in": []
        }
    ]
}


Retrieve all records for a specific component type.

GET /api/{version}/configuration/{component_type}

Headers

Name Description
Accept application/json (default) or application/xml

Response Details

On SUCCESS, the response contains all component records in the Vault for the specified component type. Each component record returns a minimum of API name and UI label, but most types return more. Complete details of the component can be retrieved using Retrieve Component Record or MDL.

Retrieve Component Record (XML/JSON)

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v17.3/configuration/Picklist.color__c

Response

{
    "responseStatus": "SUCCESS",
    "data": {
        "name": "color__c",
        "label": "Color",
        "Picklistentry": [
            {
                "name": "red__c",
                "value": "Red",
                "order": 1,
                "active": true
            },
            {
                "name": "blue__c",
                "value": "Blue",
                "order": 2,
                "active": true
            },
            {
                "name": "green__c",
                "value": "Green",
                "order": 3,
                "active": true
            }
        ],
        "active": true,
        "used_in": []
    }
}


Retrieve metadata of a specific component record as JSON or XML. To retrieve as MDL, see Retrieve Component Record MDL.

GET /api/{version}/configuration/{component_type}.{record_name}

Headers

Name Description
Accept application/json (default) or application/xml

URI Path Parameters

Name Description
component_type The component type of the record to retrieve metadata.
record_name The name of the record to retrieve metadata. Find this with the Retrieve Component Record Collection endpoint.

Response Details

On SUCCESS, the response contains the complete definition for a specific component record. If a field returns as blank or null, it means the record has no value for that field.

Component Record (MDL)

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/mdl/components/Picklist.color__c

Response

RECREATE Picklist color__c (
   label('Color'),
   active(true),
   Picklistentry red__c(
      value('Red'),
      order(1),
      active(true)
   ),
   Picklistentry blue__c(
      value('Blue'),
      order(2),
      active(true)
   ),
   Picklistentry green__c(
      value('Green'),
      order(3),
      active(true)
   )
);


Retrieve metadata of a specific component record as MDL. To retrieve as JSON or XML, see Retrieve Component Record.

GET /api/mdl/components/{component_type}.{record_name}

Headers

Name Description
Accept application/json (default) or application/xml

URI Path Parameters

Name Description
component_type The component type of the record to retrieve metadata.
record_name The name of the record to retrieve metadata. Find this with the Retrieve Component Record Collection endpoint.

Response Details

On SUCCESS, the response contains a RECREATE MDL statement of metadata for the specified component record. Metadata returned varies based on component type. If a field returns as blank, it means the record currently has no value for that field. Execute this RECREATE with the Execute endpoint.

Components with Content

The following Vault component types contain binary content as part of their definition:

The following endpoints allow you to upload, reference, and migrate the binary content of a file.

Upload Content File

Request 

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: multipart/form-data" \
-F 'file=@C:\Quote.pdf'
https://myvault.veevavault.com/api/mdl/files

Response

{
  "responseStatus": "SUCCESS",
  "data": {
      "name__v": "4be398c32fc2ccf48adaf6ebe53782a1",
      "format__v": "application/pdf",
      "size__v": 4716,
      "sha1_checksum__v": "4be398c32fc2ccf48adaf6ebe53782a1"
         }
    }

This endpoint allows you to upload a content file to be referenced by a component.

Once uploaded, Vault stores the file in a generic files staging area where they will remain until referenced by a component. Once referenced, Vault cannot access the named file from the staging area.

POST /api/files

Headers

Name Description
Content-Type multipart/form-data (default) or application/x-www-form-urlencoded
Accept application/json (default) or application/xml

Response Details

On SUCCESS, the response includes the following:

Name Description
name__v The name of the file which can be used in MDL for referencing the component.
format__v The format of the file.
size__v The file size of the file.
sha1_checksum__v The SHA-1 checksum value generated for the file. Use the checksum to ensure the file was transmitted correctly.

Referencing Files

Example Body: Reference Named File

RECREATE Formattedoutput my_formatted_output__c (
    label(‘My Formatted Output’),
    active(true),
    root_object('Object.product__v'),
    root_object_type('Objecttype.product__v.base__v'),
    output_type('native'),
    template('4be398c32fc2ccf48adaf6ebe53782a1')
);

After uploading a content file, you can reference the file by name using the file or template attributes in your MDL statement. This example uses the template attribute.

To change a component file, you must first upload it and update the component to reference the new file.

Retrieve Content File

Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/mdl/components/Formattedoutput.my_formatted_output__c/files

Response

{
    "responseStatus": "SUCCESS",
    "links": [
        {
            "rel": "my_formatted_output__c.template_file",
            "href": "myvault.veevavault.com/api/mdl/components/Formattedoutput.my_formatted_output__c/files/4be398c32fc2ccf48adaf6ebe53782a1",
            "method": "GET",
            "accept": "application/pdf"
        }
    ],
    "data": [
        {
            "name__v": "4be398c32fc2ccf48adaf6ebe53782a1",
            "original_name__v": "Quote.pdf",
            "format__v": "application/pdf",
            "size__v": 654122,
            "sha1_checksum__v": "4be398c32fc2ccf48adaf6ebe53782a1"
        }
    ]
}

Retrieve the content file of a specified component.

GET /api/mdl/components/{component_type}.{record_name}/files

Headers

Name Description
Accept application/json (default) or application/xml

URI Path Parameters

Name Description
component_type The component type of the record to retrieve content file. For example, Formattedoutput.
record_name The name of the component record. For example, my_formatted_output__c.

Response Details

On SUCCESS, the response includes the following:

Name Description
name__v The name of the file which can be used in MDL for referencing the component.
original_name__v The original name of the uploaded file.
format__v The format of the file.
size__v The file size of the file.
sha1_checksum__v The SHA-1 checksum value generated for the file. Use the checksum to ensure the file was transmitted correctly.