Get Attachment API

This document details how to use the Attachments API to retrieve (get) attachments. Before proceeding, ensure you have a foundational understanding of document definitions and documents.

To get an attachment on v1 check this documentation.

Core Resource Path

The core path structure for all attachment operations, including retrieval, is:

api/v2/document-definitions/[DDname or DDid]/documents/[documentId or externalId]/attachments

Parameters

These parameters must be updated to correspond to the correct document definition and document:

Parameter	Description
DDname or DDid	Replace with the name or ID of the Document Definition.
documentId or externalId	Replace with the ID or the external ID of the specific Document.

Endpoints

The following endpoint is available for retrieving attachments:

URL	HTTP Method	Description
/attachments?valuePath={valuePath}	GET	Retrieves all attachments from the location in an object. This object also includes the state of succes. The attachments itself will have the general information about the attachments and most importantly the attachment ID.

Using the API Script

You can use the internal REST.call() script to make API calls.

Examples

In here we will take a look at the curl command and also the REST.call functionality.

Example: Getting Attachment URLs using Script Call

This example demonstrates how to use the REST.call() function to retrieve attachment URLs for a specific document at a given valuePath. Note that this example lacks robust error handling.

const ddId = 'your_dd_id'; // Replace with the actual Document Definition ID/name
const documentId = 'your_document_id'; // Replace with the actual Document ID/external ID
const valuePath = 'section.field.attachments'; // Replace with the actual value path
const API_service = 'https_service_api'; // Replace with the correct api location

const getAttachmentsEndpoint = `${API_Service}api/v2/document-definitions/${ddId}/documents/${documentId}/attachments?valuePath=${valuePath}`;
const getAttachmentsMethod = 'GET';
const getAttachmentsHeaders = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN' // Replace with your actual access token
};
const getAttachmentsBody = null; // GET requests typically have no body

REST.call(getAttachmentsEndpoint, getAttachmentsMethod, getAttachmentsHeaders, getAttachmentsBody);

Example: Get Attachment URLs for a Specific Field (cURL)

This example shows how to retrieve the URLs and ID for attachments located at a specific valuePath within a document using curl. Remember to fill in your API domain, IDs, and access token.

curl -X GET "[Main API Domain]/api/v2/document-definitions/YOUR_DD_ID/documents/YOUR_DOCUMENT_ID/attachments?valuePath=YOUR_VALUE_PATH" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
A typical return value looks like this:

Returns a value like this:

{
  "status": "ok",
  "data": [
    {
      "_id": "attachment-uuid-1",
      "downloadURL": "https://yourstorage.com/path/to/attachment1.pdf",
      "_filename": "report.pdf",
      "_type": "image/png",
      "_size": 21,
      "status": 4,
      "uploaded_at": "2023-10-27T11:00:00Z"
    },
    {
      "OBJECT" etc.
    }
  ]
}