PDF Blocks
Go to Page

Add a text watermark to a PDF

Stamp up to three lines of text across the pages of a PDF, with control over the template, color, and opacity.

Add a text watermark to a PDF document. Supply up to three lines of text and control the template, color, transparency, and margin. By default the watermark is stamped on every page. Use the pages parameter to target a subset. The API is stateless: your document is processed in-region and never stored.

Endpoint

POST
/v1/add_text_watermark

Available in every region. See Regions & data residency for routing and data residency.

Region URL
Global https://api.pdfblocks.com/v1/add_text_watermark
United States https://us.api.pdfblocks.com/v1/add_text_watermark
US HIPAA https://hipaa.api.pdfblocks.com/v1/add_text_watermark
European Union https://eu.api.pdfblocks.com/v1/add_text_watermark
United Kingdom https://uk.api.pdfblocks.com/v1/add_text_watermark
Canada https://ca.api.pdfblocks.com/v1/add_text_watermark
Australia https://au.api.pdfblocks.com/v1/add_text_watermark
Japan https://jp.api.pdfblocks.com/v1/add_text_watermark
India https://in.api.pdfblocks.com/v1/add_text_watermark
Brazil https://br.api.pdfblocks.com/v1/add_text_watermark

Authentication

Authenticate every request with your secret API key in the X-API-Key header, over HTTPS. Create and manage keys from the dashboard. See Authentication for details.

Request

The endpoint accepts a multipart/form-data request body.

filefilerequired

The input PDF document.

line_1stringrequired

The first line of watermark text. Maximum 32 characters. Use standard Latin characters.

line_2string

The second line of watermark text. Maximum 32 characters.

line_3string

The third line of watermark text. Maximum 32 characters.

pagesstring

The pages to stamp, written as a page range such as 1..3,5. When omitted, the watermark is applied to every page. Maximum 1000 characters.

templateintegerdefault:1001

The watermark template, which sets the style (filled or outline) and orientation.

colorstringdefault:Gray

The watermark color. One of Red, Blue, Gray, or Black.

transparencyintegerdefault:75

The transparency level, from 0 (fully opaque) to 100 (fully transparent).

margindecimaldefault:1.0

The distance, in inches, from the page border to the watermark. 0 or greater.

Watermark templates

Each template combines a style (filled or outline) with an orientation. Pass the ID to the template parameter.

Template Style Orientation
1001 Filled Diagonal, bottom-left to top-right (default)
1002 Filled Diagonal, top-left to bottom-right
1003 Filled Horizontal
1004 Filled Vertical, reading upward
1005 Filled Vertical, reading downward
1017 Outline Diagonal, bottom-left to top-right
1018 Outline Diagonal, top-left to bottom-right
1019 Outline Horizontal
1020 Outline Vertical, reading upward
1021 Outline Vertical, reading downward

See every template rendered on a sample page in the visual template catalog.

Colors

Value Swatch
Red #C00000
Blue #005DFF
Gray #545454
Black #000000

Selecting pages

The pages parameter takes a comma-separated list of 1-based page numbers and ranges. It is treated as a set: order and duplicates are ignored, and pages are always stamped in document order.

Pattern Selects
(omit) Every page
1 The first page only
1..3,5 Pages 1, 2, 3, and 5
2.. Page 2 through the last page
..-2 The first page through the second-to-last
-1 The last page

See Selecting pages for the complete reference.

Examples

Stamp a two-line watermark on pages 1–3 and 5:

cURLbash
curl https://api.pdfblocks.com/v1/add_text_watermark \
  -H 'X-API-Key: your_api_key' \
  -F file=@input.pdf \
  -F line_1='CONFIDENTIAL' \
  -F line_2='ACME, Inc.' \
  -F template=1001 \
  -F color=Red \
  -F pages='1..3,5' \
  -o watermarked.pdf
Pythonpython
# pip install requests
import requests

with open('input.pdf', 'rb') as file:
    response = requests.post(
        'https://api.pdfblocks.com/v1/add_text_watermark',
        headers={'X-API-Key': 'your_api_key'},
        files={'file': file},
        data={
            'line_1': 'CONFIDENTIAL',
            'line_2': 'ACME, Inc.',
            'template': 1001,
            'color': 'Red',
            'pages': '1..3,5',
        },
    )

