Editing 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 validate fields based on other values, and advancedOptions controls flattening, table parsing, field detection, and conditional generation.

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, Detect Form 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
}

For fields that should wrap across multiple lines, set multiLine: true:

1
{
2
  "extend_edit:text_edit_options": { "multiLine": true }
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.

For an introduction to these keywords and additional examples, see Conditional schema validation in the JSON Schema documentation.

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. You can write these rules yourself, or detect a form and generate them from requirements in the form content.

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 } } }

advancedOptions.conditionalGenerationEnabled

Type: boolean (default: false)

When Extend generates an edit schema, it reads requirements stated in the form and adds supported root-level JSON Schema conditionals that validate the generated field values. For example, a form instruction that requires an explanation after a “Yes” answer can become an if / then rule.

If an Edit run cannot generate values that satisfy the generated conditionals, the run fails with SCHEMA_VALIDATION_ERROR. A synchronous /edit request returns that value in the error body’s code; an asynchronous /edit_runs run returns it in failureReason. See Editing Error Handling.

This option applies only when the schema is generated. If you provide config.schema, Extend uses that schema as-is; include any conditional validation rules directly in it.

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

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