**Source URL:** https://general.veevavault.dev/medical/vault-api/guides/postman-collection/sending-requests.md

# Sending Requests to Vault API

Once you’ve successfully authenticated to your Vault, you can send requests to Vault API. To send a request to a particular endpoint, navigate to that endpoint within the nested folders of the Vault Platform Postman Collection. To help you navigate, the Vault API Reference and Vault Platform Postman Collection endpoints share the same hierarchy. For example, if you'd like to retrieve all supported versions of Vault API, navigate to **Authentication > Retrieve API Versions**, as you would in the Vault API Reference.

<ThemeImage srcLight="/images/api/postman/25r2_postman_collection_send_request_light.png" srcDark="/images/api/postman/25r2_postman_collection_send_request_dark.png" alt="Request to retrieve API versions"></ThemeImage>
In the righthand sidebar, you can select the **Documentation** (<Icon name="ph:file-text-light"></Icon>) icon to access the documentation for the endpoint or select the **Code** (<Icon name="ph:code-light"></Icon>) icon to access the code snippet of the request. Within the workbench are the following relevant tabs: *Params*, *Headers*, and *Body*.

At the top of the workbench, Postman displays the method (`GET`, `POST`, `PUT`, or `DELETE`) and the request URL. Alongside the URL box is the *Send* button. After ensuring that the request has all the required parameters to execute successfully, click the **Send** button to send a call to Vault API.

The following subsections outline how to work with headers, populate key-value pairs for parameters, download files, interpret the response, and store history.

## Working with Request Headers {#working-with-request-headers}

Headers, such as `Accept` and `Content-Type`, usually serve as additional metadata for a request. Within the Vault Platform Postman Collection, each endpoint is preconfigured with default header values.

<ThemeImage srcLight="/images/api/postman/25r2_postman_collection_headers_light.png" srcDark="/images/api/postman/25r2_postman_collection_headers_dark.png" alt="Request headers"></ThemeImage>
To view the headers for a particular endpoint, navigate to the *Headers* tab. To omit a header, select the checkmark next to the header's name. To include a header, select the empty checkbox next to the header's name. To modify the value of a header, click into its box underneath the *Value* column.

## Populating Parameters {#populating-parameters}

Some endpoints in the Vault Platform Postman Collection give you the option to populate parameters before sending a request to Vault API. Depending on the endpoint, there may be query, path, or body parameters, whose values can influence the information returned in the response.

### Query Parameters {#query-parameters}

Query parameters are often optional and usually help to filter requests to return more precise results. Query params are key-value pairs appended to the end of the request URL following a `?` and separated by a `&`. If a query parameter is omitted from a request, it may default to a particular value. Within the Vault Platform Postman Collection, each endpoint that has one or more query parameters is preconfigured with key-value pairs, with the parameter itself omitted by default from the request.

<ThemeImage srcLight="/images/api/postman/25r2_postman_collection_query_parameters_light.png" srcDark="/images/api/postman/25r2_postman_collection_query_parameters_dark.png" alt="Query parameters"></ThemeImage>
For example, the [Create Single Document Version](/vault-api/api-reference/26.1/documents/update-documents/create-single-document-version) endpoint includes a query parameter called `suppressRendition`. If you wanted to suppress automatic generation of the viewable rendition for a new draft version of an existing document, you would include this parameter by selecting the empty checkbox and provide a value of `true` for the query parameter. Postman then automatically modifies the request URL to appear as follows:

`https://{{vaultDNS}}/api/{{version}}/objects/documents/:{doc_id}?suppressRendition=true`

If omitted, this value would default to `false` and Postman would exclude the query parameter from the request URL.

### Path Parameters {#path-parameters}

Path parameters are a part of the request URL, preceded by a colon and sometimes surrounded by curly braces (`{}`). They typically communicate pertinent information that does not need to be within the body of the request. Within the Vault Platform Postman Collection, if an endpoint requires path parameters, they appear underneath the *Path Variables* section in the *Params* tab. If an endpoint does not require path parameters, this section is not visible.

<ThemeImage srcLight="/images/api/postman/25r2_postman_collection_path_parameters_light.png" srcDark="/images/api/postman/25r2_postman_collection_path_parameters_dark.png" alt="Path parameters"></ThemeImage>
For example, the [Retrieve Object Metadata](/vault-api/api-reference/26.1/vault-objects/retrieve-object-metadata) endpoint has a path parameter called `object_name`. If you wanted to retrieve the object metadata for the object, `product__v`, you would populate this value by clicking into its box underneath the *Value* column. This path parameter is visible within the request URL in Postman as follows:

