Add Attachment to PDF - File Embedding API

PDF4me Add Attachment to PDF enables you to add file attachments to PDF documents, creating comprehensive document packages with embedded files. This API service processes PDF documents and various attachment file types, embedding them directly into PDFs. The API receives source PDF files and attachment files through REST API calls, utilizing Base64 encoding for secure file transmission. With support for multiple file types and batch attachment processing, this solution is ideal for document management systems, enterprise workflows, and business applications that require reliable PDF attachment functionality.

Authenticating Your API Request

To access the PDF4me REST API, every request must include proper authentication credentials. Authentication ensures secure communication and validates your identity as an authorized user of the REST API.

Get your api Key

Key Features

• Multiple File Types: Support for various attachment file formats including text, images, and documents
• Batch Attachments: Add multiple attachments to a single PDF document
• Base64 Encoding: Secure file content transmission using Base64 encoding
• Document Preservation: Maintains original PDF structure while adding attachments
• Flexible Naming: Customize attachment names for better organization
• Professional Packaging: Create comprehensive document packages with embedded resources

REST API Endpoint

The PDF4me REST API uses standard HTTP methods to interact with resources. All attachment addition operations are performed through a single endpoint:

• Method: POST
• Endpoint: /api/v2/AddAttachmentToPdf

REST API Parameters

Complete list of parameters for the Add Attachment to PDF REST API. Parameters are organized by category for better understanding and implementation.

Important: Parameters marked with an asterisk (*) are required and must be provided for the API to function correctly.

Required Parameters

Parameter	Type	Description	Example
docName*	String	Output PDF file name with .pdf extension	output.pdf
docContent*	Base64	The content of the input PDF file encoded in Base64	JVBERi...
attachments*	Array	Array of attachment objects to embed in the PDF. Each object must contain docName (string) and docContent (base64 string)	See example below

Attachment Object Structure

Each item in the attachments array must be an object with the following structure:

Parameter	Type	Description	Example
docName	String	Attachment file name with extension (e.g., .txt, .pdf, .jpg, etc.)	attachment.txt
docContent	Base64	The content of the attachment file encoded in Base64	RXhhbXBsZSBvZiBhdHRhY2htZW50IGZpbGUuIA==

Optional Parameters

Parameter	Type	Description	Example
async	Boolean	Enable asynchronous processing. When true, the API returns a 202 status and provides a polling URL in the Location header	true

Output

The PDF4me Add Attachment to PDF REST API returns different responses based on the processing mode. The API returns the PDF as a Base64-encoded string in JSON format, not as binary data.

Success Response

Synchronous Processing (Default)

When async is not set or set to false, the API processes the request immediately:

Status Code: 200 OK

Content-Type: application/json

Response Body:

{
  "docName": "output.pdf",
  "docContent": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovUGFnZXMgMiAwIFIKPj4KZW5kb2JqCjIgMCBvYmoKPDwKL1R5cGUgL1BhZ2VzCi9LaWRzIFszIDAgUl0KL0NvdW50IDEKPD4KZW5kb2JqCjMgMCBvYmoKPDwKL1R5cGUgL1BhZ2UKL1BhcmVudCAyIDAgUgovTWVkaWFCb3ggWzAgMCA2MTIgNzkyXQovUmVzb3VyY2VzIDw8Ci9Gb250IDw8Ci9GMSA0IDAgUgo+Pgo+PgovQ29udGVudHMgNSAwIFIKPj4KZW5kb2JqCjQgMCBvYmoKPDwKL1R5cGUgL0ZvbnQKL1N1YnR5cGUgL1R5cGUxCi9CYXNlRm9udCAvSGVsdmV0aWNhCj4+CmVuZG9iago1IDAgb2JqCjw8Ci9MZW5ndGggNDQKPj4Kc3RyZWFtCkJUCi9GMSAxMiBUZgoxMDAgNzAwIFRkCihIZWxsbyBXb3JsZCkgVGoKRVQKZW5kc3RyZWFtCmVuZG9iagp4cmVmCjAgNgowMDAwMDAwMDAwIDY1NTM1IGYgCjAwMDAwMDAwMDkgMDAwMDAgbiAKMDAwMDAwMDA1NCAwMDAwMCBuIAowMDAwMDAwMTAxIDAwMDAwIG4gCjAwMDAwMDAxNzAgMDAwMDAgbiAKMDAwMDAwMDI0NCAwMDAwMCBuIAp0cmFpbGVyCjw8Ci9TaXplIDYKL1Jvb3QgMSAwIFIKPj4Kc3RhcnR4cmVmCjM0MQolJUVPRg=="
}

