Choices By URL Schema

Use choicesByUrl when a choice-based question should load choices from an external JSON endpoint.

Prefer static choices when options are known at design time. Use choicesByUrl only when the list must stay dynamic.

Minimal Shape

{
  "url": "https://example.com/api/departments",
  "valueName": "id",
  "titleName": "name"
}

Properties

url

• Type: string
• Required: Yes

Endpoint that returns choice data. The URL can include dynamic text placeholders such as {region} so choices reload when referenced answers change.

valueName

• Type: string

Field name from each returned item to use as the stored choice value.

titleName

• Type: string

Field name from each returned item to use as the visible choice label.

imageLinkName

• Type: string

Field name from each returned item to use as an image URL. Use this for imagepicker choices loaded from a remote endpoint.

path

• Type: string

Path to the array inside the response object. Use this only when the endpoint returns an object and the choices array is nested inside it.

allowEmptyResponse

• Type: boolean

Allows the endpoint to return no choices without treating it as an error.

attachData

• Type: boolean

Stores the original returned item on the generated choice item. Use this only when downstream code needs access to extra fields from the remote item.

Example

{
  "type": "dropdown",
  "name": "country",
  "title": "Country",
  "choicesByUrl": {
    "url": "https://example.com/countries.json",
    "path": "items",
    "valueName": "code",
    "titleName": "label"
  }
}

Dynamic URL Example

{
  "type": "dropdown",
  "name": "city",
  "title": "City",
  "choicesByUrl": {
    "url": "https://example.com/api/cities?country={country}",
    "path": "items",
    "valueName": "id",
    "titleName": "name",
    "allowEmptyResponse": true
  },
  "visibleIf": "{country} notempty"
}

Image Picker Example

{
  "type": "imagepicker",
  "name": "product",
  "title": "Select a product",
  "choicesByUrl": {
    "url": "https://example.com/api/products",
    "path": "items",
    "valueName": "sku",
    "titleName": "label",
    "imageLinkName": "imageUrl"
  }
}

Generation Notes

• Prefer static choices when the list is known at design time.
• Use dynamic text placeholders in url only for dependencies that should reload the choice list.
• Use valueName for stable stored values and titleName for respondent-facing labels.
• Use path when the response shape is { "items": [...] } rather than a raw array.
• Use allowEmptyResponse for dependent dropdowns where a valid filter may return no choices.