Configuration

The Edit API accepts a config object that controls how a PDF is filled. You can drive a run two ways: with natural-language instructions, or with an explicit schema that pins each field’s type, value, and position using extend_edit:* keywords. Beyond those, schemaGenerationInstructions biases automatic field detection, the schema supports root-level conditional logic to make fields required based on other values, and advancedOptions controls flattening, table parsing, and field detection.

For default values and the full schema, see the Create Edit Run API reference.

Prefer a UI? Extend Studio lets you configure an editor visually and export the config JSON.

Instructions

instructions

Type: string

Natural-language guidance for the edit. Use it to describe the values to fill and any special handling. With instructions only, Extend detects the form’s fields and fills the ones you describe.

1
{
2
  "config": {
3
    "instructions": "Fill out all fields on the form. For the signature field, use 'John Doe'. Leave optional fields blank if no data is provided."
4
  }
5
}

schemaGenerationInstructions

Type: string

Additional instructions used when Extend generates a schema from the document (when you don’t supply one). Useful to bias field detection or naming without writing a full schema yourself.

1
{
2
  "config": {
3
    "schemaGenerationInstructions": "Detect signature fields, preserve table structure, and use customer-friendly field names."
4
  }
5
}

Schema

schema

Type: object

A JSON Schema defining the fields to edit. Each property uses extend_edit:* keywords to specify the PDF field type, position, value, and styling. If you don’t have a schema yet, Generate Edit Schema detects the fields and returns one with positions annotated.

Schema types

The PDF field type allowed for a property depends on its JSON type:

Field properties

Each field in the schema can include:

Example schema

The simplest schema gives each field a type, an extend_edit:field_type, and an extend_edit:value; Extend places it on the detected form field:

1
{
2
  "config": {
3
    "schema": {
4
      "type": "object",
5
      "required": ["first_name"],
6
      "properties": {
7
        "first_name": {
8
          "type": ["string", "null"],
9
          "description": "The taxpayer's first name and middle initial.",
10
          "extend_edit:field_type": "text",
11
          "extend_edit:value": "Jordan"
12
        },
13
        "last_name": {
14
          "type": ["string", "null"],
15
          "description": "The taxpayer's last name.",
16
          "extend_edit:field_type": "text",
17
          "extend_edit:value": "Avery"
18
        },
19
        "filing_status_single": {
20
          "type": ["boolean", "null"],
21
          "description": "Check this box for the Single filing status.",
22
          "extend_edit:field_type": "checkbox",
23
          "extend_edit:value": true
24
        }
25
      },
26
      "additionalProperties": false
27
    }
28
  }
29
}

Signature image fills

For signature fields, provide an image instead of a text value:

1
{
2
  "type": "object",
3
  "extend_edit:field_type": "signature",
4
  "extend_edit:image": { "image_url": "https://example.com/signature.png" }
5
}

Combed fields

For fields that require character-by-character input (SSN, phone numbers, policy numbers), use combing: true with a maxLength:

1
{
2
  "extend_edit:text_edit_options": { "combing": true, "maxLength": 9 }
3
}

Conditional form editing

Edit schemas support root-level JSON Schema conditionals, so you can make fields required or optional based on other values. Supported keywords include dependentRequired, if / then / else, allOf, oneOf, anyOf, and not. Conditional clauses do not accept extend_edit:* keys.

1
{
2
  "config": {
3
    "schema": {
4
      "type": "object",
5
      "properties": {
6
        "employmentType": {
7
          "enum": ["FULL_TIME", "CONTRACTOR"],
8
          "extend_edit:field_type": "dropdown"
9
        },
10
        "contractEndDate": {
11
          "type": ["string", "null"],
12
          "extend_edit:field_type": "text"
13
        }
14
      },
15
      "if": { "properties": { "employmentType": { "enum": ["CONTRACTOR"] } } },
16
      "then": { "required": ["contractEndDate"] }
17
    }
18
  }
19
}

This is useful for forms where follow-up fields only apply to a subset of users. A common workflow is to generate a base schema from the PDF, then add conditional requirements on top.

Advanced options

advancedOptions.flattenPdf

Type: boolean (default: true)

Flatten PDF forms after editing, making the form fields non-editable. Use when generating final documents.

1
{ "config": { "advancedOptions": { "flattenPdf": true } } }

advancedOptions.tableParsingEnabled

Type: boolean (default: false)

Parse table regions as arrays of objects. Enable for forms with large table regions you want filled.

1
{ "config": { "advancedOptions": { "tableParsingEnabled": true } } }

advancedOptions.radioEnumsEnabled

Type: boolean (default: false)

Model radio fields as enums, ensuring only one radio widget in a group is filled.

1
{ "config": { "advancedOptions": { "radioEnumsEnabled": true } } }

advancedOptions.nativeFieldsOnly

Type: boolean (default: false)

Only import native AcroForm fields from the PDF and skip object detection.

1
{ "config": { "advancedOptions": { "nativeFieldsOnly": true } } }

For the exact request and response schemas, see the Create Edit Run API reference.