> ## Documentation Index
> Fetch the complete documentation index at: https://developer.pdf.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Fill PDF Forms

> You can fill existing form fields in a PDF after identifying the form field names.

<Note>
  **Try it live:** [PDF Add → API Tester](/api-tester/pdf-add) — send a real request from your browser.
</Note>

<div id="fill-pdf-forms" />

<div id="fill-pdf-form" />

<div id="filling-pdf-forms" />

## `POST /v1/pdf/edit/add`

You can fill existing form fields in a PDF after identifying the form field names.

Once form fields are identified then the [fields\[\]](#param-fields) attribute should be used to populate the fields by fieldName .

<Note>To see the request size limits, please refer to the [Request Size Limits](/api/url-input-and-request-limits#pdf-co-request-size).</Note>

## Request body

<Note>Attributes are case-sensitive and should be inside JSON for POST request. for example: `{ "url": "https://example.com/file1.pdf" }` There are no query parameters.</Note>

<ParamField body="url" type="string" required>
  URL to the source file [`url` attribute](/api/url-input-and-request-limits#supported-file-sources)
</ParamField>

<div id="param-fields" />

<ParamField body="fields" type="array[object]">
  <Expandable title="field properties">
    <ParamField body="fieldName" type="string" required>
      Name of the form field. To find form fields please use [PDF Edit Add Helper](https://app.pdf.co/pdf-edit-add-helper).
    </ParamField>

    <ParamField body="text" type="string" required>
      Value to set for this field. If you have a checkbox, set X, true, 1, or another text which is different from false to enable the checkbox. For radio buttons and combo boxes, you need to set the item value in text or index of the item to select. To find form fields please use [PDF Edit Add Helper](https://app.pdf.co/pdf-edit-add-helper).
    </ParamField>

    <ParamField body="pages" type="string">
      Specify page indices as comma-separated values or ranges to process (e.g. "0, 1, 2-" or "1, 2, 3-7"). The first-page index is 0, Use "!" before a number for inverted page numbers (e.g. "!0" for the last page). To process all pages, use "0-". If not specified, the default configuration processes all pages. The input must be in string format.
    </ParamField>

    <ParamField body="size" type="integer">
      Override the font size of the text inside the given input field.
    </ParamField>

    <ParamField body="fontName" type="string">
      Name of the font to use to fill out the input field.
    </ParamField>

    <ParamField body="fontBold" type="boolean">
      Override font bold style of the text input field.
    </ParamField>

    <ParamField body="fontItalic" type="boolean">
      Override font italic style of the text input field.
    </ParamField>

    <ParamField body="fontStrikeout" type="boolean">
      Override font strikeout style of the text input field.
    </ParamField>

    <ParamField body="fontUnderline" type="boolean">
      Override font underline style of the text input field.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="fieldsString" type="string">
  Set values for fillable PDF field objects. Each object is made of parameter separated by the `;` symbol. See [fieldsString](#fieldsstring) for more information.
</ParamField>

<ParamField body="profiles" type="string">
  See [Profiles](/api/profiles) for more information.

  <Expandable title="profiles properties">
    <ParamField body="FlattenDocument()" type="array">
      Flattening a document renders it as read-only. Handy if you want to remove editing or copying capability.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="callback" type="string">
  The callback URL (or Webhook) used to receive the POST data. see [Webhooks & Callbacks](/api/webhooks). This is only applicable when `async` is set to `true`.
</ParamField>

<ParamField body="httpusername" type="string">
  HTTP auth user name if required to access source URL.
</ParamField>

<ParamField body="httppassword" type="string">
  HTTP auth password if required to access source URL.
</ParamField>

<ParamField body="password" type="string">
  Password for the PDF file.
</ParamField>

<ParamField body="name" type="string">
  File name for the generated output, the input must be in string format.
</ParamField>

<ParamField body="expiration" type="integer" default="60">
  Set the expiration time for the output link in minutes. After this specified duration, any generated output file(s) will be automatically deleted from [PDF.co Temporary Files Storage](/api/file-upload/overview). The maximum duration for link expiration varies based on your current subscription plan. To store permanent input files (e.g. re-usable images, pdf templates, documents) consider using [PDF.co Built-In Files Storage](https://app.pdf.co/tools/files).
</ParamField>

<ParamField body="inline" type="boolean" default="false">
  Set to `true` to return results inside the response. Otherwise, the endpoint will return a URL to the output file generated.
</ParamField>

<ParamField body="async" type="boolean" default="false">
  Set `async` to `true` for long processes to run in the background, API will then return a `jobId` which you can use with the [Background Job Check endpoint](/api/job-check). Also see [Webhooks & Callbacks](/api/webhooks)
</ParamField>

### fieldsString

Set values for fillable PDF fields (i.e. fill pdf fields in pdf forms). To fill fields in PDF form, use the following format: `page;fieldName;value`.

Also, the advanced format can be used to override font name, size and style:

`0;fieldName;Field Text;12+bold+italic+underline+strikeout;FontName`

Where:
`0;editbox1;text is here;12+bold;Arial`

To fill the checkbox, use true, for example: `0;checkbox1;true`. If you have a checkbox, set X, true, 1, or another text which is different from false to enable the checkbox. For radio buttons and combo boxes, you need to set the item value in text or index of the item to select. To find form fields please use [PDF Edit Add Helper](https://app.pdf.co/pdf-edit-add-helper).

To separate multiple objects, use the `|` separator. To get the list of all fillable fields in a PDF form, use the [/pdf/info/fields](/api/forms/info-reader) endpoint. If you need to include a pipe character within a value, escape it by prefixing with `\\` (for example, `|` should be written as `\\|` and in a JSON string as `\\|`).

### Flatten Document

Flattening a document renders it as *read-only*. Handy if you want to remove editing or copying capability.

```json theme={null}
{
 "profiles": "{ 'FlattenDocument()': [] }"
}
```

### `Example` Payload (Fill PDF Forms)

```json theme={null}
{
  "async": false,
  "inline": true,
  "name": "f1040-filled",
  "url": "https://pdfco-test-files.s3.us-west-2.amazonaws.com/pdf-form/f1040.pdf",
  "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": 6,
          "fontBold": true,
          "fontItalic": true,
          "fontStrikeout": true,
          "fontUnderline": true
      },
      {
          "fieldName": "topmostSubform[0].Page1[0].YourSocial_ReadOrderControl[0].f1_05[0]",
          "pages": "1",
          "text": "Joan B."
      },
      {
          "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"
      }
  ]
}
```

### `Example` Response (Fill PDF Forms)

```json theme={null}
{
    "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "url": "https://pdf-temp-files.s3.amazonaws.com/cd15a09771554bed88d6419c1e2f2b16/f1040-filled.pdf",
    "pageCount": 3,
    "error": false,
    "status": 200,
    "name": "f1040-filled.pdf",
    "remainingCredits": 99999369,
    "credits": 63
}
```

### Code samples (For Fill PDF Forms)

<Tabs>
  <Tab title="CURL">
    ```bash theme={null}
    curl --location --request POST 'https://api.pdf.co/v1/pdf/edit/add' \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: *******************' \
    --data-raw '{
        "async": false,
        "inline": true,
        "name": "f1040-filled",
        "url": "https://pdfco-test-files.s3.us-west-2.amazonaws.com/pdf-form/f1040.pdf",
        "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": 6,
                "fontBold": true,
                "fontItalic": true,
                "fontStrikeout": true,
                "fontUnderline": true
            },
            {
                "fieldName": "topmostSubform[0].Page1[0].YourSocial_ReadOrderControl[0].f1_05[0]",
                "pages": "1",
                "text": "Joan B."
            },
            {
                "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"
            }
        ],
        "annotations":[
            {
                "text":"Sample Filled with PDF.co API using /pdf/edit/add. Get fields from forms using /pdf/info/fields. This text is be added on the first (0) and the last (!0) pages.",
                "x": 400,
                "y": 10,
                "width": 200,
                "height": 500,
                "size": 12,
                "pages": "0-",
                "color": "FF0000",
                "link": "https://pdf.co"
            }
        ]
      }'
    ```
  </Tab>

  <Tab title="JavaScript/Node.js">
    ```javascript theme={null}
    var https = require("https");
    var path = require("path");
    var fs = require("fs");

    // The authentication key (API Key).
    // Get your own by registering at https://app.pdf.co
    const API_KEY = "***********************************";

    // Direct URL of source PDF file.
    const SourceFileUrl = "https://pdfco-test-files.s3.us-west-2.amazonaws.com/pdf-form/f1040.pdf";

    // PDF document password. Leave empty for unprotected documents.
    const Password = "";

    // Destination PDF file name
    const DestinationFile = "./result.pdf";

    // Runs processing asynchronously. Returns Use JobId that you may use with /job/check to check state of the processing (possible states: working, failed, aborted and success). Must be one of: true, false.
    const async = false;

    // Form field data
    var 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."
        },
        {
            "fieldName": "topmostSubform[0].Page1[0].YourSocial_ReadOrderControl[0].f1_05[0]",
            "pages": "1",
            "text": "Joan B."
        },
        {
            "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"
        }
    ];

    // * Fill forms *
    // Prepare request to `PDF Edit` API endpoint
    var queryPath = `/v1/pdf/edit/add`;

    // JSON payload for api request
    var jsonPayload = JSON.stringify({
        name: path.basename(DestinationFile),
        password: Password,
        url: SourceFileUrl,
        async: async,
        fields: fields
    });

    var reqOptions = {
        host: "api.pdf.co",
        method: "POST",
        path: queryPath,
        headers: {
            "x-api-key": API_KEY,
            "Content-Type": "application/json",
            "Content-Length": Buffer.byteLength(jsonPayload, 'utf8')
        }
    };
    // Send request
    var postRequest = https.request(reqOptions, (response) => {
        response.on("data", (d) => {
            // Parse JSON response
            var data = JSON.parse(d);

            if (data.error == false) {
                // Download the PDF file
                var file = fs.createWriteStream(DestinationFile);
                https.get(data.url, (response2) => {
                    response2.pipe(file).on("close", () => {
                        console.log(`Generated PDF file saved to '${DestinationFile}' file.`);
                    });
                });
            }
            else {
                // Service reported error
                console.log(data.message);
            }
        });
    }).on("error", (e) => {
        // Request error
        console.error(e);
    });

    // Write request data
    postRequest.write(jsonPayload);
    postRequest.end();
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import os
    import requests # pip install requests

    # The authentication key (API Key).
    # Get your own by registering at https://app.pdf.co
    API_KEY = "**************************************"

    # Base URL for PDF.co Web API requests
    BASE_URL = "https://api.pdf.co/v1"

    def main(args = None):
        fillPDFForm()

    def fillPDFForm():
        """Fill PDF form using PDF.co Web API"""

        # Prepare requests params as JSON
        # See documentation: https://developer.pdf.co
        payload = "{\n    \"async\": false,\n    \"encrypt\": false,\n    \"name\": \"f1040-filled\",\n    \"url\": \"https://pdfco-test-files.s3.us-west-2.amazonaws.com/pdf-form/f1040.pdf\",\n    \"fields\": [\n        {\n            \"fieldName\": \"topmostSubform[0].Page1[0].FilingStatus[0].c1_01[1]\",\n            \"pages\": \"1\",\n            \"text\": \"True\"\n        },\n        {\n            \"fieldName\": \"topmostSubform[0].Page1[0].f1_02[0]\",\n            \"pages\": \"1\",\n            \"text\": \"John A.\"\n        },        \n        {\n            \"fieldName\": \"topmostSubform[0].Page1[0].f1_03[0]\",\n            \"pages\": \"1\",\n            \"text\": \"Doe\"\n        },        \n        {\n            \"fieldName\": \"topmostSubform[0].Page1[0].YourSocial_ReadOrderControl[0].f1_04[0]\",\n            \"pages\": \"1\",\n            \"text\": \"123456789\"\n        },\n        {\n            \"fieldName\": \"topmostSubform[0].Page1[0].YourSocial_ReadOrderControl[0].f1_05[0]\",\n            \"pages\": \"1\",\n            \"text\": \"Joan B.\"\n        },\n        {\n            \"fieldName\": \"topmostSubform[0].Page1[0].YourSocial_ReadOrderControl[0].f1_05[0]\",\n            \"pages\": \"1\",\n            \"text\": \"Joan B.\"\n        },\n        {\n            \"fieldName\": \"topmostSubform[0].Page1[0].YourSocial_ReadOrderControl[0].f1_06[0]\",\n            \"pages\": \"1\",\n            \"text\": \"Doe\"\n        },\n        {\n            \"fieldName\": \"topmostSubform[0].Page1[0].YourSocial_ReadOrderControl[0].f1_07[0]\",\n            \"pages\": \"1\",\n            \"text\": \"987654321\"\n        }     \n\n\n\n    ],\n    \"annotations\":[\n        {\n            \"text\":\"Sample Filled with PDF.co API using /pdf/edit/add. Get fields from forms using /pdf/info/fields\",\n            \"x\": 10,\n            \"y\": 10,\n            \"size\": 12,\n            \"pages\": \"0-\",\n            \"color\": \"FFCCCC\",\n            \"link\": \"https://pdf.co\"\n        }\n    ],    \n    \"images\": [        \n    ]\n}"

        # Prepare URL for 'Fill PDF' API request
        url = "{}/pdf/edit/add".format(BASE_URL)

        # Execute request and get response as JSON
        response = requests.post(url, data=payload, headers={"x-api-key": API_KEY, 'Content-Type': 'application/json'})
        if (response.status_code == 200):
            json = response.json()

            if json["error"] == False:
                #  Get URL of result file
                resultFileUrl = json["url"]
                # Download result file
                r = requests.get(resultFileUrl, stream=True)
                if (r.status_code == 200):
                    with open(destinationFile, 'wb') as file:
                        for chunk in r:
                            file.write(chunk)
                    print(f"Result file saved as \"{destinationFile}\" file.")
                else:
                    print(f"Request error: {response.status_code} {response.reason}")
            else:
                # Show service reported error
                print(json["message"])
        else:
            print(f"Request error: {response.status_code} {response.reason}")

    if __name__ == '__main__':
        main()
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    using Newtonsoft.Json;
    using Newtonsoft.Json.Linq;
    using System;
    using System.Collections.Generic;
    using System.Net;
    using System.Runtime.InteropServices;

    namespace PDFcoApiExample
    {
        class Program
        {
            // The authentication key (API Key).
            // Get your own by registering at https://app.pdf.co
            const String API_KEY = "*************************";

            // Direct URL of source PDF file.
            const string SourceFileUrl = "https://pdfco-test-files.s3.us-west-2.amazonaws.com/pdf-form/f1040.pdf";
            // PDF document password. Leave empty for unprotected documents.
            const string Password = "";
            // File name for generated output. Must be a String
            const string FileName = "f1040-form-filled";

            // Destination File Name
            const string DestinationFile = "./result.pdf";

            static void Main(string[] args)
            {
                // Create standard .NET web client instance
                WebClient webClient = new WebClient();

                // Set API Key
                webClient.Headers.Add("x-api-key", API_KEY);

                // Values to fill out pdf fields with built-in pdf form filler
                var fields = new List<object> {
                    new { fieldName = "topmostSubform[0].Page1[0].FilingStatus[0].c1_01[1]", pages = "1", text = "True" },
                    new { fieldName = "topmostSubform[0].Page1[0].f1_02[0]", pages = "1", text = "John A." },
                    new { fieldName = "topmostSubform[0].Page1[0].f1_03[0]", pages = "1", text = "Doe" },
                    new { fieldName = "topmostSubform[0].Page1[0].YourSocial_ReadOrderControl[0].f1_04[0]", pages = "1", text = "123456789" },
                    new { fieldName = "topmostSubform[0].Page1[0].YourSocial_ReadOrderControl[0].f1_05[0]", pages = "1", text = "John  B." },
                    new { fieldName = "topmostSubform[0].Page1[0].YourSocial_ReadOrderControl[0].f1_06[0]", pages = "1", text = "Doe" },
                    new { fieldName = "topmostSubform[0].Page1[0].YourSocial_ReadOrderControl[0].f1_07[0]", pages = "1", text = "987654321" }
                };

                // If enabled, Runs processing asynchronously. Returns Use JobId that you may use with /job/check to check state of the processing (possible states: working,
                var async = false;

                // Prepare requests params as JSON
                // See documentation: https://developer.pdf.co
                Dictionary<string, object> parameters = new Dictionary<string, object>();
                parameters.Add("url", SourceFileUrl);
                parameters.Add("name", FileName);
                parameters.Add("password", Password);
                parameters.Add("async", async);
                parameters.Add("fields", fields);

                // Convert dictionary of params to JSON
                string jsonPayload = JsonConvert.SerializeObject(parameters);

                try
                {
                    // URL of "PDF Edit" endpoint
                    string url = "https://api.pdf.co/v1/pdf/edit/add";

                    // Execute POST request with JSON payload
                    string response = webClient.UploadString(url, jsonPayload);

                    // Parse JSON response
                    JObject json = JObject.Parse(response);

                    if (json["error"].ToObject<bool>() == false)
                    {
                        // Get URL of generated PDF file
                        string resultFileUrl = json["url"].ToString();

                        // Download generated PDF file
                        webClient.DownloadFile(resultFileUrl, DestinationFile);

                        Console.WriteLine("Generated PDF file saved as \"{0}\" file.", DestinationFile);
                    }
                    else
                    {
                        Console.WriteLine(json["message"].ToString());
                    }
                }
                catch (WebException e)
                {
                    Console.WriteLine(e.ToString());
                }
                finally
                {
                    webClient.Dispose();
                }

                Console.WriteLine();
                Console.WriteLine("Press any key...");
                Console.ReadKey();
            }
        }
    }
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    package com.company;

    import com.google.gson.JsonObject;
    import com.google.gson.JsonParser;
    import okhttp3.*;

    import java.io.*;
    import java.net.*;
    import java.nio.file.Path;
    import java.nio.file.Paths;

    public class Main
    {
        // The authentication key (API Key).
        // Get your own by registering at https://app.pdf.co
        final static String API_KEY = "****************************";

        // Direct URL of source PDF file.
        final static String SourceFileUrl = "pdfco-test-files.s3.us-west-2.amazonaws.com/pdf-form/f1040.pdf";
        // PDF document password. Leave empty for unprotected documents.
        final static String Password = "";

        // Destination PDF file name
        final static Path ResultFile = Paths.get(".\\result.pdf");

        public static void main(String[] args) throws IOException
        {
            // Create HTTP client instance
            OkHttpClient webClient = new OkHttpClient();

            // Prepare URL for `PDF Edit` API call
            String query = "https://api.pdf.co/v1/pdf/edit/add";

            // Prepare form filling data
            String fields = "[\n" +
                    "        {\n" +
                    "            \"fieldName\": \"topmostSubform[0].Page1[0].FilingStatus[0].c1_01[1]\",\n" +
                    "            \"pages\": \"1\",\n" +
                    "            \"text\": \"True\"\n" +
                    "        },\n" +
                    "        {\n" +
                    "            \"fieldName\": \"topmostSubform[0].Page1[0].f1_02[0]\",\n" +
                    "            \"pages\": \"1\",\n" +
                    "            \"text\": \"John A.\"\n" +
                    "        },        \n" +
                    "        {\n" +
                    "            \"fieldName\": \"topmostSubform[0].Page1[0].f1_03[0]\",\n" +
                    "            \"pages\": \"1\",\n" +
                    "            \"text\": \"Doe\"\n" +
                    "        },        \n" +
                    "        {\n" +
                    "            \"fieldName\": \"topmostSubform[0].Page1[0].YourSocial_ReadOrderControl[0].f1_04[0]\",\n" +
                    "            \"pages\": \"1\",\n" +
                    "            \"text\": \"123456789\"\n" +
                    "        },\n" +
                    "        {\n" +
                    "            \"fieldName\": \"topmostSubform[0].Page1[0].YourSocial_ReadOrderControl[0].f1_05[0]\",\n" +
                    "            \"pages\": \"1\",\n" +
                    "            \"text\": \"Joan B.\"\n" +
                    "        },\n" +
                    "        {\n" +
                    "            \"fieldName\": \"topmostSubform[0].Page1[0].YourSocial_ReadOrderControl[0].f1_05[0]\",\n" +
                    "            \"pages\": \"1\",\n" +
                    "            \"text\": \"Joan B.\"\n" +
                    "        },\n" +
                    "        {\n" +
                    "            \"fieldName\": \"topmostSubform[0].Page1[0].YourSocial_ReadOrderControl[0].f1_06[0]\",\n" +
                    "            \"pages\": \"1\",\n" +
                    "            \"text\": \"Doe\"\n" +
                    "        },\n" +
                    "        {\n" +
                    "            \"fieldName\": \"topmostSubform[0].Page1[0].YourSocial_ReadOrderControl[0].f1_07[0]\",\n" +
                    "            \"pages\": \"1\",\n" +
                    "            \"text\": \"987654321\"\n" +
                    "        }     \n" +
                    "    ]";

            // Asynchronous Job
            String async = "false";

            // Make correctly escaped (encoded) URL
            URL url = null;
            try
            {
                url = new URI(null, query, null).toURL();
            }
            catch (URISyntaxException e)
            {
                e.printStackTrace();
            }

            // Create JSON payload
            String jsonPayload = String.format("{\n" +
                    "    \"url\": \"%s\",\n" +
                    "    \"async\": %s,\n" +
                    "    \"encrypt\": false,\n" +
                    "    \"name\": \"f1040-filled\",\n" +
                    "    \"fields\": %s"+
                    "}", SourceFileUrl, async, fields);

            // Prepare request body
            RequestBody body = RequestBody.create(MediaType.parse("application/json"), jsonPayload);
            // Prepare request
            Request request = new Request.Builder()
                    .url(url)
                    .addHeader("x-api-key", API_KEY) // (!) Set API Key
                    .addHeader("Content-Type", "application/json")
                    .post(body)
                    .build();

            // Execute request
            Response response = webClient.newCall(request).execute();

            if (response.code() == 200)
            {
                // Parse JSON response
                JsonObject json = new JsonParser().parse(response.body().string()).getAsJsonObject();

                boolean error = json.get("error").getAsBoolean();
                if (!error)
                {
                    // Get URL of generated output file
                    String resultFileUrl = json.get("url").getAsString();

                    // Download the image file
                    downloadFile(webClient, resultFileUrl, ResultFile);

                    System.out.printf("Generated file saved to \"%s\" file.", ResultFile.toString());
                }
                else
                {
                    // Display service reported error
                    System.out.println(json.get("message").getAsString());
                }
            }
            else
            {
                // Display request error
                System.out.println(response.code() + " " + response.message());
            }
        }

        public static void downloadFile(OkHttpClient webClient, String url, Path destinationFile) throws IOException
        {
            // Prepare request
            Request request = new Request.Builder()
                    .url(url)
                    .build();
            // Execute request
            Response response = webClient.newCall(request).execute();

            byte[] fileBytes = response.body().bytes();

            // Save downloaded bytes to file
            OutputStream output = new FileOutputStream(destinationFile.toFile());
            output.write(fileBytes);
            output.flush();
            output.close();

            response.close();
        }
    }
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    <?php

    // The authentication key (API Key).
    // Get your own by registering at https://app.pdf.co
    $API_KEY = "***********************************";

    // Direct URL of source PDF file.
    $SourceFileUrl = "https://pdfco-test-files.s3.us-west-2.amazonaws.com/pdf-form/f1040.pdf";


    fillPdfForm($API_KEY, $SourceFileUrl);


    function fillPdfForm($apiKey, $sourceFileUrl)
    {
        // Prepare URL for Fill PDF API call
        $url = "https://api.pdf.co/v1/pdf/edit/add";

        // Field Strings
        $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."
        },
        {
            "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"
        }]';// JSON string

        // Convert JSON string to Array
        $fieldsArray = json_decode($fields, true);

        // Prepare requests params
        // See documentation: https://developer.pdf.co
        $parameters = array();

        // Direct URL of source PDF file.
        $parameters["url"] = $sourceFileUrl;

        // Name of resulting file
        $parameters["name"] = "f1040-form-filled";

        // If large input document, process in async mode by passing true
        $parameters["async"] = false;

        $parameters["fields"] = $fieldsArray;

        // Create Json payload
        $data = json_encode($parameters);

        // Create request
        $curl = curl_init();
        curl_setopt($curl, CURLOPT_URL, $url);
        curl_setopt($curl, CURLOPT_HTTPHEADER, array("x-api-key: " . $apiKey, "Content-Type: application/json"));
        curl_setopt($curl, CURLOPT_POST, true);
        curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
        curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

        // Execute request
        $result = curl_exec($curl);
        $statusCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
        $curlError = curl_error($curl);
        curl_close($curl);

        if ($result === false) {
            // Display CURL error
            echo "fillPdfForm(): " . $curlError . PHP_EOL;
            return;
        }

        if ($statusCode != 200) {
            // Display request error
            echo "fillPdfForm(): request error " . $statusCode . PHP_EOL . $result . PHP_EOL;
            return;
        }

        $json = json_decode($result, true);

        if (!empty($json["error"])) {
            // Display service reported error
            echo "fillPdfForm(): " . $json["message"] . PHP_EOL;
            return;
        }

        // Display URL of the generated PDF file
        echo "Generated PDF file: " . $json["url"] . PHP_EOL;
    }

    ?>
    ```
  </Tab>
</Tabs>

<Panel>
  **Sample request**

  <RequestExample dropdown>
    ```bash cURL theme={null}
    curl --request POST \
      --url 'https://api.pdf.co/v1/pdf/edit/add' \
      --header 'Content-Type: application/json' \
      --header 'x-api-key: YOUR_API_KEY' \
      --data '{
        "async": false,
        "inline": true,
        "name": "f1040-form-filled",
        "url": "https://pdfco-test-files.s3.us-west-2.amazonaws.com/pdf-form/f1040.pdf",
        "fieldsString": "1;topmostSubform[0].Page1[0].f1_02[0];John A. Doe|1;topmostSubform[0].Page1[0].FilingStatus[0].c1_01[1];true|1;topmostSubform[0].Page1[0].YourSocial_ReadOrderControl[0].f1_04[0];123456789"
      }'
    ```

    ```javascript Node.js theme={null}
    const response = await fetch(
      "https://api.pdf.co/v1/pdf/edit/add",
      {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "x-api-key": "YOUR_API_KEY",
        },
        body: JSON.stringify({
          async: false,
          inline: true,
          name: "f1040-form-filled",
          url: "https://pdfco-test-files.s3.us-west-2.amazonaws.com/pdf-form/f1040.pdf",
          fieldsString: "1;topmostSubform[0].Page1[0].f1_02[0];John A. Doe|1;topmostSubform[0].Page1[0].FilingStatus[0].c1_01[1];true|1;topmostSubform[0].Page1[0].YourSocial_ReadOrderControl[0].f1_04[0];123456789",
        }),
      }
    );
    const result = await response.json();
    if (!response.ok || result.error) {
      throw new Error(result.message ?? "PDF.co request failed");
    }
    console.log(result.url);
    ```

    ```python Python theme={null}
    import requests

    response = requests.post(
        "https://api.pdf.co/v1/pdf/edit/add",
        headers={"x-api-key": "YOUR_API_KEY"},
        json={
            "async": False,
            "inline": True,
            "name": "f1040-form-filled",
            "url": "https://pdfco-test-files.s3.us-west-2.amazonaws.com/pdf-form/f1040.pdf",
            "fieldsString": "1;topmostSubform[0].Page1[0].f1_02[0];John A. Doe|1;topmostSubform[0].Page1[0].FilingStatus[0].c1_01[1];true|1;topmostSubform[0].Page1[0].YourSocial_ReadOrderControl[0].f1_04[0];123456789",
        },
    )
    result = response.json()
    if result.get("error"):
        raise RuntimeError(result.get("message", "PDF.co request failed"))
    print(result["url"])
    ```

    ```csharp C# theme={null}
    using System.Collections.Generic;
    using System.Net.Http;
    using System.Text;
    using System.Text.Json;

    var client = new HttpClient();
    client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");

    var payload = JsonSerializer.Serialize(new Dictionary<string, object>
    {
        ["async"] = false,
        ["inline"] = true,
        ["name"] = "f1040-form-filled",
        ["url"] = "https://pdfco-test-files.s3.us-west-2.amazonaws.com/pdf-form/f1040.pdf",
        ["fieldsString"] = "1;topmostSubform[0].Page1[0].f1_02[0];John A. Doe|1;topmostSubform[0].Page1[0].FilingStatus[0].c1_01[1];true|1;topmostSubform[0].Page1[0].YourSocial_ReadOrderControl[0].f1_04[0];123456789",
    });

    var response = await client.PostAsync(
        "https://api.pdf.co/v1/pdf/edit/add",
        new StringContent(payload, Encoding.UTF8, "application/json")
    );
    var json = await response.Content.ReadAsStringAsync();
    Console.WriteLine(json);
    ```

    ```java Java theme={null}
    OkHttpClient client = new OkHttpClient();

    String jsonPayload = "{\"async\": false, \"inline\": true, \"name\": \"f1040-form-filled\", \"url\": \"https://pdfco-test-files.s3.us-west-2.amazonaws.com/pdf-form/f1040.pdf\", \"fieldsString\": \"1;topmostSubform[0].Page1[0].f1_02[0];John A. Doe|1;topmostSubform[0].Page1[0].FilingStatus[0].c1_01[1];true|1;topmostSubform[0].Page1[0].YourSocial_ReadOrderControl[0].f1_04[0];123456789\"}";

    Request request = new Request.Builder()
        .url("https://api.pdf.co/v1/pdf/edit/add")
        .addHeader("x-api-key", "YOUR_API_KEY")
        .addHeader("Content-Type", "application/json")
        .post(RequestBody.create(MediaType.parse("application/json"), jsonPayload))
        .build();

    try (Response response = client.newCall(request).execute()) {
        System.out.println(response.body().string());
    }
    ```

    ```php PHP theme={null}
    <?php
    $payload = json_encode([
        "async" => false,
        "inline" => true,
        "name" => "f1040-form-filled",
        "url" => "https://pdfco-test-files.s3.us-west-2.amazonaws.com/pdf-form/f1040.pdf",
        "fieldsString" => "1;topmostSubform[0].Page1[0].f1_02[0];John A. Doe|1;topmostSubform[0].Page1[0].FilingStatus[0].c1_01[1];true|1;topmostSubform[0].Page1[0].YourSocial_ReadOrderControl[0].f1_04[0];123456789",
    ]);

    $curl = curl_init("https://api.pdf.co/v1/pdf/edit/add");
    curl_setopt_array($curl, [
        CURLOPT_HTTPHEADER => [
            "x-api-key: YOUR_API_KEY",
            "Content-Type: application/json",
        ],
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POSTFIELDS => $payload,
    ]);

    echo curl_exec($curl);
    curl_close($curl);
    ```
  </RequestExample>

  <ResponseExample>
    ```json 200 theme={null}
    {
        "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
        "url": "https://pdf-temp-files.s3.us-west-2.amazonaws.com/I0C35YE2U9G79PKS443RWZ4ZZSD7CPMS/f1040-form-filled.pdf?X-Amz-Expires=3600&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA4NRRSZPHPZV7KQXY%2F20260914%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20260914T093104Z&X-Amz-SignedHeaders=host&X-Amz-Signature=d2ae6765cf911f8426c757fb484a4bcf0e34827a960588440a86afdd5750a2cd",
        "outputLinkValidTill": "2026-09-14T10:31:04.2051588+00:00",
        "pageCount": 1,
        "error": false,
        "status": 200,
        "name": "f1040-form-filled.pdf",
        "duration": 254,
        "credits": 21,
        "remainingCredits": 88824
    }
    ```

    ```json 400 theme={null}
    {
      "error": true,
      "status": 400,
      "message": "Bad request. Typically due to bad input parameters or unreachable input URLs (e.g., access restrictions like login or password)."
    }
    ```

    ```json 401 theme={null}
    {
      "error": true,
      "status": 401,
      "message": "Unauthorized. Authentication is required and has failed or has not yet been provided."
    }
    ```

    ```json 402 theme={null}
    {
      "error": true,
      "status": 402,
      "message": "Not enough credits."
    }
    ```

    ```json 403 theme={null}
    {
      "error": true,
      "status": 403,
      "message": "Access forbidden for input URL."
    }
    ```

    ```json 404 theme={null}
    {
      "error": true,
      "status": 404,
      "message": "The requested resource could not be found."
    }
    ```

    ```json 408 theme={null}
    {
      "error": true,
      "status": 408,
      "message": "The server timed out waiting for the request."
    }
    ```

    ```json 429 theme={null}
    {
      "error": true,
      "status": 429,
      "message": "Too many requests in a given time period."
    }
    ```

    ```json 441 theme={null}
    {
      "error": true,
      "status": 441,
      "message": "Invalid Password. Password protected document."
    }
    ```

    ```json 442 theme={null}
    {
      "error": true,
      "status": 442,
      "message": "Input document is damaged or of incorrect type."
    }
    ```

    ```json 443 theme={null}
    {
      "error": true,
      "status": 443,
      "message": "Permissions. The operation is prohibited by document security settings."
    }
    ```

    ```json 444 theme={null}
    {
      "error": true,
      "status": 444,
      "message": "Profiles parsing error. Please ensure that the configuration is supported."
    }
    ```

    ```json 445 theme={null}
    {
      "error": true,
      "status": 445,
      "message": "Timeout error. For large documents, use asynchronous mode (async=true) and check status via /job/check."
    }
    ```

    ```json 446 theme={null}
    {
      "error": true,
      "status": 446,
      "message": "Some files required for conversion are missing."
    }
    ```

    ```json 447 theme={null}
    {
      "error": true,
      "status": 447,
      "message": "Invalid template."
    }
    ```

    ```json 448 theme={null}
    {
      "error": true,
      "status": 448,
      "message": "Invalid URL or HTML. Ensure the provided URL is valid and accessible."
    }
    ```

    ```json 449 theme={null}
    {
      "error": true,
      "status": 449,
      "message": "Invalid index range. Page index is out of range."
    }
    ```

    ```json 450 theme={null}
    {
      "error": true,
      "status": 450,
      "message": "Invalid page range specified."
    }
    ```

    ```json 452 theme={null}
    {
      "error": true,
      "status": 452,
      "message": "Invalid URL."
    }
    ```

    ```json 454 theme={null}
    {
      "error": true,
      "status": 454,
      "message": "Invalid parameters."
    }
    ```

    ```json 500 theme={null}
    {
      "error": true,
      "status": 500,
      "message": "Something went wrong. Please try again or contact support."
    }
    ```
  </ResponseExample>
</Panel>