**Source URL:** https://limited.veevavault.dev/medical/vault-api/api-reference/23.1/documents/document-tokens.md

# Document Tokens



The Vault Document Tokens API allows you to generate document access tokens needed by the external viewer to view documents outside of Vault. [Learn more.](/commercial/library/guides/external-document-viewer)

<Endpoint path="/api/{version}/objects/documents/tokens" method="POST"></Endpoint>

## Headers {#headers}

<FieldTable>
| Name | Description |
| --- | --- |
| `Content-Type` | `application/x-www-form-urlencoded` |
| `Accept` | `application/json` (default) or `application/xml` |
</FieldTable>

## Body Parameters {#body-parameters}

<FieldTable>
| Name | Description |
| --- | --- |
| `docIds` | Include the `docIds` request parameter with a comma-separated string of document `id` values. This will generate tokens for each document. For example: `docIds=101,102,103,104` |
| `expiryDateOffset` | Include the `expiryDateOffset` request parameter set to the number of days after which the tokens will expire and the documents will no longer be available in the viewer. If not specified, the tokens will expire after 10 years by default. |
| `downloadOption` | Include the `downloadOption` request parameter set to `PDF`, `source`, `both`, or `none`. These allow users viewing the document to be able to download a PDF version or source version (Word, PowerPoint, etc.) of the document. If not specified, the download options default to those set on each document. |
| `channel` | Include the `channel` request parameter set to the website object record `id` value that corresponds to the distribution channel where the document is being made available. If no website record is specified, Vault will assume the request is for Approved Email. |
| `tokenGroup` | Include the `tokenGroup` request parameter to group together generated tokens for multiple documents in order to display the documents being referenced in the same viewer. This value accepts strings of alphanumeric characters (a-z, A-Z, 0-9, and single consecutive underscores) up to 255 characters in length. The token that is passed as a URL parameter to the External Viewer is the primary token and the document it references will be displayed normally. However, any additional documents that have tokens generated with the same case-sensitive `tokenGroup` string will be displayed in a sidebar of the viewer. The order of documents in the sidebar depends on the order in which the tokens are generated. If multiple tokens are generated with one request, the documents will be ordered top-to-bottom based on the order they are passed to the `docIds` parameter. For example: If passing the parameters `docIds=101,102,103,104` and `tokenGroup=group_1` with the request, the top-to-bottom order in the sidebar will be documents 101, 102, 103, 104. If a new request is then made with the parameters `docIds=105` and `tokenGroup=group_1`, document 105 will be added below document 104 in the previous list. |
| `steadyState` | If set to `true`, Vault generates a token for the latest steady state version of a document. If you do not have *View* permission, or if a steady-state version does not exist, Vault returns an `INVALID_STATE` error. If omitted, the default value is `false`, and Vault generates a token for the latest version, regardless of state. |
</FieldTable>

## Request {#request}

<CodeExample title="">
```
curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "docIds=101,102,103,104" \
-d "expiryDateOffset=90" \
-d "downloadOption=PDF" \
-d "channel=00W000000000301" \
https://myvault.veevavault.com/api/v15.0/objects/documents/tokens

```
</CodeExample>

## Response {#response}

<CodeExample title="">
```
{
    "responseStatus": "SUCCESS",
    "tokens": [
        {
            "document_id__v": 101,
            "token__v": "3003-cb6e5c3b-4df9-411c-abc2-6e7ae120ede7"
        }
        {
            "document_id__v": 102,
            "token__v": "3003-1174154c-ac8e-4eb9-b453-2855de273bec"
        },
        {
            "document_id__v": 103,
            "token__v": "3003-51ca652c-36d9-425f-894f-fc2f42601fa9"
        },
        {
            "document_id__v": 104,
            "errorType": "OPERATION_NOT_ALLOWED",
            "errors": [
                {
                    "type": "INVALID_DOCUMENT",
                    "message": "Document not found [104]."
                }
            ]
        }
    ]
}

```
</CodeExample>

## Response Details {#response-details}

In the example above, tokens are generated for the first three documents. The fourth document could not be found. This indicates either an incorrect document `id` or that the specified document is a binder.



---

**Previous:** [Delete Basic Document Template](/medical/vault-api/api-reference/23.1/documents/document-templates/delete-basic-document-template)  
**Next:** [Binders](/medical/vault-api/api-reference/23.1/binders)