response.raise_for_status()
with open('watermarked.pdf', 'wb') as output:
    output.write(response.content)
Node.jsjavascript
// Node.js 18+
import { readFile, writeFile } from 'node:fs/promises';

const body = new FormData();
body.set('file', new Blob([await readFile('input.pdf')]), 'input.pdf');
body.set('line_1', 'CONFIDENTIAL');
body.set('line_2', 'ACME, Inc.');
body.set('template', '1001');
body.set('color', 'Red');
body.set('pages', '1..3,5');

const response = await fetch('https://api.pdfblocks.com/v1/add_text_watermark', {
  method: 'POST',
  headers: { 'X-API-Key': 'your_api_key' },
  body,
});

if (!response.ok) throw new Error(`Request failed: ${response.status}`);
await writeFile('watermarked.pdf', Buffer.from(await response.arrayBuffer()));
PHPphp
<?php
$ch = curl_init('https://api.pdfblocks.com/v1/add_text_watermark');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: your_api_key'],
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => [
        'file' => new CURLFile('input.pdf', 'application/pdf'),
        'line_1' => 'CONFIDENTIAL',
        'line_2' => 'ACME, Inc.',
        'template' => '1001',
        'color' => 'Red',
        'pages' => '1..3,5',
    ],
]);

$pdf = curl_exec($ch);
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) === 200) {
    file_put_contents('watermarked.pdf', $pdf);
}
Rubyruby
# gem install http
require 'http'

response = HTTP
  .headers('X-API-Key' => 'your_api_key')
  .post('https://api.pdfblocks.com/v1/add_text_watermark', form: {
    file: HTTP::FormData::File.new('input.pdf'),
    line_1: 'CONFIDENTIAL',
    line_2: 'ACME, Inc.',
    template: '1001',
    color: 'Red',
    pages: '1..3,5',
  })

File.write('watermarked.pdf', response.body) if response.status.success?
Gogo
package main

import (
	"bytes"
	"io"
	"mime/multipart"
	"net/http"
	"os"
)

func main() {
	var buf bytes.Buffer
	form := multipart.NewWriter(&buf)

	file, _ := os.Open("input.pdf")
	defer file.Close()
	part, _ := form.CreateFormFile("file", "input.pdf")
	io.Copy(part, file)

	form.WriteField("line_1", "CONFIDENTIAL")
	form.WriteField("line_2", "ACME, Inc.")
	form.WriteField("template", "1001")
	form.WriteField("color", "Red")
	form.WriteField("pages", "1..3,5")
	form.Close()

	req, _ := http.NewRequest("POST", "https://api.pdfblocks.com/v1/add_text_watermark", &buf)
	req.Header.Set("Content-Type", form.FormDataContentType())
	req.Header.Set("X-API-Key", "your_api_key")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()

	out, _ := os.Create("watermarked.pdf")
	defer out.Close()
	io.Copy(out, res.Body)
}
C#csharp
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "your_api_key");

using var form = new MultipartFormDataContent
{
    { new ByteArrayContent(File.ReadAllBytes("input.pdf")), "file", "input.pdf" },
    { new StringContent("CONFIDENTIAL"), "line_1" },
    { new StringContent("ACME, Inc."), "line_2" },
    { new StringContent("1001"), "template" },
    { new StringContent("Red"), "color" },
    { new StringContent("1..3,5"), "pages" },
};

var response = await client.PostAsync(
    "https://api.pdfblocks.com/v1/add_text_watermark", form);
response.EnsureSuccessStatusCode();
await File.WriteAllBytesAsync(
    "watermarked.pdf", await response.Content.ReadAsByteArrayAsync());

Response

On success, the response is 200 OK with the watermarked PDF as the body:

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Length: 48213

The output preserves the input’s page count and dimensions: only the watermark is added. Stream the body straight to a file, as the examples above do; nothing is stored on our side.

Errors

Failed requests return an application/problem+json body. The most common one for this endpoint is a 400, returned when a parameter is invalid or file isn’t a readable PDF. The errors object names each field:

{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/400",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "line_1": ["The field line_1 must be a string with a maximum length of 32."]
  }
}

A missing or invalid X-API-Key returns a 401. See Errors for every status code and the full response shape.

Recipes

Common variations. Expand one to see it in every language.

A bold red DRAFT across every page
cURLbash
curl https://api.pdfblocks.com/v1/add_text_watermark \
  -H 'X-API-Key: your_api_key' \
  -F file=@input.pdf \
  -F line_1='DRAFT' \
  -F color=Red \
  -F template=1001 \
  -F transparency=40 \
  -o draft.pdf
Pythonpython
import requests

with open('input.pdf', 'rb') as file:
    response = requests.post(
        'https://api.pdfblocks.com/v1/add_text_watermark',
        headers={'X-API-Key': 'your_api_key'},
        files={'file': file},
        data={'line_1': 'DRAFT', 'color': 'Red', 'template': 1001, 'transparency': 40},
    )

response.raise_for_status()
with open('draft.pdf', 'wb') as output:
    output.write(response.content)
Node.jsjavascript
import { readFile, writeFile } from 'node:fs/promises';

const body = new FormData();
body.set('file', new Blob([await readFile('input.pdf')]), 'input.pdf');
body.set('line_1', 'DRAFT');
body.set('color', 'Red');
body.set('template', '1001');
body.set('transparency', '40');

const response = await fetch('https://api.pdfblocks.com/v1/add_text_watermark', {
  method: 'POST',
  headers: { 'X-API-Key': 'your_api_key' },
  body,
});

if (!response.ok) throw new Error(`Request failed: ${response.status}`);
await writeFile('draft.pdf', Buffer.from(await response.arrayBuffer()));
PHPphp
<?php
$ch = curl_init('https://api.pdfblocks.com/v1/add_text_watermark');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: your_api_key'],
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => [
        'file' => new CURLFile('input.pdf', 'application/pdf'),
        'line_1' => 'DRAFT',
        'color' => 'Red',
        'template' => '1001',
        'transparency' => '40',
    ],
]);

$pdf = curl_exec($ch);
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) === 200) {
    file_put_contents('draft.pdf', $pdf);
}
Rubyruby
require 'http'

response = HTTP
  .headers('X-API-Key' => 'your_api_key')
  .post('https://api.pdfblocks.com/v1/add_text_watermark', form: {
    file: HTTP::FormData::File.new('input.pdf'),
    line_1: 'DRAFT',
    color: 'Red',
    template: '1001',
    transparency: '40',
  })

File.write('draft.pdf', response.body) if response.status.success?
Gogo
package main

import (
	"bytes"
	"io"
	"mime/multipart"
	"net/http"
	"os"
)

func main() {
	var buf bytes.Buffer
	form := multipart.NewWriter(&buf)

	file, _ := os.Open("input.pdf")
	defer file.Close()
	part, _ := form.CreateFormFile("file", "input.pdf")
	io.Copy(part, file)

	form.WriteField("line_1", "DRAFT")
	form.WriteField("color", "Red")
	form.WriteField("template", "1001")
	form.WriteField("transparency", "40")
	form.Close()

	req, _ := http.NewRequest("POST", "https://api.pdfblocks.com/v1/add_text_watermark", &buf)
	req.Header.Set("Content-Type", form.FormDataContentType())
	req.Header.Set("X-API-Key", "your_api_key")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()

	out, _ := os.Create("draft.pdf")
	defer out.Close()
	io.Copy(out, res.Body)
}
C#csharp
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "your_api_key");

using var form = new MultipartFormDataContent
{
    { new ByteArrayContent(File.ReadAllBytes("input.pdf")), "file", "input.pdf" },
    { new StringContent("DRAFT"), "line_1" },
    { new StringContent("Red"), "color" },
    { new StringContent("1001"), "template" },
    { new StringContent("40"), "transparency" },
};

var response = await client.PostAsync(
    "https://api.pdfblocks.com/v1/add_text_watermark", form);
response.EnsureSuccessStatusCode();
await File.WriteAllBytesAsync(
    "draft.pdf", await response.Content.ReadAsByteArrayAsync());