Response Fields:

• docName (string): The output PDF file name
• docContent (string): The PDF file with embedded attachments, encoded as Base64 string

How to Use:

1. Extract the docContent field from the JSON response
2. Decode the Base64 string to get the binary PDF data
3. Save or process the PDF file as needed

Example (JavaScript):

const response = await fetch(url, options);
const data = await response.json();
const pdfBytes = atob(data.docContent); // Decode Base64
// Save or process pdfBytes

Asynchronous Processing

Asynchronous Processing

When async: true is set, the API processes the request asynchronously:

Status Code: 202 Accepted

Response Headers:

Location: https://api.pdf4me.com/api/v2/AddAttachmentToPdf/poll/12345-abcde-67890

Polling Process:

1. Extract the Location header from the 202 response
2. Poll the URL using GET requests
3. Continue polling until you receive a 200 OK status
4. The final response contains the same JSON format with docName and docContent (Base64)

Polling Example:

// Initial request returns 202 with Location header
const response = await fetch(url, options);
const location = response.headers.get('Location');

// Poll until complete
while (true) {
  const pollResponse = await fetch(location, { headers: { 'Authorization': 'Basic ' + apiKey } });
  if (pollResponse.status === 200) {
    const data = await pollResponse.json();
    // Process data.docContent (Base64 PDF)
    break;
  }
  await new Promise(resolve => setTimeout(resolve, 2000)); // Wait 2 seconds
}

Error Responses

Error Responses

The API returns standard HTTP error codes with error details:

400 Bad Request

• Invalid request parameters
• Missing required fields (docName, docContent, attachments)
• Invalid Base64 encoding in docContent or attachment docContent
• Invalid attachment object structure

401 Unauthorized

• Invalid or missing API key
• API key not properly Base64 encoded in Authorization header
• Missing Authorization: Basic header

500 Internal Server Error

• Server-side processing error
• PDF processing failure
• Attachment embedding failure

Error Response Format:

{
  "error": "Error message describing what went wrong"
}

Response Format Details

Response Format Details

Important: The API always returns JSON, never binary PDF data directly.

Response Structure:

{
  "docName": "string",      // Output PDF filename
  "docContent": "string"    // Base64-encoded PDF content
}

Content-Type Header:

• Success: application/json
• The PDF is embedded as a Base64 string within the JSON response

Why Base64?

• JSON-safe encoding for binary data
• Easy to transmit over HTTP
• Compatible with all programming languages
• Can be directly embedded in JSON without escaping issues

Decoding Base64 to PDF:

JavaScript/Node.js:

const base64 = response.docContent;
const binary = atob(base64); // Browser
// OR
const binary = Buffer.from(base64, 'base64').toString('binary'); // Node.js

Python:

import base64
pdf_bytes = base64.b64decode(response['docContent'])
with open('output.pdf', 'wb') as f:
    f.write(pdf_bytes)

C#:

byte[] pdfBytes = Convert.FromBase64String(response.docContent);
File.WriteAllBytes("output.pdf", pdfBytes);

Request Example

Header

Content-Type: application/json
Authorization: Basic YOUR_BASE64_ENCODED_API_KEY

Note:

