Campaigns¶

A campaign defines the channel feedback requests go out on, the metric and grading scale, the texts, and the custom fields. The campaign endpoints export the campaigns of your account with their statistics, and break the statistics down by custom field value.

Campaigns in the Draft status are not returned. Feedback requests are exported separately; see Feedback requests.

List campaigns¶

GET /appeals/campaigns returns the campaigns of your account.

GET https://app.instantfeedback.si/api/appeals/campaigns?type=sms&type=widget&stats_from=2026-01-01

Parameters are sent in the URL, as in the example.

Parameter	Required	Format	Meaning
`type`	No	string	Campaign channel: `sms`, `email`, `mixed`, `widget`, or `external`. Repeat the parameter to select several channels.
`metric`	No	string	Campaign metric: `avg`, `csat`, `nps`, or `survey`. Repeat the parameter to select several metrics.
`stats_from`	No	`YYYY-MM-DD`	Counts only feedback requests scheduled on or after this date in `stats`.
`stats_to`	No	`YYYY-MM-DD`	Counts only feedback requests scheduled up to and including this date in `stats`.

Example response:

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [{
        "id": 15,
        "type": "email",
        "metric": "csat",
        "name": "Customer support – after a closed ticket",
        "grade_list": [1, 2, 3, 4, 5],
        "send_from": "08:00:00",
        "send_until": "20:00:00",
        "send_delay": null,
        "custom_fields": [{
            "name": "Service type",
            "field_type": "Choice",
            "required": false,
            "choices": ["Development", "Support"]
        }],
        "stats": {
            "csat_index": 79,
            "appeals_total": 100,
            "appeals_graded": 68,
            "appeals_commented": 23,
            "average_grade": 4.176470588235294,
            "grade_counts": {
                "1": 2,
                "2": 4,
                "3": 8,
                "4": 20,
                "5": 34
            }
        }
    }]
}

Field	Meaning
`id`	Campaign ID.
`type`	Campaign channel: `sms`, `email`, `mixed` (SMS and email), `widget` (web widget), or `external` (your own channel).
`metric`	Campaign metric: `avg` (average grade), `csat`, `nps`, or `survey` (survey only, no grade).
`name`	Campaign name.
`grade_list`	The grades of the campaign's scale, in order. Empty for survey-only campaigns.
`send_from`	Time of day from which feedback requests are sent, as `HH:MM:SS`. The account's setting when the campaign has none of its own.
`send_until`	Time of day until which feedback requests are sent.
`send_delay`	Minutes to wait before sending a feedback request that has no explicit scheduled date, or `null`.
`custom_fields`	The custom fields defined on the campaign, one object per field; see the next table.
`stats`	Feedback request statistics for the campaign; see the table below.

Each entry of custom_fields has these fields:

Field	Meaning
`name`	Field name. Use it as `name` when you send custom field values with a new feedback request.
`field_type`	`Text`, `Integer`, `Date`, `Time`, `Date and time`, `Yes/No`, `Choice`, or `URL address`.
`required`	Whether a value is required when creating a feedback request.
`choices`	The possible values of the field. Filled for fields of type `Choice`, an empty list for other types.

The stats object has these fields:

Field	Meaning
`csat_index`	CSAT index in percent. Only for campaigns with metric `csat`.
`nps_index`	Net Promoter Score. Only for campaigns with metric `nps`.
`appeals_total`	Number of feedback requests.
`appeals_graded`	Number of graded feedback requests.
`appeals_commented`	Number of feedback requests with a comment.
`average_grade`	Average grade.
`grade_counts`	Number of graded feedback requests per grade, keyed by grade.

Get a campaign¶

GET /appeals/campaigns/:id returns one campaign, in the same shape as an entry of the campaigns list.

GET https://app.instantfeedback.si/api/appeals/campaigns/15?stats_from=2026-01-01&stats_to=2026-06-30

Parameter	Required	Format	Meaning
`stats_from`	No	`YYYY-MM-DD`	Counts only feedback requests scheduled on or after this date in `stats`.
`stats_to`	No	`YYYY-MM-DD`	Counts only feedback requests scheduled up to and including this date in `stats`.

A campaign that does not exist in your account, or is still a draft, returns HTTP 404.

Custom field statistics¶

GET /appeals/custom-fields returns the average grade and the number of feedback requests for each value of each custom field of a campaign. Only fields with Show in report enabled on the campaign are included.

GET https://app.instantfeedback.si/api/appeals/custom-fields?campaign=15&date_from=2026-01-01

Parameter	Required	Format	Meaning
`campaign`	Yes	integer	Campaign ID.
`date_from`	No	`YYYY-MM-DD`	Only feedback requests scheduled on or after this date.
`date_to`	No	`YYYY-MM-DD`	Only feedback requests scheduled up to and including this date.
`changed_since`	No	`YYYY-MM-DD`	Only feedback requests whose grade changed on or after this date.

Example response:

[{
    "id": 47,
    "name": "Service type",
    "values": [{
        "value": "Support",
        "count": 102,
        "average_grade": 4.5
    }, {
        "value": "Development",
        "count": 38,
        "average_grade": 4.1
    }]
}]

The response is a plain array, without the paging envelope.

Field	Meaning
`id`	Custom field ID.
`name`	Custom field name.
`values`	One entry per value entered for the field, with the `value` itself, `count` (number of feedback requests with that value), and `average_grade`. Values are ordered by average grade, highest first.

Troubleshooting¶

Message or symptom	What to do
Parameter "campaign" is required.	`GET /appeals/custom-fields` needs `?campaign=<id>` in the URL.
No Campaign matches the given query.	The campaign ID does not exist in your account, or the campaign is a draft.
Select a valid choice. ... is not one of the available choices.	The `type` or `metric` parameter has a value outside the lists above.
An expected custom field is missing from the statistics.	Enable Show in report for the field in the campaign's custom field settings.
`custom_fields` of a campaign is empty.	The campaign has no custom fields. Fields are added per campaign in the campaign's settings.