`https://{{vaultDNS}}/api/{{version}}/metadata/vobjects/:object_name`

You cannot omit path parameters in Postman and the request is likely to fail if you do not provide a value.

### Body Parameters {#body-parameters}

Body parameters are sent along with the request in order to add or update data in your Vault. Within the Vault Platform Postman Collection, if an endpoint has body parameters, they appear underneath the *Body* tab. Each endpoint that has one or more body parameters is preconfigured with a key and a description. Any optional body parameters are omitted by default from the request while required body parameters are included by default.

<ThemeImage srcLight="/images/api/postman/25r2_postman_collection_body_parameters_light.png" srcDark="/images/api/postman/25r2_postman_collection_body_parameters_dark.png" alt="Body parameters"></ThemeImage>
For example, the [Submitting a Query](/vault-api/api-reference/26.1/vault-query-language-vql/submitting-a-query) endpoint has a single required body parameter, `q`. If you wanted to retrieve the name and ID of all `person__sys` records, you would populate the value of the `q` body parameter with the following VQL query: `SELECT id, name__v FROM person__sys`.

## Downloading Files {#downloading-files}

Some endpoints, such as [Download Direct Data File](/vault-api/api-reference/26.1/direct-data/download-direct-data-file), allow you to download files from your Vault's file staging to your local machine. To do so, instead of clicking **Send**, click the drop-down arrow and select **Send and Download**, as shown below.

<ThemeImage srcLight="/images/api/postman/25r2_postman_collection_download_light.png" srcDark="/images/api/postman/25r2_postman_collection_download_dark.png" alt="Downloading files from Postman"></ThemeImage>
If the request is successful, you may be prompted in a pop-up window to "Select path to save file." When naming the local file, we advise naming it according to the filename indicated within the `Content-Disposition` HTTP Response Header. You can obtain this value from the *Headers* tab in the lower pane.

## Viewing the Response {#viewing-the-response}

The *Body* tab of the lower pane on the workbench displays the response returned by Vault API. On `SUCCESS`, the response includes the desired information by default in JSON format. On `FAILURE`, the response typically includes an error message in JSON format. To change the format of the response, click the drop-down arrow next to the current format. To interpret the response, refer to the information contained in the *Response Details* section for the endpoint in the Vault API Reference.

<ThemeImage srcLight="/images/api/postman/25r2_postman_collection_save_response_light.png" srcDark="/images/api/postman/25r2_postman_collection_save_response_dark.png" alt="Saving responses"></ThemeImage>
To save a particular request response, click **Save Response** from the upper righthand corner of the lower pane. A tab will open, upon which you can provide a name for the response. Upon saving, this response is nested underneath the corresponding endpoint within the collection. If a response is not saved, it cannot be referenced in the future or shared with collaborators. To have Postman save all responses by default, see [how to store history](/vault-api/guides/postman-collection/sending-requests/#Storing_History).

### Viewing Response Headers {#viewing-response-headers}

The *Headers* tab of the lower pane on the workbench displays each response header returned by Vault API. These headers contain various metrics to aid developers in monitoring performance, limits, and more. There are standard response headers returned for all calls to Vault API while any additional headers may vary based on the request. Learn more about [response headers](/vault-api/references/response-headers).

<ThemeImage srcLight="/images/api/postman/25r2_postman_collection_response_headers_light.png" srcDark="/images/api/postman/25r2_postman_collection_response_headers_dark.png" alt="Viewing response headers"></ThemeImage>
For example, if you need to access the unique ID associated with your request, you can obtain this value from the `X-VaultAPI-ExecutionId` response header. This value may be useful to provide in Veeva Support tickets regarding Vault API. The `X-VaultAPI-VaultId` response header returns the currently authenticated Vault's ID.

### Storing History {#storing-history}

You can access previous requests from the *History* (<Icon name="ph:clock-counter-clockwise-light"></Icon>) tab in the lefthand sidebar. Each request is listed in chronological order, starting with the most recent request. Postman saves these requests automatically, however, the responses are not saved by default.

From the **View more actions** (<Icon name="ph:dots-three-outline-light"></Icon>) menu of the *History* tab, you can choose to **Clear all** saved requests or enable the option to **Save Responses** by default in order to retain response details for future reference. Learn more about accessing and managing history in the [Postman Docs](https://learning.postman.com/docs/getting-started/basics/navigating-postman/#history).



---

**Previous:** [Authenticating to your Vault](/medical/vault-api/guides/postman-collection/authenticating-vault)  
**Next:** [File Staging](/medical/vault-api/guides/file-staging)