• Get your API key from the PDF4me Dashboard
• The API key must be Base64 encoded and prefixed with "Basic " in the Authorization header
• Example: If your API key is abc123, encode it to Base64 and use Authorization: Basic YWJjMTIz

Payload

Single Attachment:

{
  "docName": "output.pdf",
  "docContent": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovUGFnZXMgMiAwIFIKPj4KZW5kb2JqCjIgMCBvYmoKPDwKL1R5cGUgL1BhZ2VzCi9LaWRzIFszIDAgUl0KL0NvdW50IDEKPD4KZW5kb2JqCjMgMCBvYmoKPDwKL1R5cGUgL1BhZ2UKL1BhcmVudCAyIDAgUgovTWVkaWFCb3ggWzAgMCA2MTIgNzkyXQovUmVzb3VyY2VzIDw8Ci9Gb250IDw8Ci9GMSA0IDAgUgo+Pgo+PgovQ29udGVudHMgNSAwIFIKPj4KZW5kb2JqCjQgMCBvYmoKPDwKL1R5cGUgL0ZvbnQKL1N1YnR5cGUgL1R5cGUxCi9CYXNlRm9udCAvSGVsdmV0aWNhCj4+CmVuZG9iago1IDAgb2JqCjw8Ci9MZW5ndGggNDQKPj4Kc3RyZWFtCkJUCi9GMSAxMiBUZgoxMDAgNzAwIFRkCihIZWxsbyBXb3JsZCkgVGoKRVQKZW5kc3RyZWFtCmVuZG9iagp4cmVmCjAgNgowMDAwMDAwMDAwIDY1NTM1IGYgCjAwMDAwMDAwMDkgMDAwMDAgbiAKMDAwMDAwMDA1NCAwMDAwMCBuIAowMDAwMDAwMTAxIDAwMDAwIG4gCjAwMDAwMDAxNzAgMDAwMDAgbiAKMDAwMDAwMDI0NCAwMDAwMCBuIAp0cmFpbGVyCjw8Ci9TaXplIDYKL1Jvb3QgMSAwIFIKPj4Kc3RhcnR4cmVmCjM0MQolJUVPRg==",
  "attachments": [
    {
      "docName": "output.txt",
      "docContent": "RXhhbXBsZSBvZiBhdHRhY2htZW50IGZpbGUuIA=="
    }
  ]
}

Multiple Attachments:

{
  "docName": "output.pdf",
  "docContent": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovUGFnZXMgMiAwIFIKPj4KZW5kb2JqCjIgMCBvYmoKPDwKL1R5cGUgL1BhZ2VzCi9LaWRzIFszIDAgUl0KL0NvdW50IDEKPD4KZW5kb2JqCjMgMCBvYmoKPDwKL1R5cGUgL1BhZ2UKL1BhcmVudCAyIDAgUgovTWVkaWFCb3ggWzAgMCA2MTIgNzkyXQovUmVzb3VyY2VzIDw8Ci9Gb250IDw8Ci9GMSA0IDAgUgo+Pgo+PgovQ29udGVudHMgNSAwIFIKPj4KZW5kb2JqCjQgMCBvYmoKPDwKL1R5cGUgL0ZvbnQKL1N1YnR5cGUgL1R5cGUxCi9CYXNlRm9udCAvSGVsdmV0aWNhCj4+CmVuZG9iago1IDAgb2JqCjw8Ci9MZW5ndGggNDQKPj4Kc3RyZWFtCkJUCi9GMSAxMiBUZgoxMDAgNzAwIFRkCihIZWxsbyBXb3JsZCkgVGoKRVQKZW5kc3RyZWFtCmVuZG9iagp4cmVmCjAgNgowMDAwMDAwMDAwIDY1NTM1IGYgCjAwMDAwMDAwMDkgMDAwMDAgbiAKMDAwMDAwMDA1NCAwMDAwMCBuIAowMDAwMDAwMTAxIDAwMDAwIG4gCjAwMDAwMDAxNzAgMDAwMDAgbiAKMDAwMDAwMDI0NCAwMDAwMCBuIAp0cmFpbGVyCjw8Ci9TaXplIDYKL1Jvb3QgMSAwIFIKPj4Kc3RhcnR4cmVmCjM0MQolJUVPRg==",
  "attachments": [
    {
      "docName": "file1.txt",
      "docContent": "RXhhbXBsZSBvZiBhdHRhY2htZW50IGZpbGUuIA=="
    },
    {
      "docName": "file2.pdf",
      "docContent": "JVBERi0xLjQKJeLjz9MK..."
    }
  ],
  "async": true
}

