Get File

const fileId = '670e8400-e29b-41d4-a716-446655440000';

const response = await fetch(
  `https://connect.penbox.io/v1/attachments/${fileId}`,
  {
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Accept': 'application/octet-stream'
    }
  }
);

const blob = await response.blob();
// Save or process the file

const fileId = '770e8400-e29b-41d4-a716-446655440000';

const response = await fetch(
  `https://connect.penbox.io/v1/attachments/${fileId}`,
  {
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Accept': 'application/json'
    }
  }
);

const metadata = await response.json();
console.log('Filename:', metadata.name);
console.log('Size:', metadata.metadata.size);
console.log('Type:', metadata.type);

curl -X GET 'https://connect.penbox.io/v1/attachments/670e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Accept: application/octet-stream' \
  --output downloaded-file.pdf

curl -X GET 'https://connect.penbox.io/v1/attachments/770e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Accept: application/json'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "type": "<string>",
  "scope": "<string>",
  "data": "<string>",
  "metadata": {
    "size": 123,
    "width": 123,
    "height": 123
  },
  "uri": "<string>"
}

GET

attachments

{id}

const fileId = '670e8400-e29b-41d4-a716-446655440000';

const response = await fetch(
  `https://connect.penbox.io/v1/attachments/${fileId}`,
  {
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Accept': 'application/octet-stream'
    }
  }
);

const blob = await response.blob();
// Save or process the file

const fileId = '770e8400-e29b-41d4-a716-446655440000';

const response = await fetch(
  `https://connect.penbox.io/v1/attachments/${fileId}`,
  {
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Accept': 'application/json'
    }
  }
);

const metadata = await response.json();
console.log('Filename:', metadata.name);
console.log('Size:', metadata.metadata.size);
console.log('Type:', metadata.type);

curl -X GET 'https://connect.penbox.io/v1/attachments/670e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Accept: application/octet-stream' \
  --output downloaded-file.pdf

curl -X GET 'https://connect.penbox.io/v1/attachments/770e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Accept: application/json'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "type": "<string>",
  "scope": "<string>",
  "data": "<string>",
  "metadata": {
    "size": 123,
    "width": 123,
    "height": 123
  },
  "uri": "<string>"
}

Download or retrieve metadata for a specific file (API: attachment).

In the API, uploaded files are referred to as attachments. This is the technical term used in all endpoints and parameters.

const fileId = '670e8400-e29b-41d4-a716-446655440000';

const response = await fetch(
  `https://connect.penbox.io/v1/attachments/${fileId}`,
  {
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Accept': 'application/octet-stream'
    }
  }
);

const blob = await response.blob();
// Save or process the file

const fileId = '770e8400-e29b-41d4-a716-446655440000';

const response = await fetch(
  `https://connect.penbox.io/v1/attachments/${fileId}`,
  {
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Accept': 'application/json'
    }
  }
);

const metadata = await response.json();
console.log('Filename:', metadata.name);
console.log('Size:', metadata.metadata.size);
console.log('Type:', metadata.type);

curl -X GET 'https://connect.penbox.io/v1/attachments/670e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Accept: application/octet-stream' \
  --output downloaded-file.pdf

curl -X GET 'https://connect.penbox.io/v1/attachments/770e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Accept: application/json'

Response Formats

The endpoint supports two response formats controlled by the Accept header:

Format	Accept Header	Use Case
Binary	`application/octet-stream`	Download the actual file
JSON	`application/json`	Get metadata and Base64 data (for files < 50MB)

JSON Response

When using Accept: application/json, you’ll receive:

{
  "id": "770e8400-e29b-41d4-a716-446655440000",
  "name": "passport.pdf",
  "type": "application/pdf",
  "metadata": {
    "size": 245678,
    "width": null,
    "height": null
  },
  "uri": "https://connect.penbox.io/v1/attachments/770e8400-e29b-41d4-a716-446655440000",
  "data": "JVBERi0xLjQKJeLjz9MKJSVJU0lTIEREREVfUGRmLVY3LjEg..."
}

