Prefill a form

Your system often knows part of what a form asks for: a customer's name, an employee's details, an order number. Prefilling saves the person typing it again and avoids typos. This page shows the three ways to do it, and when to use each:

Every method fills fields by their data path. Form data schema explains how to find each field's path, and Field types shows the value each kind of field takes.

Method 1: put the data in the link

Add a data parameter to the form's link. Its value is a JSON object of the values to prefill, URL-encoded. It needs no API key and no request to Tepez: your system only builds a link.

const data = { fullName: 'Dana Levi', position: 'qa', address: { city: 'Haifa' } };
const link = `https://app.tepez.co.il/f/<formId>/?data=${encodeURIComponent(JSON.stringify(data))}`;

Both produce this link:

https://app.tepez.co.il/f/<formId>/?data=%7B%22fullName%22%3A%22Dana%20Levi%22%2C%22position%22%3A%22qa%22%2C%22address%22%3A%7B%22city%22%3A%22Haifa%22%7D%7D

The form opens with the full name and city filled in and "QA engineer" chosen as the position. Nothing is saved until the person saves or submits.

The rules that decide whether a value lands in its field:

• Only fields the form declares are filled. Other keys are ignored and never saved. The parameter must be named data: other query string parameters, such as ?fullName=Dana, fill nothing.
• Nesting follows the form's sections. A field inside a section with "secFlat": false sits in an object named after the section, such as {"address": {"city": "Haifa"}}. A field inside any other section sits at the top level: {"phone": "050-0000000"}.
• Select fields take the option's value, not its label. "position": "qa" chooses "QA engineer". "position": "QA engineer" leaves the field empty.
• data must be a valid JSON object, URL-encoded. Invalid JSON is ignored without an error: the form opens empty. Encode the whole JSON with encodeURIComponent or its equivalent.
• Keep the encoded link under about 2,000 characters. Longer links can break in browsers and email clients. For more data, create a personal entry.
• tpz.link short links drop the data parameter. A short link redirects to its target without the query string, so https://tpz.link/<code>?data=… opens with no prefilled values. Put data on the full app.tepez.co.il link.

data works on every fill link: a form link (/f/<formId>/), a template link (/c/<entryId>/) and a personal entry link (/e/<entryId>/?b=<bewit>). On a template or personal entry link, the values in data are applied on top of the entry's own data, and each top-level key replaces that key whole. For example, data={"address":{"city":"Tel Aviv"}} on the link of an entry whose address is Haifa, Herzl 10 opens it with the city Tel Aviv and an empty street. On a personal entry, the replaced values are saved when the person next saves or submits, so add data to such a link only when you mean to overwrite the draft.

Method 2: create a personal entry

Create a draft entry with the values already in it, with POST /entry/save, and send the person its link. The data stays in Tepez, there is no length limit, and your system can later read the entry by its id to learn whether the person submitted it.

curl -X POST https://api.tepez.co.il/v1.0/entry/save \
  -H "x-api-key: $TEPEZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"form": "<formId>", "data": {"fullName": "Dana Levi", "email": "dana@example.com", "address": {"city": "Haifa", "street": "Herzl 10"}}}'

The response, trimmed:

{
  "entry": {
    "id": "<entryId>",
    "form": "<formId>",
    "status": "saved",
    "idx": 1,
    "data": {
      "fullName": "Dana Levi",
      "email": "dana@example.com",
      "address": { "city": "Haifa", "street": "Herzl 10" }
    },
    "bewit": "<bewit>",
    "resumeUrlBewit": "https://app.tepez.co.il/e/<entryId>/?b=<bewit>",
    "resumeUrl": "https://app.tepez.co.il/e/<entryId>/",
    "cloneUrl": "https://app.tepez.co.il/c/<entryId>/",
    "editUrl": "https://app.tepez.co.il/admin/entries/<formId>/<entryId>/",
    "createTime": "2026-09-30T16:43:48.668Z",
    "changedAt": "2026-09-30T16:43:48.692Z"
  },
  "uiActions": [{ "type": "continueLater" }],
  "userCanResume": true,
  "formId": "<formId>",
  "entryId": "<entryId>",
  "bewit": "<bewit>"
}

• Send the person entry.resumeUrlBewit. It opens this entry with no sign-in, until the entry is submitted, and for at most 2 years.
• The link is personal: anyone who has it can see and change the draft. Send each person only their own link. See Authentication.
• Store entry.id next to the person in your system. It is how you read the entry after they submit. Let your users fill a form in your app walks through the whole flow.
• A save checks the form's rules only if the form is set to check drafts, so a missing required field doesn't fail here. The person fills it in before submitting.
• When your system already has every value and nobody needs to fill anything in, skip the link and submit the entry yourself: see Submit entries from your server.

To hand out personal links before you know the values, create empty entries in bulk with POST /form/{formId}/generateEntries.

Method 3: share a template link

A template entry holds values that every person who opens its link starts with, such as your company's details. Each opening starts a new entry, and the template itself doesn't change. Create one with POST /entry/template:

curl -X POST "https://api.tepez.co.il/v1.0/entry/template?createShortUrl=true" \
  -H "x-api-key: $TEPEZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"form": "<formId>", "data": {"position": "qa", "address": {"city": "Haifa"}}}'

{
  "formId": "<formId>",
  "entryId": "<templateEntryId>",
  "shortUrl": "https://tpz.link/<code>"
}

Share shortUrl, or the template's full link, https://app.tepez.co.il/c/<templateEntryId>/. Both are safe to publish: they reveal only the template's values, and nobody can change the template through them.

To add per-person values on top of the shared ones, put data on the full link: https://app.tepez.co.il/c/<templateEntryId>/?data=…. It doesn't work on the short link, which drops the query string. Entries explains how to change a template later.

Troubleshooting

Errors explains the error format and lists more messages.

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