An outline CONFIDENTIAL on the cover page
cURLbash
curl https://api.pdfblocks.com/v1/add_text_watermark \
  -H 'X-API-Key: your_api_key' \
  -F file=@input.pdf \
  -F line_1='CONFIDENTIAL' \
  -F template=1017 \
  -F pages='1' \
  -o confidential.pdf
Pythonpython
import requests

with open('input.pdf', 'rb') as file:
    response = requests.post(
        'https://api.pdfblocks.com/v1/add_text_watermark',
        headers={'X-API-Key': 'your_api_key'},
        files={'file': file},
        data={'line_1': 'CONFIDENTIAL', 'template': 1017, 'pages': '1'},
    )

response.raise_for_status()
with open('confidential.pdf', 'wb') as output:
    output.write(response.content)
Node.jsjavascript
import { readFile, writeFile } from 'node:fs/promises';

const body = new FormData();
body.set('file', new Blob([await readFile('input.pdf')]), 'input.pdf');
body.set('line_1', 'CONFIDENTIAL');
body.set('template', '1017');
body.set('pages', '1');

const response = await fetch('https://api.pdfblocks.com/v1/add_text_watermark', {
  method: 'POST',
  headers: { 'X-API-Key': 'your_api_key' },
  body,
});

if (!response.ok) throw new Error(`Request failed: ${response.status}`);
await writeFile('confidential.pdf', Buffer.from(await response.arrayBuffer()));
PHPphp
<?php
$ch = curl_init('https://api.pdfblocks.com/v1/add_text_watermark');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: your_api_key'],
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => [
        'file' => new CURLFile('input.pdf', 'application/pdf'),
        'line_1' => 'CONFIDENTIAL',
        'template' => '1017',
        'pages' => '1',
    ],
]);

$pdf = curl_exec($ch);
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) === 200) {
    file_put_contents('confidential.pdf', $pdf);
}
Rubyruby
require 'http'

response = HTTP
  .headers('X-API-Key' => 'your_api_key')
  .post('https://api.pdfblocks.com/v1/add_text_watermark', form: {
    file: HTTP::FormData::File.new('input.pdf'),
    line_1: 'CONFIDENTIAL',
    template: '1017',
    pages: '1',
  })

File.write('confidential.pdf', response.body) if response.status.success?
Gogo
package main

import (
	"bytes"
	"io"
	"mime/multipart"
	"net/http"
	"os"
)

func main() {
	var buf bytes.Buffer
	form := multipart.NewWriter(&buf)

	file, _ := os.Open("input.pdf")
	defer file.Close()
	part, _ := form.CreateFormFile("file", "input.pdf")
	io.Copy(part, file)

	form.WriteField("line_1", "CONFIDENTIAL")
	form.WriteField("template", "1017")
	form.WriteField("pages", "1")
	form.Close()

	req, _ := http.NewRequest("POST", "https://api.pdfblocks.com/v1/add_text_watermark", &buf)
	req.Header.Set("Content-Type", form.FormDataContentType())
	req.Header.Set("X-API-Key", "your_api_key")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()

	out, _ := os.Create("confidential.pdf")
	defer out.Close()
	io.Copy(out, res.Body)
}
C#csharp
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "your_api_key");

using var form = new MultipartFormDataContent
{
    { new ByteArrayContent(File.ReadAllBytes("input.pdf")), "file", "input.pdf" },
    { new StringContent("CONFIDENTIAL"), "line_1" },
    { new StringContent("1017"), "template" },
    { new StringContent("1"), "pages" },
};

var response = await client.PostAsync(
    "https://api.pdfblocks.com/v1/add_text_watermark", form);
response.EnsureSuccessStatusCode();
await File.WriteAllBytesAsync(
    "confidential.pdf", await response.Content.ReadAsByteArrayAsync());
A subtle gray notice on every page but the last
cURLbash
curl https://api.pdfblocks.com/v1/add_text_watermark \
  -H 'X-API-Key: your_api_key' \
  -F file=@input.pdf \
  -F line_1='ACME, Inc.' \
  -F line_2='Do not distribute' \
  -F color=Gray \
  -F transparency=88 \
  -F pages='..-2' \
  -o notice.pdf
