Best Practices

This guide covers practical tips for getting reliable results from Edit: choosing how to drive a run, controlling the output, and running at scale.

Prefer a schema for precision

Natural-language instructions are the fastest way to get started, but a schema with extend_edit:value on each field gives you exact, repeatable control over what gets filled and where. Reach for a schema whenever you run the same form type repeatedly or need deterministic output.

1
{
2
  "config": {
3
    "schema": {
4
      "type": "object",
5
      "properties": {
6
        "first_name": {
7
          "type": ["string", "null"],
8
          "extend_edit:field_type": "text",
9
          "extend_edit:value": "Jordan"
10
        }
11
      },
12
      "additionalProperties": false
13
    }
14
  }
15
}

Don’t have a schema yet? Generate Edit Schema detects a form’s fields and returns one with positions annotated, so you can start from a real layout instead of hand-writing field positions. See Schema.

Use instructions for context

When field mapping isn’t obvious — ambiguous labels, fields that depend on conditions — add instructions to guide how those fields should be filled. You can combine instructions with a schema: the schema pins the values you know, and instructions steer the rest.

1
{
2
  "config": {
3
    "instructions": "Use the Single filing status. For any date fields, use today's date. Leave optional fields blank."
4
  }
5
}

See Instructions.

Flatten final documents

Set advancedOptions.flattenPdf to true when you’re generating a document for delivery, so the filled fields can’t be edited further. Flattening is on by default; set it to false if you need the output to remain an editable form.

1
{
2
  "config": {
3
    "advancedOptions": { "flattenPdf": true }
4
  }
5
}

See Flatten the PDF.

Enable table parsing for tabular forms

For forms with large table regions you want filled, set advancedOptions.tableParsingEnabled to true so Extend parses those regions as arrays of objects you can populate.

1
{
2
  "config": {
3
    "advancedOptions": { "tableParsingEnabled": true }
4
  }
5
}

See Table parsing.

Download the edited file promptly

output.editedFile.presignedUrl expires 15 minutes after the run completes. Fetch and store the file as soon as the run reaches PROCESSED — don’t hold the URL for later use. The edited file’s id is reusable as input to other endpoints if you need to reprocess it.

Recipes

Ready-to-run config blocks for common scenarios (comments explain each setting). For field-level options and defaults, see Configuration.

Precise, repeatable fill

1
{
2
  "config": {
3
    "schema": {
4
      "type": "object",
5
      "properties": {
6
        "first_name": {
7
          "type": ["string", "null"],
8
          "extend_edit:field_type": "text",
9
          "extend_edit:value": "Jordan"
10
        },
11
        "ssn": {
12
          "type": ["string", "null"],
13
          "extend_edit:field_type": "text",
14
          "extend_edit:value": "123-45-6789",
15
          "extend_edit:text_edit_options": { "combing": true, "maxLength": 9 }  // character-by-character box
16
        }
17
      },
18
      "additionalProperties": false
19
    },
20
    "advancedOptions": { "flattenPdf": true }  // non-editable final document
21
  }
22
}

Quick fill from instructions

1
{
2
  "config": {
3
    "instructions": "Fill the applicant's name and today's date. Leave optional fields blank.",  // Extend detects and fills fields
4
    "advancedOptions": { "flattenPdf": false }  // keep the form editable
5
  }
6
}

Tabular form

1
{
2
  "config": {
3
    "instructions": "Fill the line-items table with the provided rows.",
4
    "advancedOptions": {
5
      "tableParsingEnabled": true,  // parse table regions as arrays of objects
6
      "flattenPdf": true
7
    }
8
  }
9
}

Move to production with async processing

The quick start and the examples above use the synchronous /edit endpoint — the fastest way to try Edit and iterate on config. When you’re ready to run Edit in production, switch to the asynchronous /edit_runs endpoint.

Why the sync /edit endpoint isn’t built for production:

• It has a 5-minute timeout — large or complex documents can exceed it and fail.
• It holds a connection open for the entire run, which is brittle for big files and bursty traffic.
• It’s intended for onboarding and testing, not sustained workloads.

What async (/edit_runs) gives you:

• Reliable handling of large documents without timeouts.
• Results via polling (GET /edit_runs/{id}) or webhooks, so you’re not holding connections open.
• A better fit for batch and high-volume pipelines.

The SDK helpers (client.edit_runs.create_and_poll() / client.editRuns.createAndPoll()) create a run and poll until it reaches a terminal state for you. See Async Processing for the full comparison, polling options, and webhook setup, and Error Handling for handling failed runs.