Code Samples

The PDF4me Add Attachment to PDF REST API provides code samples in multiple programming languages. Choose the language that best fits your development environment:

C#

C# (CSharp) Sample

Complete C# implementation for adding attachments to PDF:

View C# Sample

Java

Java Sample

Java implementation with full error handling and response processing:

View Java Sample

JavaScript

JavaScript Sample

Node.js and browser-compatible JavaScript implementation:

View JavaScript Sample

Python

Python Sample

Python implementation with requests library and JSON handling:

View Python Sample

Salesforce

Salesforce Sample

Salesforce implementation with Apex and HTTP callouts:

View Salesforce Sample

n8n

n8n Sample

n8n workflow implementation with HTTP request nodes:

View n8n Sample

Google Script

Google Script Sample

Google Apps Script implementation with UrlFetchApp:

View Google Script Sample

AWS Lambda

AWS Lambda Sample

AWS Lambda implementation with Node.js and API Gateway:

View AWS Lambda Sample

PDF Attachment Features

Attachment Processing

• Multiple File Types: Support for various attachment formats including text files (.txt, .csv, .log), documents (.pdf, .doc, .docx, .xls, .xlsx), images (.jpg, .jpeg, .png, .gif), archives (.zip, .rar), and other file types
• Batch Processing: Add multiple attachments to a single PDF document in one operation by providing an array of attachment objects
• Base64 Encoding: Secure transmission of file content using Base64 encoding
• File Naming: Each attachment must include a docName with the appropriate file extension

Document Enhancement

• PDF Preservation: Maintains original PDF structure and content while adding attachments
• File Organization: Custom naming and organization of embedded attachments through the docName field
• Document Portability: Create self-contained document packages with all related files embedded in the PDF
• Professional Packaging: Generate comprehensive document packages for distribution

Response Handling

• Synchronous Processing: By default, the API processes requests synchronously and returns the PDF with attachments (200 status)
• Asynchronous Processing: Set async: true to enable asynchronous processing. The API returns a 202 status with a polling URL in the Location header
• Binary Response: The API returns the PDF file as binary content (application/pdf) when successful

Industry Use Cases & Applications

Legal & Professional Services

Legal & Professional Services Use Cases

• Legal Documentation: Include evidence files, contracts, and supporting documents
• Court Filings: Attach supporting documents to court filings and legal briefs
• Client Documentation: Package client documents with supporting materials
• Compliance Documentation: Include certificates, licenses, and regulatory documents

Education & Research

Education & Research Use Cases

• Academic Papers: Include datasets, research materials, and supplementary information
• Research Documentation: Attach research data and supplementary materials
• Thesis Submissions: Package theses with supporting documents and datasets
• Training Materials: Embed resources, exercises, and reference guides

Business & Enterprise

Business & Enterprise Use Cases

• Business Reports: Attach spreadsheets, charts, and detailed analysis files
• Project Deliverables: Package all project files into a single PDF document
• Document Packages: Create comprehensive document packages with supporting materials
• Corporate Documentation: Include supporting materials with corporate documents

Technology & Development

Technology & Development Use Cases

• Technical Documentation: Embed code samples, configuration files, and reference materials
• Software Documentation: Attach code files and technical specifications
• API Documentation: Include code examples and configuration files
• Developer Resources: Package developer resources and reference materials

Get Help

Get Your API KeyAPI SamplesGetting Started