Options sets

An options set (מאגר אפשרויות) is a named list of options stored in Tepez. A select field can search it as the person types, and a field can check a value against it. Use one for a list too long to keep inside the form, or one your system updates, such as your branches or product codes. This page shows how to create a set, fill it and replace its options, and how to search and check values against it. It ends with the sets Tepez maintains for everyone.

What an options set holds

Each option has:

The API has no request that lists a set's options. You read them only by searching, with autocomplete.

List your sets

GET /optionsSet lists the sets of your account, and GET /optionsSet/{setId} returns one.

curl -G https://api.tepez.co.il/v1.0/optionsSet \
  -H "x-api-key: $TEPEZ_API_KEY" \
  --data-urlencode 'fields=["id","name"]'

{
  "data": [
    { "id": "<setId>", "name": "Branches" }
  ]
}

Create a set

POST /optionsSet creates an empty set. Keep its id: every other request takes it.

curl -X POST https://api.tepez.co.il/v1.0/optionsSet \
  -H "x-api-key: $TEPEZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Branches"}'

{
  "id": "<setId>",
  "name": "Branches",
  "account": "<accountId>",
  "createTime": "2026-09-30T16:09:19.836Z",
  "modifyTime": "2026-09-30T16:09:19.836Z"
}

Add options

POST /optionsSet/{setId}/addOptions adds options to the set:

curl -X POST https://api.tepez.co.il/v1.0/optionsSet/<setId>/addOptions \
  -H "x-api-key: $TEPEZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"options": [
    {"value": "Tel Aviv - Rothschild", "score": 30, "data": {"region": "center"}},
    {"value": "Tel Aviv - Ramat Aviv", "score": 20, "data": {"region": "center"}},
    {"value": "Haifa - Carmel", "score": 10, "data": {"region": "north"}}
  ]}'

{
  "message": "3 options where added to the set"
}

• A request body can be at most 5 MB (see Limits). Split a larger list over several requests.
• addOptions always adds. Sending an option that already exists adds a second copy, and both then appear in search results.

Replace all options

To update a set, delete all its options with POST /optionsSet/{setId}/deleteOptions, then add the current list again with addOptions. There is no request that changes or removes a single option.

curl -X POST https://api.tepez.co.il/v1.0/optionsSet/<setId>/deleteOptions \
  -H "x-api-key: $TEPEZ_API_KEY"

{
  "message": "3 options where deleted from the set"
}

Between the two requests the set is empty, so a person searching it at that moment finds nothing. Replace the options when few people are filling your forms. Search results are cached for up to a minute, so a change can take a minute to show.

Search a set

GET /optionsSet/{setId}/autocomplete returns the options that match what the person typed. It is public: it needs no API key, because the fill page calls it from the browser of whoever fills the form. GET /optionsSet/{setId}/autocomplete in the API reference lists its parameters. Its full URL is:

https://api.tepez.co.il/v1.0/optionsSet/<setId>/autocomplete

Results come in descending score order, with an option that equals term exactly moved to the top.

curl -G https://api.tepez.co.il/v1.0/optionsSet/<setId>/autocomplete \
  --data-urlencode 'term=aviv' \
  --data-urlencode 'query={"region":"center"}' \
  --data-urlencode 'limit=10'

{
  "data": [
    { "value": "Tel Aviv - Rothschild" },
    { "value": "Tel Aviv - Ramat Aviv" }
  ]
}

In a form, a select field points at this URL and passes what the person typed as term. A field that depends on another passes that field's value in query, as a street field passes the chosen city.

Check a value

GET /optionsSet/{setId}/validate answers whether the set contains an option with exactly this value. It is public too. GET /optionsSet/{setId}/validate in the API reference lists its parameters: value, and an optional query on data as in autocomplete.

curl -G https://api.tepez.co.il/v1.0/optionsSet/<setId>/validate \
  --data-urlencode 'value=Haifa - Carmel'

{ "isValid": true }

Unlike autocomplete, the match is exact, including case: haifa - carmel and Haifa both return {"isValid": false}. So does Haifa - Carmel with query={"region":"center"}, because that option's region is north.

Sets maintained by Tepez

Tepez maintains these sets, and any form can use them. Their autocomplete and validate endpoints are public, like those of any set.

• A country's code is its two-letter ISO 3166-1 code. The sets that include former countries, such as the Soviet Union, give those their four-letter ISO 3166-3 code. A country of birth is a typical use.
• The localities set holds one copy of the list for each tax year, so filter it by year. Until the Israel Tax Authority publishes the list for a new year, that year has a copy of the previous year's list.
• Cities come in order of their number of streets, and banks in order of their number of branches, so the larger ones come first in search results.

Tepez refreshes these sets from their sources every night:

Chain related sets

Some of these sets are related: the option picked in one set filters the next, as a city filters its streets. Each pair is linked by a data key or the value of the second set:

Autocomplete returns only each option's value, not its data, so the key you pass in query comes from the picked value itself. The examples below call the API. To do the same in a form, see Filter one field by another in a form.

Streets of a city

A street option's city is the city's name exactly as in the cities set, so pass the picked city as it is:

curl -G https://api.tepez.co.il/v1.0/optionsSet/572085e38b59b1ba2ebcec37/autocomplete \
  --data-urlencode 'term=הרצל' \
  --data-urlencode 'query={"city":"חיפה"}' \
  --data-urlencode 'limit=3'

{
  "data": [
    { "value": "הרצל" },
    { "value": "גרינשפון הרצל" },
    { "value": "הרצליה" }
  ]
}

validate takes the same query. This checks a street in a city:

