ForHosting KIT · Documents & PDF

Overlay two PDFs

Overlay Two PDFs explains what a page-for-page stack will contain before you build or review the final document.

● BetaFree · in your browser

Use it from WebAPIEmailTelegramApp soon

Supply one ordered description for every page in the base PDF and one for every page in the overlay PDF. The result preserves the pairing, states the layer order, and produces a concise description for each combined page. It is especially useful for checking stamp templates, letterhead, approval marks, and other repeated artwork. Different page counts are rejected because there is no unambiguous corresponding-page overlay.

Describe both PDFs in page order

Start with two arrays containing extracted text or concise visual descriptions, one string for each PDF page. The pages_base array represents the document underneath, while pages_overlay represents the document placed on top. Keep every array in the original page order: the first base description is paired with the first overlay description, the second with the second, and so on. A description can mention text, logos, stamps, borders, form fields, or any other feature that matters to your review. Use an empty string when a real page is blank; do not remove that entry, because doing so changes all later pairings. This capability describes a proposed or extracted stack rather than altering PDF bytes. That makes it suitable for workflow checks, audit records, and human-readable previews when another system already extracts page content or knows the template design. Both fields must be non-empty arrays, every item must be a string, and the bounded input prevents an accidentally unmanageable job.

Understand the stacking result

For each page number, the response identifies the bottom base layer and the top overlay layer. The explicit stacking order matters: a stamp, letterhead, or annotation in the overlay PDF is conceptually drawn after the underlying document and may cover part of it in a rendered file. Because plain descriptions do not contain coordinates, colors, transparency, fonts, or exact object boundaries, the tool does not claim pixel-level collision detection. Instead, it gives a deterministic account of which described material contributes to each stacked page. Blank pages receive special treatment. If the overlay page is blank, the response says that the base remains unobstructed; if the base is blank, only the overlay contributes described content; and if both are blank, that state is recorded directly. Whitespace is normalized so descriptions copied from extraction tools remain readable and stable. The same inputs always produce exactly the same page sequence and wording, which makes results dependable in automated tests and approval logs.

Catch page-count mistakes before production

A page overlay is meaningful only when each base page has exactly one corresponding overlay page. The capability therefore compares the two array lengths before describing anything and returns an invalid-input error when they differ. This strict behavior catches a common document-production failure: a two-page stamp template applied to a three-page contract, or a cover sheet inserted into one file but not the other. Fix the source documents or add an intentional blank page description so that their structures agree, then run the request again. The response includes the verified page count, the overall bottom-to-top order, and one numbered record per pair, making it easy to compare against a job ticket or feed into a review interface. API automation costs $0.002 per request. Since processing is local, deterministic, and requires no network or model calls, sensitive page descriptions are not sent to an outside analysis provider, and phrasing will not drift between repeated executions of the same job.

What you can do with it

Review an approval stamp

Confirm that every contract page is paired with the intended approval or review stamp description.

Check letterhead templates

Describe how page-specific letterhead, footer, or border artwork stacks above existing document content.

Validate document assembly

Catch a missing or extra template page before a downstream renderer combines two production PDFs.

FAQ

Does this create a new PDF?

No. It returns a structured, page-by-page description of the stack; it does not modify or render PDF bytes.

Which PDF is on top?

pages_overlay is the top layer, and pages_base is the bottom layer.

What happens when page counts differ?

The request fails with an invalid-input error that reports both page counts.

How should I represent a blank page?

Keep its position in the array and use an empty string, so later pages remain correctly paired.

Can it detect whether a stamp hides specific words?

No. Text descriptions do not provide geometry or transparency, so the result describes layer contributions rather than pixel-level occlusion.

What does it cost?

Each API request costs $0.002.

For developers — API access

Everything on this page is available programmatically. This section is for teams who want to wire it into their own systems; everyone else can just use the tool above.

API endpoint

POSThttps://api.kit.forhosting.com/pdf/overlay-two-files

Prefer to automate it? One authenticated POST creates the task; the result comes back by webhook or a signed link. The same capability also runs here on the web, by email and from Telegram — and soon from our app too.

Call it from your stack

curl -X POST https://api.kit.forhosting.com/pdf/overlay-two-files \
  -H "Authorization: Bearer $KIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pages_base":["Invoice 1042: customer, line items, and total due","Payment terms and bank details"],"pages_overlay":["APPROVED stamp centered across the page","APPROVED stamp centered across the page"]}'

const res = await fetch("https://api.kit.forhosting.com/pdf/overlay-two-files", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.KIT_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "pages_base": [
      "Invoice 1042: customer, line items, and total due",
      "Payment terms and bank details"
    ],
    "pages_overlay": [
      "APPROVED stamp centered across the page",
      "APPROVED stamp centered across the page"
    ]
  })
});
const { task_id } = await res.json();

import os, requests

res = requests.post(
    "https://api.kit.forhosting.com/pdf/overlay-two-files",
    headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
    json={
    "pages_base": [
        "Invoice 1042: customer, line items, and total due",
        "Payment terms and bank details"
    ],
    "pages_overlay": [
        "APPROVED stamp centered across the page",
        "APPROVED stamp centered across the page"
    ]
},
)
task_id = res.json()["task_id"]

<?php
$res = file_get_contents("https://api.kit.forhosting.com/pdf/overlay-two-files", false, stream_context_create([
  "http" => [
    "method"  => "POST",
    "header"  => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
    "content" => '{"pages_base":["Invoice 1042: customer, line items, and total due","Payment terms and bank details"],"pages_overlay":["APPROVED stamp centered across the page","APPROVED stamp centered across the page"]}',
  ],
]));
$task = json_decode($res, true);

body := bytes.NewBufferString(`{"pages_base":["Invoice 1042: customer, line items, and total due","Payment terms and bank details"],"pages_overlay":["APPROVED stamp centered across the page","APPROVED stamp centered across the page"]}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/pdf/overlay-two-files", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)

Example request

{
  "pages_base": [
    "Invoice 1042: customer, line items, and total due",
    "Payment terms and bank details"
  ],
  "pages_overlay": [
    "APPROVED stamp centered across the page",
    "APPROVED stamp centered across the page"
  ]
}

Example response

{
  "task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
  "type": "pdf.overlay_two_files",
  "status": "queued",
  "_links": {
    "result": "/tasks/tsk_…/result"
  }
}

The API is asynchronous: the call returns a task_id immediately and the result arrives by webhook. Polling is capped at 1 req/s per task.

Pricing

Per request$0.002

Published price — no tokens, no invented credits. A failed task is never charged.

Limits

`max_mb`	25
`max_pages`	200

Errors

HTTP	Code	Meaning
`401`	`unauthorized`	Missing or invalid API key.
`402`	`insufficient_balance`	Your balance doesn't cover the task price.
`404`	`unknown_type`	That task type doesn't exist.
`429`	`rate_limited`	Too many requests. Use the webhook instead of polling.

Read the full KIT documentation →