--- agentTools: projectIndex: https://financial-cloud.readme.io/llms.txt --- # Download document Downloads a specific document associated with the provided UUID. This UUID represents a document which could be of type **FCCORE_attachment**, **FCCORE_emailSent**, **FCCORE_letterSent**, **FCCORE_smsSent** or **DASHBOARD_email**. For S3-backed documents, the default behaviour is an HTTP `302` redirect to a signed S3 URL. Set `mode=url` to return the signed URL in a `200` JSON response instead. **FCCORE_smsSent** documents return `200 text/plain` because SMS content is stored as text rather than an S3 file. Set `parser=email` for supported inbound dashboard emails to return rendered `200 text/html` content instead of a signed URL or redirect. # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "title": "Documents", "version": "0.6.0", "description": "The Documents API manages customer and account document access.\n\nIt supports uploading **FCCORE_attachment** documents to either a customer or a specific customer account. Uploaded documents are added through a signed S3 URL flow.\n\nIt also supports listing and downloading existing documents from these document sources:\n\n* FCCORE_attachment\n* FCCORE_emailSent\n* FCCORE_letterSent\n* FCCORE_smsSent\n* DASHBOARD_email\n\nOnly **FCCORE_attachment** documents can currently be uploaded, updated, or deleted through this API." }, "tags": [ { "name": "UUID", "description": "Document specific operations" } ], "servers": [ { "url": "http://localhost:{port}", "description": "Local API endpoint", "variables": { "port": { "default": "8080", "description": "Local port" } } }, { "url": "https://api.{systemName}.financial-cloud.co.uk/documents", "description": "Deployed API endpoint", "variables": { "systemName": { "default": "your-system-name", "description": "Replace with your assigned system name" } } } ], "paths": { "/{UUID}": { "get": { "summary": "Download document", "description": "Downloads a specific document associated with the provided UUID. This UUID represents a document which could be of type **FCCORE_attachment**, **FCCORE_emailSent**, **FCCORE_letterSent**, **FCCORE_smsSent** or **DASHBOARD_email**.\n\nFor S3-backed documents, the default behaviour is an HTTP `302` redirect to a signed S3 URL. Set `mode=url` to return the signed URL in a `200` JSON response instead. **FCCORE_smsSent** documents return `200 text/plain` because SMS content is stored as text rather than an S3 file.\n\nSet `parser=email` for supported inbound dashboard emails to return rendered `200 text/html` content instead of a signed URL or redirect.", "operationId": "document_download", "tags": [ "UUID" ], "parameters": [ { "in": "path", "required": true, "schema": { "title": "UUID", "type": "string", "example": "5b974554-326b-40a8-beab-84a51b0cd60c" }, "name": "UUID", "description": "This is a required string parameter provided in the path. It represents the unique identifier of the document that needs to be downloaded." }, { "in": "query", "schema": { "title": "mode", "type": "string", "example": "redirect", "enum": [ "redirect", "url" ] }, "name": "mode", "description": "Optional response mode for S3-backed documents. The default is **redirect**, which returns `302` with a signed S3 URL in the `Location` header. Use **url** to return `200 application/json` containing the signed URL." }, { "in": "query", "schema": { "title": "parser", "type": "string", "example": "email", "enum": [ "email" ] }, "name": "parser", "description": "This is an optional query parameter that, when set to **email**, will render an email document into HTML rather than returning the raw email file. This parameter is useful when the UUID refers to a **DASHBOARD_email**." } ], "responses": { "200": { "description": "Successful response when `mode=url`, when downloading SMS text, or when rendering supported email content with `parser=email`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DownloadURL" }, "example": { "url": "https://company.s3.eu-west-1.amazonaws.com/attachments/68d33aea-8e2c-4789-8232-85f15a0f4a98/1652866418380-example.pdf?AWSAccessKeyId=AXXXXXXXXXXXXXXXXXXX&Expires=1655986157&Signature=%2BBejt%2BHgfbFqRZI2I6ZBR8adpYk%3D" } }, "text/plain": { "schema": { "type": "string" }, "examples": { "smsText": { "summary": "FCCORE_smsSent text response", "value": "Your payment is due on 2026-02-28" } } }, "text/html": { "schema": { "type": "string" }, "examples": { "parsedEmail": { "summary": "DASHBOARD_email parsed with parser=email", "value": "..." } } } } }, "302": { "description": "Redirect to signed S3 URL when mode=redirect (default)", "headers": { "Location": { "description": "Signed S3 URL for download", "schema": { "type": "string", "format": "uri" } } } }, "400": { "description": "Unsupported properties", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericMessage" }, "example": { "message": "this document cannot be downloaded" } } } }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericMessage" }, "example": { "message": "Document not found" } } } } } } } }, "components": { "securitySchemes": { "OAuthUserHeader": { "type": "apiKey", "in": "header", "name": "x-oauth-user", "description": "Authenticated OAuth user context. Access to this API requires an account with the `documents:upload` role." } }, "responses": { "ForbiddenError": { "description": "User is missing the required `documents:upload` role.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericMessage" }, { "properties": { "error": { "type": "boolean" } } } ] }, "examples": { "missingRequiredRole": { "summary": "Missing required role", "value": { "error": true, "message": "Not Authorised user: {username} lacked one of these roles documents:upload" } } } } } } }, "schemas": { "GenericMessage": { "title": "Generic Message", "description": "A message", "required": [ "message" ], "type": "object", "properties": { "message": { "title": "Message", "type": "string", "example": "This is a generic message" } } }, "DownloadURL": { "title": "Download URL", "description": "This object contains a URL that will allow the document to be downloaded", "required": [ "url" ], "type": "object", "properties": { "url": { "title": "URL", "type": "string", "example": "https://company.s3.eu-west-1.amazonaws.com/attachments/68d33aea-8e2c-4789-8232-85f15a0f4a98/1652866418380-example.pdf?AWSAccessKeyId=AXXXXXXXXXXXXXXXXXXX&Expires=1655986157&Signature=%2BBejt%2BHgfbFqRZI2I6ZBR8adpYk%3D" } } } } }, "security": [ { "OAuthUserHeader": [] } ], "x-readme": { "explorer-enabled": true, "proxy-enabled": true }, "_id": { "buffer": { "0": 101, "1": 113, "2": 172, "3": 13, "4": 228, "5": 246, "6": 77, "7": 0, "8": 49, "9": 131, "10": 36, "11": 169 } } } ```