Editing Configuration

The Edit API accepts a config object that controls how a PDF is filled. You can pin the Edit pipeline with engineVersion and 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.

Engine version

engineVersion

Type: string (default: "1.0.0")

Pins the Edit engine version used to detect, understand, and fill form fields. Pass an exact version for reproducible results, or "latest" to use the latest stable version. The default stable version is "1.0.0"; "1.0.0-beta" and the legacy "0.0.1" version are also available. See the Edit version changelog for details.

{ "config": { "engineVersion": "1.0.0" } }

When you pass "latest", Extend resolves it before starting the run. The run’s returned config.engineVersion contains the resolved exact version. An unsupported exact version returns a 400 error.

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.

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

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.

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

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:

{
  "config": {
    "schema": {
      "type": "object",
      "required": ["first_name"],
      "properties": {
        "first_name": {
          "type": ["string", "null"],
          "description": "The taxpayer's first name and middle initial.",
          "extend_edit:field_type": "text",
          "extend_edit:value": "Jordan"
        },
        "last_name": {
          "type": ["string", "null"],
          "description": "The taxpayer's last name.",
          "extend_edit:field_type": "text",
          "extend_edit:value": "Avery"
        },
        "filing_status_single": {
          "type": ["boolean", "null"],
          "description": "Check this box for the Single filing status.",
          "extend_edit:field_type": "checkbox",
          "extend_edit:value": true
        }
      },
      "additionalProperties": false
    }
  }
}

Native AcroForm fields

For PDF form fields, Detect Form may return extend_edit:source_acroform. Keep this object unchanged when adding extend_edit:value and sending the schema to Edit.

{
  "enum": ["approved", "declined"],
  "extend_edit:field_type": "radio",
  "extend_edit:source_acroform": {
    "fieldName": "decision",
    "fieldType": "radio",
    "optionMap": [
      {
        "schemaValue": "approved",
        "exportValue": "Approved",
        "displayValue": "Approved"
      },
      {
        "schemaValue": "declined",
        "exportValue": "Declined",
        "displayValue": "Declined"
      }
    ]
  },
  "extend_edit:value": "approved"
}

fieldName and fieldType describe the PDF form field. optionMap lists the supported choices, and optionValue identifies the value for a selected option.

Signature image fills

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

{
  "type": "object",
  "extend_edit:field_type": "signature",
  "extend_edit:image": { "image_url": "https://example.com/signature.png" }
}

Combed fields

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

{
  "extend_edit:text_edit_options": { "combing": true, "maxLength": 9 }
}

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

{
  "extend_edit:text_edit_options": { "multiLine": true }
}

Text appearance

Use color for an RGB text color and opacity for text opacity. RGB channels are integers from 0 to 255; opacity ranges from 0 to 1. fontColor remains accepted as a deprecated alias for color.

{
  "extend_edit:text_edit_options": {
    "color": [24, 72, 120],
    "opacity": 0.8
  }
}

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.

{
  "config": {
    "schema": {
      "type": "object",
      "properties": {
        "employmentType": {
          "enum": ["FULL_TIME", "CONTRACTOR"],
          "extend_edit:field_type": "dropdown"
        },
        "contractEndDate": {
          "type": ["string", "null"],
          "extend_edit:field_type": "text"
        }
      },
      "if": { "properties": { "employmentType": { "enum": ["CONTRACTOR"] } } },
      "then": { "required": ["contractEndDate"] }
    }
  }
}

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.

{ "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.

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

advancedOptions.radioEnumsEnabled

Type: boolean (default: true with Edit 1.0.0)

Represent radio groups as enums so only one option can be selected.

The default is true for 1.0.0 and 1.0.0-beta, and false for 0.0.1.

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

advancedOptions.nativeFieldsOnly

Type: boolean (default: false)

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

{ "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.

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

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