Skip to main content
POST
/
v1
/
edits
/
templates
/
fill
from retab import Retab

client = Retab()

edit = client.edits.templates.fill(
    template_id="edittplt_abc123",
    instructions="Name: John Doe, Date of Birth: 1990-01-15, Tax ID: 123-45-6789",
    model="retab-small",
)

print(f"Edit ID: {edit.id}")
for field in edit.data.form_data:
    print(f"{field.key} = {field.value}")
{
  "id": "edit_01G34H8J2K",
  "file": {
    "id": "file_6dd6eb00688ad8d1",
    "filename": "w9_empty.pdf",
    "mime_type": "application/pdf"
  },
  "model": "retab-small",
  "instructions": "Name: John Doe, Tax ID: 123-45-6789",
  "template_id": "edittplt_abc123",
  "config": {"color": "#000080"},
  "data": {
    "form_data": [
      {"key": "full_name", "type": "text", "value": "John Doe", "description": "Full legal name", "bbox": {"left": 0.15, "top": 0.20, "width": 0.35, "height": 0.03, "page": 1}},
      {"key": "tax_id", "type": "text", "value": "123-45-6789", "description": "Taxpayer Identification Number", "bbox": {"left": 0.15, "top": 0.28, "width": 0.25, "height": 0.03, "page": 1}}
    ],
    "filled_document": {
      "filename": "w9_filled.pdf",
      "url": "data:application/pdf;base64,JVBERi0xLjQK..."
    }
  },
  "usage": {"page_count": 1, "credits": 1.0},
  "created_at": "2024-03-15T10:30:00Z",
  "updated_at": "2024-03-15T10:30:00Z"
}
Fill a previously-registered EditTemplate with values described in instructions. Returns an Edit resource containing the filled PDF and the list of populated form fields.
from retab import Retab

client = Retab()

edit = client.edits.templates.fill(
    template_id="edittplt_abc123",
    instructions="Name: John Doe, Date of Birth: 1990-01-15, Tax ID: 123-45-6789",
    model="retab-small",
)

print(f"Edit ID: {edit.id}")
for field in edit.data.form_data:
    print(f"{field.key} = {field.value}")
{
  "id": "edit_01G34H8J2K",
  "file": {
    "id": "file_6dd6eb00688ad8d1",
    "filename": "w9_empty.pdf",
    "mime_type": "application/pdf"
  },
  "model": "retab-small",
  "instructions": "Name: John Doe, Tax ID: 123-45-6789",
  "template_id": "edittplt_abc123",
  "config": {"color": "#000080"},
  "data": {
    "form_data": [
      {"key": "full_name", "type": "text", "value": "John Doe", "description": "Full legal name", "bbox": {"left": 0.15, "top": 0.20, "width": 0.35, "height": 0.03, "page": 1}},
      {"key": "tax_id", "type": "text", "value": "123-45-6789", "description": "Taxpayer Identification Number", "bbox": {"left": 0.15, "top": 0.28, "width": 0.25, "height": 0.03, "page": 1}}
    ],
    "filled_document": {
      "filename": "w9_filled.pdf",
      "url": "data:application/pdf;base64,JVBERi0xLjQK..."
    }
  },
  "usage": {"page_count": 1, "credits": 1.0},
  "created_at": "2024-03-15T10:30:00Z",
  "updated_at": "2024-03-15T10:30:00Z"
}

Request Body

template_id
string
required
The template id whose pre-defined fields will be filled.
instructions
string
required
Natural-language instructions describing the values to fill.
model
string
default:"retab-small"
The model used for edit inference.
config
EditConfig
Rendering configuration. Currently supports color (hex code of the color used for the filled text).
bust_cache
boolean
default:"false"
When true, bypass the cache and re-run the fill.

Authorizations

Api-Key
string
header
required

Query Parameters

access_token
string | null

Body

application/json

The body is of type Payload · object.

Response

Successful Response

id
string
required

Unique identifier of the edit.

file
FileRef · object
required

Information about the source file (input document or template PDF).

model
string
required

Model used for the edit operation.

instructions
string
required

Instructions supplied with the edit request.

config
EditConfig · object
required

Configuration used for the edit operation.

data
EditResult · object
required

The edit result: filled form fields and the rendered PDF.

usage
RetabUsage · object
required

Usage information for the edit operation.

template_id
string | null

Template id used when the edit was created from a template; null for direct-document edits.

created_at
string<date-time> | null
updated_at
string<date-time> | null