API overview¶

The InstantFeedback REST API gives your own systems access to the same campaigns, feedback requests, surveys, and contacts you see in the web app, as JSON over HTTPS. Use it to:

• Create feedback requests from your CRM, shop, or ticketing system, including values for the campaign's custom fields.
• Record grades and comments that your own channel collected, in an external campaign.
• Export campaigns with their statistics, and feedback requests with grades and comments.
• Get the average grade and number of feedback requests per custom field value, for example per store or per agent.
• Look up, anonymise, and audit the data stored about a single contact.

The paths in this reference are relative to the base URL.

Before you start¶

• You need an API key. Keys belong to the account, so a request made with a key sees that account's campaigns and data. Only account admins can create keys; see Get an API key.
• Use HTTPS only. The API is not available over plain HTTP, and HTTP requests can fail in unexpected ways.
• Send and expect JSON. Request bodies must be JSON, and every request with a body needs the Content-Type: application/json header. A body in another format, for example a form post, is rejected with HTTP 415.

Get an API key¶

1. Open Settings from the sidebar and click API keys. The page lists the account's keys with their expiry date and whether they are active.

1. Click Create, enter a name that tells you which system uses the key, and optionally an expiry date and time. Click Save.
2. Back in the list, click the key's name to open it.

1. Click Show to reveal the key and copy it into your system's configuration.

To take a key out of use, clear the Active switch on its page or delete it from the list. Requests made with an inactive, expired, or deleted key get HTTP 401.

Authentication¶

Every request carries the API key in the Authorization header: the word Token, a space, and the key.

Authorization: Token 5094fe531509048213ccffea2363104a655f1d5c

For example, with curl:

curl -H "Authorization: Token 5094fe531509048213ccffea2363104a655f1d5c" \
     https://app.instantfeedback.si/api/appeals/campaigns

A request without a valid key gets HTTP 401 and a JSON body that names the reason:

Responses and paging¶

Successful requests return HTTP 200, except creating a feedback request, which returns 201. Every response body is JSON.

Lists¶

Endpoints that return a list, that is campaigns, feedback requests, surveys, and a contact's access log, return at most 1000 records per request and wrap them in an envelope:

{
    "count": 2345,
    "next": "https://app.instantfeedback.si/api/appeals/?campaign=17&page=3",
    "previous": "https://app.instantfeedback.si/api/appeals/?campaign=17&page=1",
    "results": []
}

Pages are selected with the page parameter, starting at 1. The simplest way to read a whole export is to follow next until it is null.

Custom field statistics are the one list endpoint without the envelope: they return a plain JSON array.

Dates and times¶

Timestamps in responses are ISO 8601 with a UTC offset, in the account's time zone, for example 2026-01-03T16:12:10.442726+01:00. Date parameters use YYYY-MM-DD. A date and time you send without an offset is read in the account's time zone.

Paths¶

Paths are matched exactly. GET /appeals/ and GET /surveys/ end with a slash; every other path does not. A request to /appeals without the slash is redirected with HTTP 301, which not every HTTP client follows. A slash added to any other path returns HTTP 404.

Errors¶

Error responses carry a JSON body. Validation errors name the offending parameter, other errors use detail:

{"phone": ["This field is required."]}

{"detail": "This operation is only allowed for feedback requests with status 'Scheduled'."}

Endpoints¶