Create a new field mapping that aliases raw PDF fields to your domain vocabulary.

Create mapping

Creates a new mapping for a template. The field_mappings dictionary uses raw PDF field names as keys and your aliases as values.

Signature

POST /api/v1/mappings

Content-Type: application/json

Permissions

API key scope: write or higher. Caller must have read access to the referenced template.

Request body

Field	Type	Required	Description
`name`	string (1–255 chars)	yes	Display name.
`template_id`	integer	yes	ID of the template this mapping targets.
`description`	string	no	Free-form description.
`schema_template_id`	integer	no	Optional schema template ID for reusable schemas.
`field_mappings`	object	no	Map of raw PDF field → alias (or transform object). See Mappings concept.
`transformations`	object	no	Additional named transformations.
`is_template`	boolean	no	If `true`, this mapping is published as a reusable template. Default `false`.
`template_category`	string	no	When `is_template` is true, the category to file under.
`template_description`	string	no	When `is_template` is true, a short description shown in the template library.

Example

curl -X POST https://api.simplyfill.app/v1/mappings \
  -H "Authorization: Bearer $SIMPLYFILL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Invoice — billing system",
    "template_id": 123,
    "field_mappings": {
      "invoice_number": "invoiceId",
      "customer_name": "clientName",
      "total_amount": "amount"
    }
  }'

const mapping = await client.mappings.create({
  name: 'Invoice — billing system',
  templateId: 123,
  fieldMappings: {
    invoice_number: 'invoiceId',
    customer_name: 'clientName',
    total_amount: 'amount'
  }
})

mapping = client.mappings.create(
    name="Invoice — billing system",
    template_id=123,
    field_mappings={
        "invoice_number": "invoiceId",
        "customer_name": "clientName",
        "total_amount": "amount",
    },
)

Response

201 Created:

{
  "id": 456,
  "name": "Invoice — billing system",
  "description": null,
  "template_id": 123,
  "schema_template_id": null,
  "field_mappings": {
    "invoice_number": "invoiceId",
    "customer_name": "clientName",
    "total_amount": "amount"
  },
  "transformations": {},
  "is_template": false,
  "template_category": null,
  "template_description": null,
  "user_id": 7,
  "organization_id": null,
  "created_at": "2026-05-17T15:01:09Z",
  "updated_at": null
}

Errors

Status	`error` code	Cause
`400`	`validation_error`	Required fields missing or `field_mappings` references unknown PDF fields.
`404`	`template_not_found`	`template_id` does not exist or you lack access.
`404`	`schema_template_not_found`	`schema_template_id` does not exist.

Create mapping

On this page