How to Fill PDF Forms Using the PDF.co Web API in JavaScript

Create the Node.js Project

Create a new project directory and initialize it:

mkdir pdf-form-filler
cd pdf-form-filler
npm init -y

The example uses APIs included with Node.js 18, so no additional package is required.

Configure the PDF.co API Key

Copy your API key from the PDF.co dashboard.

Store it in the PDFCO_API_KEY environment variable.

On Windows PowerShell:

$env:PDFCO_API_KEY="YOUR_PDFCO_API_KEY"

On macOS or Linux:

export PDFCO_API_KEY="YOUR_PDFCO_API_KEY"

The application will send this value in the x-api-key request header.

Identify the PDF Form Fields

PDF form fields have internal names that may differ from their visible labels. You must use these internal names when constructing the request.

You can inspect a PDF form with the PDF.co PDF Inspector. Upload the form and review its field names, page information, and field types.

For automated inspection, use the /v1/pdf/info/fields endpoint. PDF.co recommends this endpoint for retrieving information about text fields, checkboxes, radio buttons, and other fillable controls.

For the sample form, a field name looks like this:

topmostSubform[0].Page1[0].f1_02[0]

Copy field names exactly, including capitalization, brackets, and indexes.

Define the Form-Field Values

Each object in the fields array can contain:

• fieldName: The internal PDF field name.
• pages: The page associated with the field.
• text: The value to place in the field.
• fontName: An optional font name.
• size: An optional font size.
• Font styling options such as fontBold, fontItalic, fontUnderline, and fontStrikeout.

For example:

const fields = [
    {
        fieldName: "topmostSubform[0].Page1[0].f1_02[0]",
        pages: "1",
        text: "John A."
    },
    {
        fieldName: "topmostSubform[0].Page1[0].f1_03[0]",
        pages: "1",
        text: "Doe"
    }
];

Use the page value returned by PDF Inspector or the fields-information endpoint.

For checkboxes and radio buttons, use the value required by that field. The sample form accepts "True" for the selected checkbox:

{
    fieldName: "topmostSubform[0].Page1[0].FilingStatus[0].c1_01[1]",
    pages: "1",
    text: "True"
}

When setting a custom font size, also specify fontName:

{
    fieldName:
        "topmostSubform[0].Page1[0].YourSocial_ReadOrderControl[0].f1_05[0]",
    pages: "1",
    text: "Joan B.",
    fontName: "Arial",
    size: 8
}

Create the JavaScript Application

Create a file named app.js and add the following code:

const { writeFile } = require("node:fs/promises");
const path = require("node:path");

const API_KEY = process.env.PDFCO_API_KEY;

const SOURCE_FILE_URL =
    "https://pdfco-test-files.s3.us-west-2.amazonaws.com/pdf-form/f1040.pdf";

const DESTINATION_FILE = "./result.pdf";

const fields = [
    {
        fieldName:
            "topmostSubform[0].Page1[0].FilingStatus[0].c1_01[1]",
        pages: "1",
        text: "True"
    },
    {
        fieldName:
            "topmostSubform[0].Page1[0].f1_02[0]",
        pages: "1",
        text: "John A."
    },
    {
        fieldName:
            "topmostSubform[0].Page1[0].f1_03[0]",
        pages: "1",
        text: "Doe"
    },
    {
        fieldName:
            "topmostSubform[0].Page1[0].YourSocial_ReadOrderControl[0].f1_04[0]",
        pages: "1",
        text: "123456789"
    },
    {
        fieldName:
            "topmostSubform[0].Page1[0].YourSocial_ReadOrderControl[0].f1_05[0]",
        pages: "1",
        text: "Joan B.",
        fontName: "Arial",
        size: 8
    },
    {
        fieldName:
            "topmostSubform[0].Page1[0].YourSocial_ReadOrderControl[0].f1_06[0]",
        pages: "1",
        text: "Doe"
    },
    {
        fieldName:
            "topmostSubform[0].Page1[0].YourSocial_ReadOrderControl[0].f1_07[0]",
        pages: "1",
        text: "987654321"
    }
];

async function fillPdfForm() {
    if (!API_KEY) {
        throw new Error(
            "Set the PDFCO_API_KEY environment variable before running the application."
        );
    }

    const payload = {
        name: path.basename(DESTINATION_FILE),
        url: SOURCE_FILE_URL,
        password: "",
        async: false,
        fields
    };

    const apiResponse = await fetch(
        "https://api.pdf.co/v1/pdf/edit/add",
        {
            method: "POST",
            headers: {
                "x-api-key": API_KEY,
                "Content-Type": "application/json"
            },
            body: JSON.stringify(payload)
        }
    );

    const responseText = await apiResponse.text();

    let result;

    try {
        result = JSON.parse(responseText);
    } catch {
        throw new Error(
            `PDF.co returned an invalid response: ${responseText}`
        );
    }

    if (!apiResponse.ok || result.error) {
        throw new Error(
            result.message ||
            `PDF.co returned HTTP ${apiResponse.status}.`
        );
    }

    if (!result.url) {
        throw new Error(
            "PDF.co did not return a URL for the completed PDF."
        );
    }

    console.log("Downloading the completed PDF...");

    const fileResponse = await fetch(result.url);

    if (!fileResponse.ok) {
        throw new Error(
            `Unable to download the completed PDF: HTTP ${fileResponse.status}.`
        );
    }

    const fileBuffer = Buffer.from(
        await fileResponse.arrayBuffer()
    );

    await writeFile(DESTINATION_FILE, fileBuffer);

    console.log(
        `Completed PDF saved as "${DESTINATION_FILE}".`
    );
}

fillPdfForm().catch((error) => {
    console.error(error.message);
    process.exitCode = 1;
});

Run the Application

Run the script from the same terminal session in which you configured the API key:

node app.js

When the request completes successfully, the application saves the filled form as:

result.pdf

Open the file and verify that the supplied values appear in the correct fields.