Field	Type	Description
`id`	string	File UUID
`name`	string	Original filename
`type`	string	MIME type (e.g., `application/pdf`, `image/jpeg`)
`metadata.size`	number	File size in bytes
`metadata.width`	number	Image width in pixels (null for non-images)
`metadata.height`	number	Image height in pixels (null for non-images)
`uri`	string	Direct download URL
`data`	string	Base64-encoded file data (only for files < 50MB)

Files larger than 50MB cannot be retrieved as JSON. Use Accept: application/octet-stream to download large files.

Bulk Download

Download multiple files as a single ZIP archive:

curl -X GET 'https://connect.penbox.io/v1/attachments?ids=id1,id2,id3&filename=documents' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Accept: application/octet-stream' \
  --output documents.zip

Query Parameters

Parameter	Type	Required	Description
`ids`	string	Yes	Comma-separated list of file UUIDs
`filename`	string	No	Custom filename for the downloaded archive

Multiple files are packaged as a ZIP archive for download.

Finding File IDs

File IDs are included when you retrieve a form response:

// Get response with files
const { data, included } = await fetch(
  `https://connect.penbox.io/v1/responses/${responseId}`,
  {
    headers: { 'Authorization': `Bearer ${accessToken}` }
  }
).then(r => r.json());

// Extract file IDs from included resources
const files = included.filter(item => item.type === 'attachments');

for (const file of files) {
  console.log('File ID:', file.id);
  console.log('Filename:', file.attributes.name);
  console.log('Size:', file.attributes.metadata.size);

  // Download the file
  await downloadFile(file.id, accessToken);
}

Supported File Types

Penbox supports various file types:

Category	MIME Types
Documents	`application/pdf`, `application/msword`, `application/vnd.openxmlformats-officedocument.wordprocessingml.document`
Images	`image/jpeg`, `image/png`, `image/gif`, `image/webp`, `image/svg+xml`
Spreadsheets	`application/vnd.ms-excel`, `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`, `text/csv`
Archives	`application/zip`, `application/x-rar-compressed`, `application/x-7z-compressed`
Other	`text/plain`, `application/json`, `application/xml`

Response Codes

Code	Description
`200`	Success - File downloaded or metadata retrieved
`400`	Bad Request - Missing `ids` parameter (for bulk download)
`401`	Unauthorized - Invalid access token
`403`	Forbidden - No access to this file
`404`	Not Found - File doesn’t exist
`413`	Payload Too Large - File too big for JSON response (use octet-stream)
`429`	Too Many Requests - Rate limit exceeded
`500`	Server Error - Internal error

Files are permanently stored and remain accessible even after the form is archived.

For large files (> 50MB), always use Accept: application/octet-stream. The JSON endpoint will return a 413 error for files exceeding this limit.

Downloaded files should be scanned for viruses before processing, especially in production environments.

Authorizations

Authorization

string

header

required

API token (starts with pnbx_). Create at https://app.penbox.io/workspace/settings/api. Include as: Authorization: Bearer {token}

Headers

enum<string>

Response format: application/json for metadata or application/octet-stream for file download

Available options:

application/json,

application/octet-stream

Path Parameters

string<uuid>

required

Attachment UUID

Response

Successful response

string<uuid>

Attachment UUID

name

string

Original filename

type

string

MIME type

scope

string | null

Attachment scope

data

string | null

Base64-encoded file content

metadata

object

Show child attributes

uri

string<uri>

Direct download URL

API Reference

Workspaces

Cases

Case Templates

Forms

Form Templates

Attachments

Document Intelligence

Signatures

Previous API version

Response Formats

JSON Response

Bulk Download

Query Parameters

Finding File IDs

Supported File Types

Response Codes

Authorizations

Headers

Path Parameters

Response

​Response Formats

​JSON Response

​Bulk Download

​Query Parameters

​Finding File IDs

​Supported File Types

​Response Codes

Authorizations

Headers

Path Parameters

Response

Response Formats

JSON Response

Bulk Download

Query Parameters

Finding File IDs

Supported File Types

Response Codes