Forms

What a form definition tells your integration, and how its fields map to the data of an entry.

A form (טופס) defines what people fill in: its fields, their rules, and what happens when someone submits it. Your integration reads a form to learn which fields exist and what values they take, so it can prefill entries and read the data people submit. This page shows how to read a form and what its properties tell you. Form data schema explains how the form's fields become the keys and values of an entry's data.

You build and change forms in the Tepez form builder. This page covers only what an integration needs from a form.

Read a form

GET /form/{formId} returns the whole form definition. Copy a form id from GET /form (see the Quickstart).

curl https://api.tepez.co.il/v1.0/form/<formId> \
  -H "x-api-key: $TEPEZ_API_KEY"

The response, trimmed to its first two fields:

{
  "id": "<formId>",
  "account": "<accountId>",
  "name": "Job application",
  "displayName": "Job application",
  "access": { "isDisabled": false },
  "formSchema": {
    "rootElem": {
      "name": "root",
      "type": "cSection",
      "children": [
        { "name": "fullName", "label": "Full name", "reqValidator": true, "type": "fInput" },
        { "name": "email", "label": "Email", "validators": "str/email", "type": "fInput" }
      ]
    }
  },
  "templates": [],
  "postSave": { "ui": [], "emails": [], "renders": [] },
  "postSubmit": { "renders": [{ "if": "true" }], "ui": [], "emails": [] },
  "postEdit": { "ui": [], "emails": [], "renders": [] },
  "postTemplate": { "emails": [], "renders": [] },
  "counts": { "all": 12, "submit": 5, "save": 6, "delete": 1, "start": 0, "template": 2, "render": 2 },
  "current": { "all": 11, "submit": 4, "save": 2, "template": 2, "render": 0 },
  "createTime": "2026-09-30T15:49:44.206Z",
  "modifyTime": "2026-09-30T16:02:30.614Z",
  "changedAt": "2026-09-30T16:03:24.465Z"
}

The properties an integration uses:

Property	What it tells you
`formSchema`	The fields and their layout. See Form data schema.
`name`, `publicName`, `displayName`	`name` is the form's name in the management app. `publicName`, when set, is the name shown to the people filling the form. `displayName` is the `name`, or the form's id when the form has no name.
`access.isDisabled`	`true` when the form is closed: nobody can start a new entry.
`formSchema.validateSaved`, `formSchema.validateTemplate`	Whether the form checks drafts, and templates, against its rules when they are saved: `true`, or an expression evaluated for each entry. Missing means `false`. Submits are always checked.
`postSave`, `postSubmit`, `postEdit`	What happens after each action: the emails the form sends and whether it archives a PDF (`renders`). Here `postSubmit.renders` archives a PDF of every submitted entry. See Files and PDFs.
`templates`	The form's PDF layouts. An empty list means the PDF is generated from the form itself.
`counts`, `current`	`counts` are running totals of actions on the form, such as saves, submits and PDF renders. `current` is how many entries the form has now in each status.
`modifyTime`	The last time someone changed the form itself. `changedAt` also moves when entries are added, so use `modifyTime` to notice a change to the form.

A form definition can be 100 KB or more. Read it when your integration starts or when modifyTime changes, not before every request. GET /form/{formId} doesn't accept fields. To read a few properties of many forms, use GET /form with fields, for example fields=["id","name","modifyTime"].

Fields and data

Form data schema explains how to work with a form's fields:

where each field's value sits in an entry's data
which value each kind of field takes, and its options
which fields are required, and which are hidden
a script that lists every field with its path, type and options, and the reports the form builder downloads

Troubleshooting

Response	Cause and fix
`400` `"fields" must be [null]`	`GET /form/{formId}` doesn't accept `fields`. Drop it, or use `GET /form` with `fields` and a `query` on `_id`.
`403` `You have insufficient permissions to perform the action.`	The form belongs to another account. A key reaches only the forms of its own account.
`400` `entry_failed_validation` when you save or submit an entry	The `data` broke a rule of the form. See Form data schema.

Every response carries an x-tepez-request-id header. Quote it when you contact us.

Email support with the request id

Read a form

Fields and data

Troubleshooting

On this page