Pythonpython
import requests

with open('input.pdf', 'rb') as file:
    response = requests.post(
        'https://api.pdfblocks.com/v1/add_text_watermark',
        headers={'X-API-Key': 'your_api_key'},
        files={'file': file},
        data={
            'line_1': 'ACME, Inc.',
            'line_2': 'Do not distribute',
            'color': 'Gray',
            'transparency': 88,
            'pages': '..-2',
        },
    )

response.raise_for_status()
with open('notice.pdf', 'wb') as output:
    output.write(response.content)
Node.jsjavascript
import { readFile, writeFile } from 'node:fs/promises';

const body = new FormData();
body.set('file', new Blob([await readFile('input.pdf')]), 'input.pdf');
body.set('line_1', 'ACME, Inc.');
body.set('line_2', 'Do not distribute');
body.set('color', 'Gray');
body.set('transparency', '88');
body.set('pages', '..-2');

const response = await fetch('https://api.pdfblocks.com/v1/add_text_watermark', {
  method: 'POST',
  headers: { 'X-API-Key': 'your_api_key' },
  body,
});

if (!response.ok) throw new Error(`Request failed: ${response.status}`);
await writeFile('notice.pdf', Buffer.from(await response.arrayBuffer()));
PHPphp
<?php
$ch = curl_init('https://api.pdfblocks.com/v1/add_text_watermark');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: your_api_key'],
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => [
        'file' => new CURLFile('input.pdf', 'application/pdf'),
        'line_1' => 'ACME, Inc.',
        'line_2' => 'Do not distribute',
        'color' => 'Gray',
        'transparency' => '88',
        'pages' => '..-2',
    ],
]);

$pdf = curl_exec($ch);
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) === 200) {
    file_put_contents('notice.pdf', $pdf);
}
Rubyruby
require 'http'

response = HTTP
  .headers('X-API-Key' => 'your_api_key')
  .post('https://api.pdfblocks.com/v1/add_text_watermark', form: {
    file: HTTP::FormData::File.new('input.pdf'),
    line_1: 'ACME, Inc.',
    line_2: 'Do not distribute',
    color: 'Gray',
    transparency: '88',
    pages: '..-2',
  })

File.write('notice.pdf', response.body) if response.status.success?
Gogo
package main

import (
	"bytes"
	"io"
	"mime/multipart"
	"net/http"
	"os"
)

func main() {
	var buf bytes.Buffer
	form := multipart.NewWriter(&buf)

	file, _ := os.Open("input.pdf")
	defer file.Close()
	part, _ := form.CreateFormFile("file", "input.pdf")
	io.Copy(part, file)

	form.WriteField("line_1", "ACME, Inc.")
	form.WriteField("line_2", "Do not distribute")
	form.WriteField("color", "Gray")
	form.WriteField("transparency", "88")
	form.WriteField("pages", "..-2")
	form.Close()

	req, _ := http.NewRequest("POST", "https://api.pdfblocks.com/v1/add_text_watermark", &buf)
	req.Header.Set("Content-Type", form.FormDataContentType())
	req.Header.Set("X-API-Key", "your_api_key")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()

	out, _ := os.Create("notice.pdf")
	defer out.Close()
	io.Copy(out, res.Body)
}
C#csharp
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "your_api_key");

using var form = new MultipartFormDataContent
{
    { new ByteArrayContent(File.ReadAllBytes("input.pdf")), "file", "input.pdf" },
    { new StringContent("ACME, Inc."), "line_1" },
    { new StringContent("Do not distribute"), "line_2" },
    { new StringContent("Gray"), "color" },
    { new StringContent("88"), "transparency" },
    { new StringContent("..-2"), "pages" },
};

var response = await client.PostAsync(
    "https://api.pdfblocks.com/v1/add_text_watermark", form);
response.EnsureSuccessStatusCode();
await File.WriteAllBytesAsync(
    "notice.pdf", await response.Content.ReadAsByteArrayAsync());
Add an image watermark

Stamp a logo or image instead of text.

Add a password

Encrypt the watermarked document.

Merge documents

Combine files before watermarking.

Add restrictions

Limit printing, copying, and editing.