How to Add an Image to an Existing PDF with PDF.co API

Step 1: Prepare your input PDF and image

Start with:

• the URL of the PDF you want to edit
• the URL of the image you want to place on the PDF

If your PDF is password-protected, include the password field in the request. If you want the API to return a downloadable file URL, keep inline as false or omit it. If you want the output directly in the response, set inline to true. PDF.co also supports async: true for longer-running jobs.

Step 2: Build the request body

Here is a simple request body that adds one image to the first page of a PDF:

{
  "name": "output-with-logo",
  "url": "https://example.com/source.pdf",
  "images": [
    {
      "url": "https://example.com/logo.png",
      "x": 270,
      "y": 150,
      "width": 159,
      "height": 43,
      "pages": "0"
    }
  ]
}

This structure follows the current PDF.co schema for adding images to an existing PDF. The images array is the recommended way to add image objects.

Step 3: Choose the right placement and size

The most important design settings are:

X and Y coordinates

These control where the image appears on the page.

Width and height

These control the displayed size of the image.

Pages

Use a page string such as:

• "0" for the first page
• "1,2,3" for selected pages
• "0-" for all pages
• "!0" for the last page

We recommend using the PDF Inspector tool to measure coordinates more easily.

Step 4: Send the API request

Here is a basic Node.js example using fetch:

const apiKey = "YOUR_PDFCO_API_KEY";

const requestBody = {
  name: "output-with-logo",
  url: "https://example.com/source.pdf",
  images: [
    {
      url: "https://example.com/logo.png",
      x: 270,
      y: 150,
      width: 159,
      height: 43,
      pages: "0",
      keepAspectRatio: true
    }
  ]
};

async function addImageToPdf() {
  const response = await fetch("https://api.pdf.co/v1/pdf/edit/add", {
    method: "POST",
    headers: {
      "x-api-key": apiKey,
      "Content-Type": "application/json"
    },
    body: JSON.stringify(requestBody)
  });

  const data = await response.json();
  console.log(data);
}

addImageToPdf();

Requests should be sent as JSON for POST /v1/pdf/edit/add, and async and inline can be used depending on how you want to receive the result.

Step 5: Download and verify the output

If the request succeeds, PDF.co returns a successful response and either:

• a downloadable output URL, or
• inline output data when inline is enabled

{
  "url": "https://pdf-temp-files.s3.amazonaws.com/03c5c55183c74f8d94a4ec952e4e32ad/f1040-form-filled.pdf",
  "pageCount": 3,
  "error": false,
  "status": 200,
  "name": "Output",
  "remainingCredits": 60822
}

By default, output links are temporary and expire after a configurable period. The docs list the default expiration as 60 minutes unless changed with the expiration parameter.

Open the generated PDF and confirm that:

• the image appears on the expected page
• the size looks correct
• the placement matches your coordinates
• the image is not stretched unless intended