add/text

The add/text-endpoint adds one or more text overlays to an existing PDF. The source document can be provided as a URL or as a base64-encoded string. A variety of options control the style of the watermark: font, size, color, rotation, opacity etc.

One use case of this endpoint is updating PDFs where the sources are no longer available. Text overlays can be used to provide updated contact information, add errata or mark parts of the document as outdated. As such, this endpoint is best suited to add watermarks to contracts, reports, catalogs and similar document types.

NEW: Video tutorial

Endpoint: 'https://api.pdfteam.com/api/add/text'
Method: 'POST'
Cost: 1
Params:
{
    job: string;
    user: string;
    key: string;
    test?: boolean;
    inputOptions: InputOptions;
    outputOptions?: OutputOptions;
    overlays?: [OverlayOptions];
}

// job: an arbitrary string to identify this job, see return value
// user: user name, see section 'API Access' in your account
// key: API key, see section 'API Access' in your account
// test: if TRUE, the API call will not consume credits. PDFs created
//       in test mode carry a watermark, default: FALSE

Returns:
{
    endpoint: string;
    job: string;
    credits: number;
    result: string;
}

// endpoint: 'add/text'
// job: same as above
// credits: number of credits consumed
// result: permalink to the PDF in S3 or a base64 encoded string

NOTE: "Test" mode is intended to dial in settings and options. Currently there are no hard limits on this feature. However, abusing "Test"-mode may lead to account termination, please see our terms.

with InputOptions:

InputOptions {
  source?: string;
  data: string;
}

// source: must be a fully qualified, publicly accessible URL (fetch timeout: 10sec.)
// data: a base64 encoded string, beginning with or without data URI, e.g.
//       'data:application/pdf;base64,JVBER...'
//
//       or
//
//       'JVBER...'
//
// If both params are given, source has precedence
//
// NOTE: If the source is not accessible or the data string can't be converted, the endpoint
// will return a 400 status code with an error message

with OutputOptions:

OutputOptions {
  storage?: boolean;
  file?: string;
}

// storage: if TRUE, write file to S3, else return PDF as base64, default: TRUE
// file: file name for document in S3, default: random uuid (v4)
//
// NOTE: File name must not contain '/' or ':'

with OverlayOptions:

OverlayOptions {
  type: string;
  position?: {
    x: string;
    y: string;
  };
  firstPageOnly?: Boolean;
  rotate?: number;
  config: TextConfig;
}

// type: "text"
// position.*: specify as cm, mm or inches (e.g. "10mm", "0.5in" etc.), default: x=0, y=0
// position.x: specify as "left" | "center" | "right"
// position.y: specify as "top" | "middle" | "bottom"
// firstPageOnly: if TRUE, put text on first page only, default: FALSE
// rotate: rotate by degrees, positive values rotate CCW, default: 0

with TextConfig:

TextConfig {
  data: string;
  size?: number;
  font?: string;
  color?: string;
  opacity?: number;
}

// data: The text to add. Max. 128 characters in UTF-8 encoding. Full ASCII
//       plus accented characters, umlauts and the like.
//
//       Currently, non-latin scripts are not supported. Consider creating an image overlay
//       with transparent background instead.
// size: fontsize in pt, default: 36pt (= 0.5in. = 12.7mm)
// font: the API currently supports the standard PostScript fonts:
//
//       - 'Times Roman'
//       - 'Times Roman Bold'
//       - 'Helvetica'
//       - 'Helvetica Bold'
//       - 'Courier'
//       - 'Courier Bold'
//
//       default: 'Helvetica'
// color: RGB in CSS style, e.g. '#FF0000', default: '#000000'
// opacity: 0-1, with 0 being fully transparent, default: 1

Code sample I (NodeJS with fetch)

Following is a code sample that adds the text 'TOP SECRET' to a PDF (source). The text is centered on the page and rotated 45 degrees CCW.

// Sample code for accessing the PDFTeam API, endpoint: add/text

const url = 'https://api.pdfteam.com/api/add/text';

let params = {
  job: '00012345',
  user: 'YOUR_USERNAME',
  key: 'YOUR_APIKEY',
  inputOptions: {
    source: 'https://pdfteam.com/samples/coyote_report.pdf',
  },
  outputOptions: {
    storage: true,
    file: 'processed_report.pdf',
  },
  overlays: [
    {
      rotate: 45,
      position: {
        x: 'center',
        y: 'middle',
      },
      firstPageOnly: false,
      type: 'text',
      config: {
        data: 'TOP SECRET',
        font: 'Helvetica Bold',
        size: 72,
        color: '#ff0000',
        opacity: 0.5,
      },
    },
  ]
};

fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(params),
}).then((result) => {
  result.text().then((text) => {
    console.log(text);
  });
});

Sample response:

{
  'endpoint':'add/text',
  'job':'00012345',
  'credits':1,
  'result':'https://pdfteam.s3.eu-north-1.amazonaws.com/.../processed_report.pdf'
}

Result I:

Code sample II (NodeJS with fetch)

Multiple text elements can be created simply by adding more overlays. Here we add a second element near the top of the page in a smaller font in blue. This text will only be displayed on the first page of the PDF:

  ...
  overlays: [
    {
      rotate: 45,
      position: {
        x: 'center',
        y: 'middle',
      },
      firstPageOnly: false,
      type: 'text',
      config: {
        data: 'TOP SECRET',
        font: 'Helvetica Bold',
        size: 72,
        color: '#ff0000',
        opacity: 0.5,
      },
    },
    {
      position: {
        x: 'center',
        y: '270mm',
      },
      firstPageOnly: true,
      type: 'text',
      config: {
        data: 'Send comments and suggestions to fatalon@coyoteduty.com. Deadline is April, 10.',
        font: 'Helvetica Bold',
        size: 12,
        color: '#0000FF',
      },
    }
  ]
  ...

Result II:

More code samples

PDF API Endpoint add/text sample: Python
PDF API Endpoint add/text sample: Rust
PDF API Endpoint add/text sample: C#
PDF API Endpoint add/text sample: PHP