Download
This endpoint is used to directly download a document based on the unique identifier.
By default, the document is streamed as a direct download. Optionally, by passing ?mode=url, the endpoint returns a short-lived signed URL instead.
Definition
Route: /documents/{document_id}/download
Method: GET
OperationId: document
Permissions
The user must be a member of one of the following groups to download a document:
- documents:manager
- documents:viewer
Request
Headers
| Name | Description | Notes |
|---|---|---|
| accept | The expected format of the response | application/octet-stream |
| osg-client-id | The unique identifier assigned to your organization | |
| client_customer_id | The unique identifier assigned to your client | |
| correlation_id | The unique identifier for correlation |
Parameters
| Name | Type | Description |
|---|---|---|
| document_id | string | The unique identifier of the document |
Query Parameters
| Name | Type | Description |
|---|---|---|
| mode | string | Optional. When set to url, the endpoint returns a short-lived signed URL instead of streaming the document. If omitted, the document is streamed as a direct download. |
Tip
When retrieving a document that was generated using SendCommunication the DocumentId is the same as the CommunicationId.
Responses
Success (Direct Download)
Returned when mode is not specified. The document is streamed with Content-Disposition: attachment.
Headers
| Key | Value | Type | Description |
|---|---|---|---|
| content-disposition | attachment; filename={filename} | FileStream | |
| content-type | {mimeType} | string |
| Status | Description | Body |
|---|---|---|
| 200 | The request was successful. | FileStream |
Success (URL Mode)
Returned when mode=url is specified. The endpoint returns a JSON body containing a short-lived, scoped signed URL that provides access to the requested document only. When accessed, the signed URL sets Content-Disposition: attachment.
Headers
| Key | Value | Type | Description |
|---|---|---|---|
| content-type | application/json |
string |
| Status | Description | Body |
|---|---|---|
| 200 | The request was successful. | JSON object |
Response Body
| Field | Type | Description |
|---|---|---|
| documentId | string | The unique identifier of the document. |
| downloadUrl | string | The short-lived, scoped signed URL. |
| expiresAt | string | The UTC timestamp at which the URL expires. |
{
"documentId": "a1b2c3d4-0000-0000-0000-000000000000",
"downloadUrl": "https://...",
"expiresAt": "2025-01-01T12:05:00Z"
}
The signed URL expires 5 minutes after it is issued.
Failures
| Status | Description | Body |
|---|---|---|
| 400 | The request was invalid. | None |
| 401 | The request was not authorized. | None |
| 403 | The request was not allowed. | None |
| 404 | The document was not found. | None |
| 410 | The signed URL has expired. | JSON error |
| 500 | An unexpected error occurred. | None |
The 410 Gone response applies when a consumer attempts to access an expired signed URL, and returns a JSON error body indicating the URL has expired.
Notes
- Signed URL generation inherits the existing rate limits applied to the
/downloadendpoint. No separate rate limit is introduced. - Audit logging distinguishes URL-based download (
download-url) from direct download as separate event types.