curl -G https://api.tepez.co.il/v1.0/optionsSet/572085e38b59b1ba2ebcec37/validate \
  --data-urlencode 'value=וולפסון' \
  --data-urlencode 'query={"city":"תל אביב - יפו"}'

{ "isValid": true }

Branches of a bank

A branch's bankCode is its bank's code, and a bank option ends with that code: בנק לאומי לישראל בע"מ | 10. Pass the code to the branches set as a number, {"bankCode":10}. As a string, {"bankCode":"10"}, it matches nothing.

curl -G https://api.tepez.co.il/v1.0/optionsSet/572085f78b59b1ba2ebcec39/autocomplete \
  --data-urlencode 'term=דיזנגוף' \
  --data-urlencode 'query={"bankCode":10}'

{
  "data": [
    { "value": "לב דיזנגוף | 806 | המלך ג'ורג' 61" }
  ]
}

The English sets use the same bank and branch codes. A bank picked as Bank Leumi Le-Israel B.M | 10 filters the English branches the same way:

curl -G https://api.tepez.co.il/v1.0/optionsSet/69118f158ee85ad8699bad02/autocomplete \
  --data-urlencode 'term=dizengoff' \
  --data-urlencode 'query={"bankCode":10}'

{
  "data": [
    { "value": "lev dizengoff | 806 | King George 61" }
  ]
}

The English name of a city

Each option in the English cities set carries the Hebrew name in heName, exactly as in the cities and streets sets. To find the English name of a picked city, filter by heName and leave out term:

curl -G https://api.tepez.co.il/v1.0/optionsSet/68fa39777677886065ba1331/autocomplete \
  --data-urlencode 'query={"heName":"תל אביב - יפו"}'

{
  "data": [
    { "value": "Tel Aviv - Yafo" }
  ]
}

The link works only in this direction. A city picked from the English set gives you just its English name, not its heName, so it can't filter the streets set. To ask for a city and its street, use the Hebrew cities set.

Localities that qualify for a tax credit

A locality in this set has the same name as in the cities set, so check the picked city with validate, and pass the tax year in query. This checks Ashkelon for 2026. With {"year":2025} the answer is {"isValid": false}, because Ashkelon is on the 2026 list and not on the 2025 one:

curl -G https://api.tepez.co.il/v1.0/optionsSet/5995a5ff13f09a4176c10d2a/validate \
  --data-urlencode 'value=אשקלון' \
  --data-urlencode 'query={"year":2026}'

{ "isValid": true }

Filter one field by another in a form

A select field (fSelect) can take its options from a set as the person types: give it remote options, the set's autocomplete URL and a qs expression for the query string. To filter it by another field, build query from that field's value. In the form builder, these are the field's options source Remote (AJAX), in Hebrew משירות חיצוני (AJAX), with its URL and query string.

These two fields ask for a city, then for a street in that city:

[
  {
    "type": "fSelect",
    "name": "city",
    "label": "City",
    "options": {
      "url": "https://api.tepez.co.il/v1.0/optionsSet/572078298b59b1ba2ebcd824/autocomplete",
      "qs": "{ term: term, limit: 10 }"
    }
  },
  {
    "type": "fSelect",
    "name": "street",
    "label": "Street",
    "readonly": "!model.city",
    "options": {
      "url": "https://api.tepez.co.il/v1.0/optionsSet/572085e38b59b1ba2ebcec37/autocomplete",
      "qs": "{ term: term, limit: 10, query: fn.JSON.stringify({ city: model.city || '' }) }"
    },
    "validators": [
      {
        "type": "remote",
        "req": {
          "url": "https://api.tepez.co.il/v1.0/optionsSet/572085e38b59b1ba2ebcec37/validate",
          "qs": "{ value: value, query: fn.JSON.stringify({ city: model.city || '' }) }"
        },
        "res": "res.data.isValid",
        "message": "This street is not in the city you chose"
      }
    ]
  }
]

• qs is an expression that returns the query string's parameters. In it, term is what the person has typed, value is the field's own value, and model.city is the value of the city field. A field inside a section with "secFlat": false has a longer path, such as model.address.city (see Data paths).
• fn.JSON.stringify turns the filter into the JSON text that query takes. The || '' matters: with no city picked, {"city":""} matches no street, while an empty filter would match every street in Israel.
• readonly keeps the street field locked until a city is picked.
• When the person changes the city, the form clears the street they picked, and the street field then searches the new city's streets.
• The form doesn't check on its own that a value came from the set, so a prefilled entry or one submitted through the API can hold any street. The remote validator checks the street against the chosen city with validate, both in the browser and on the server when the entry is submitted. A mismatch fails the submit with 400 entry_failed_validation, and the response's messages give the field's path with the validator's message.
• Always set "res": "res.data.isValid". Without res, the validator reads data.isValid, which is the form's data rather than the response, so it never fails.

For a bank and its branches, the bank field is the same as the city field with the banks set's id, 572085eb8b59b1ba2ebcec38. The branch field changes these lines:

{
  "name": "branch",
  "readonly": "!model.bank",
  "options": {
    "url": "https://api.tepez.co.il/v1.0/optionsSet/572085f78b59b1ba2ebcec39/autocomplete",
    "qs": "{ term: term, limit: 10, query: fn.JSON.stringify({ bankCode: fn.toNumber(fn.last(fn.split(model.bank, '|'))) }) }"
  }
}

fn.split, fn.last and fn.toNumber take the number after the last | of the bank's value, as a number. Its validator's req uses the same query with the branches set's validate URL. For the English banks and branches, use their ids, 69118f2309579720694216ad and 69118f158ee85ad8699bad02.

Troubleshooting

Errors explains the error format and lists more messages.

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