Add Company Letterhead to Existing PDFs

Your PDF generation pipeline produces clean documents with transparent backgrounds, but they lack company branding. Now you need to add a professional letterhead with logo, footer, and sidebar to thousands of existing files. Regenerating them from scratch is not an option.

In this tutorial, we will use Ruby and the aPDF.io Underlay API to slide a branded letterhead design behind the existing content of your PDFs. The original text and data stay intact.

The Quick Solution

Here is the simplest Ruby code to add a letterhead behind your PDF content:

require 'rest-client'
require 'json'

response = RestClient.post(
  'https://apdf.io/api/pdf/page/underlay',
  {
    file: 'https://your-server.com/report.pdf',
    underlay: 'https://your-server.com/letterhead.pdf',
    repeat: '1'
  },
  {
    Authorization: 'Bearer YOUR_API_TOKEN',
    Accept: 'application/json',
    content_type: 'application/json'
  }
)

result = JSON.parse(response.body)
puts result['file']  # URL to the branded PDF

That is it. Your report now has the letterhead appearing behind every page.

Overlay vs. Underlay: What is the Difference?

The aPDF.io API offers two layer operations:

Overlay - Places a PDF on top of your document (watermarks, stamps, "CONFIDENTIAL" labels)
Underlay - Places a PDF behind your document (letterheads, backgrounds, branding)

For letterheads, underlay is the right choice. Your existing text, tables, and charts remain fully readable while the branded design appears in the background.

Important: For the underlay to be visible, your base PDF must have a transparent background. If your PDF has a solid white page background, it will cover the underlay completely. This approach works best with PDFs generated from HTML without explicit background colors, or documents specifically created with transparency.

Step 1: Create Your Letterhead PDF

Your letterhead needs to be a single-page PDF with the branding elements positioned where you want them. Common elements include:

Company logo in the header
Address and contact info in the footer
Decorative sidebar or border
Subtle background color or pattern

Option A: Use a Design Tool
Create your letterhead in Canva, Figma, or Adobe Illustrator. Export as PDF with the same page dimensions as your target documents (usually A4 or Letter).

Option B: Generate with HTML
Use the aPDF.io Create endpoint to generate a letterhead PDF from HTML. This is useful for dynamic elements like the current year in the footer.

<div style="position: fixed; top: 20px; left: 40px;">
  <img src="https://your-server.com/logo.png" style="height: 50px;">
</div>
<div style="
  position: fixed;
  bottom: 20px;
  left: 0;
  right: 0;
  text-align: center;
  font-size: 10px;
  color: #666;
">
  Acme Corp | 123 Business St | contact@acme.com
</div>

Step 2: Get Your API Token

Sign up at aPDF.io (it is free).
Copy your API Token from the dashboard.

Step 3: Bulk Letterhead Script

Here is a complete Ruby script that processes multiple reports and adds the letterhead to each one:

require 'rest-client'
require 'json'

API_TOKEN = 'YOUR_API_TOKEN_HERE'
API_URL = 'https://apdf.io/api/pdf/page/underlay'

# The letterhead PDF (your branded background)
LETTERHEAD_URL = 'https://your-server.com/letterhead.pdf'

# List of reports to brand
reports = [
  'https://your-server.com/reports/q1-sales.pdf',
  'https://your-server.com/reports/q2-sales.pdf',
  'https://your-server.com/reports/q3-sales.pdf'
]

puts "Starting letterhead application...\n"

reports.each_with_index do |report_url, index|
  begin
    puts "Processing report #{index + 1}/#{reports.length}..."

    response = RestClient.post(
      API_URL,
      {
        file: report_url,
        underlay: LETTERHEAD_URL,
        repeat: '1'
      },
      {
        Authorization: "Bearer #{API_TOKEN}",
        Accept: 'application/json',
        content_type: 'application/json'
      }
    )

    result = JSON.parse(response.body)

    puts "  Done: #{result['file']}"

  rescue RestClient::ExceptionWithResponse => e
    puts "  Error: #{e.response}"
  rescue => e
    puts "  Error: #{e.message}"
  end
end

puts "\nLetterhead application complete!"

Run the script

gem install rest-client
ruby add_letterhead.rb

Output

Starting letterhead application...
Processing report 1/3...
  Done: https://apdf-files.s3.eu-central-1.amazonaws.com/a1b2c3d4.pdf
Processing report 2/3...
  Done: https://apdf-files.s3.eu-central-1.amazonaws.com/e5f6g7h8.pdf
Processing report 3/3...
  Done: https://apdf-files.s3.eu-central-1.amazonaws.com/i9j0k1l2.pdf

Letterhead application complete!

Each URL is a branded version of the original report. You can download them or send them directly to recipients. Note: These URLs are valid for 1 hour.

Advanced: Skip the Cover Page

Many reports have a title page that should not have the letterhead. Use the to parameter to specify which pages receive the underlay:

response = RestClient.post(
  API_URL,
  {
    file: report_url,
    underlay: LETTERHEAD_URL,
    to: '2-z',  # Skip page 1, apply to pages 2 through the end
    repeat: '1'
  },
  {
    Authorization: "Bearer #{API_TOKEN}",
    Accept: 'application/json',
    content_type: 'application/json'
  }
)

The to: '2-z' parameter means "apply the letterhead from page 2 to the last page." Page 1 (your cover) stays clean.

Use Case: Different Letterheads per Department

Large organizations often have department-specific branding. Here is how to apply different letterheads based on the document type:

require 'rest-client'
require 'json'

API_TOKEN = 'YOUR_API_TOKEN_HERE'
API_URL = 'https://apdf.io/api/pdf/page/underlay'

# Department-specific letterheads
letterheads = {
  sales: 'https://your-server.com/letterheads/sales.pdf',
  hr: 'https://your-server.com/letterheads/hr.pdf',
  finance: 'https://your-server.com/letterheads/finance.pdf'
}

# Documents with their department
documents = [
  { url: 'https://your-server.com/docs/proposal.pdf', dept: :sales },
  { url: 'https://your-server.com/docs/handbook.pdf', dept: :hr },
  { url: 'https://your-server.com/docs/budget.pdf', dept: :finance }
]

documents.each do |doc|
  response = RestClient.post(
    API_URL,
    {
      file: doc[:url],
      underlay: letterheads[doc[:dept]],
      repeat: '1'
    },
    {
      Authorization: "Bearer #{API_TOKEN}",
      Accept: 'application/json',
      content_type: 'application/json'
    }
  )

  result = JSON.parse(response.body)
  puts "#{doc[:dept].capitalize}: #{result['file']}"
end

Conclusion

Retrofitting company branding onto existing PDFs is straightforward with the aPDF.io Underlay API. Instead of regenerating thousands of documents, you slide a letterhead design behind the existing content. The original text stays readable, and your brand appears on every page.

Next Steps

Once you have branded your documents, consider these follow-up actions:

Protect the Documents: Use the Password Protection endpoint to prevent unauthorized editing of your branded files.
Merge with Cover Letters: Combine branded reports with personalized cover letters using the Merge endpoint.

Ready to build?

Get your free API token here

Most APIs charge you per document. aPDF.io is built to be a developer-friendly, free alternative that handles the heavy lifting without the monthly subscription.