Query settings

Query settings let the user configure characteristics of a query — for example a reporting timezone, a currency, or a filter. They're defined per report type under a settings object, and the value the user selects becomes available in requests through the {{query.settings.<ID>}} placeholder.

Each setting is an item under settings.items:

Choosing a type

• Use select when the user picks from a set of known values, e.g. currency, device, or timezone. This is the most common and powerful type, and the only one that supports per-option parameters (see below).
• Use text (single-line) or textarea (multi-line) for free-form values the user types in.
• Use checkbox for a simple on/off toggle.

Static options

When the list of choices is fixed, define them with options:

"settings": {
  "items": [
    {
      "id": "currency",
      "label": "Currency",
      "type": "select",
      "isRequired": true,
      "options": [
        {
          "label": "EUR",
          "value": "EUR",
          "isDefault": true
        },
        {
          "label": "USD",
          "value": "USD"
        }
      ]
    }
  ]
}

The selected value is referenced in a request with {{query.settings.currency}} — for example as a query parameter:

{
  "name": "currency",
  "value": "{{query.settings.currency}}"
}

Attaching parameters to an option

Sometimes one setting selection needs to provide several different values, used in different places in the request — for example a timezone where the API wants both a timezone name in one field and a numeric timezone ID in another. Instead of encoding multiple values into the single value and splitting them apart later, give each option a set of named parameters (key/value pairs):

"settings": {
  "items": [
    {
      "id": "timezone",
      "label": "Timezone",
      "type": "select",
      "isRequired": true,
      "options": [
        {
          "label": "UTC",
          "value": "UTC",
          "isDefault": true,
          "parameters": [
            {
              "name": "timezone_name",
              "value": "UTC"
            },
            {
              "name": "timezone_id",
              "value": "11"
            }
          ]
        },
        {
          "label": "US/Central",
          "value": "US/Central",
          "parameters": [
            {
              "name": "timezone_name",
              "value": "US/Central"
            },
            {
              "name": "timezone_id",
              "value": "423"
            }
          ]
        }
      ]
    }
  ]
}

You then reference each value from the selected option independently — for example in a POST request body:

"request": {
  "method": "POST",
  "url": "https://api.example.com/report",
  "body": {
    "type": "json",
    "content": {
      "timezone": {
        "name": "{{query.settings.timezone.timezone_name}}",
        "id": "{{query.settings.timezone.timezone_id}}"
      }
    }
  }
}

How the placeholders resolve:

• {{query.settings.<id>}} — the selected option's required value attribute.
• {{query.settings.<id>.<parameter_name>}} — the value of a named parameter on the selected option.

Note: An option's value is always required. You can either reuse value as one of your values and reference it with {{query.settings.<id>}}, or set value to anything, leave it unused, and define all the values you actually need under parameters. The second approach is recommended when an option carries multiple values — it keeps each value explicit and separately addressable.

Dynamic options

When the available options can't be known in advance — for example a list of the user's own clients or currencies — use dynamicOptions instead of options. Each defines a request that fetches the list of options, and an optionInfo that maps each returned item to a label and a value:

"settings": {
  "items": [
    {
      "id": "currency",
      "label": "Currency",
      "type": "select",
      "isRequired": true,
      "dynamicOptions": [
        {
          "request": {
            "url": "https://example.com/api/currencies",
            "response": {
              "dataRows": {
                "source": "jsonPath",
                "value": "$.items.*"
              }
            }
          },
          "optionInfo": {
            "label": {
              "source": "jsonPath",
              "value": "$.name"
            },
            "value": {
              "source": "jsonPath",
              "value": "$.id"
            }
          }
        }
      ]
    }
  ]
}

Note: Dynamic options are fetched at the connection level. The fetch request can use connection-level values such as the access token ({{user.access_token}}) and data source user properties, but it has no account in scope, so dynamic options can't be fetched per account. If your options depend on a specific account, they can't be loaded this way.