Feedback requests¶

A feedback request is one request for a grade sent to one contact through a campaign. The API calls them appeals in its paths. These endpoints export the feedback requests of a campaign, create new ones from your systems, record grades and comments your own channel collected, and cancel requests that have not been sent yet.

Every feedback request has a type and a status:

List feedback requests¶

GET /appeals/ exports the feedback requests of one campaign. Note the trailing slash.

GET https://app.instantfeedback.si/api/appeals/?campaign=17&date_from=2026-01-01&date_to=2026-01-31

Feedback requests deleted in the web app are not returned.

Example response:

{
    "count": 65,
    "next": null,
    "previous": null,
    "results": [{
        "id": 1637,
        "type": "sms",
        "status": "Graded",
        "phone": "+38641279757",
        "text": "Thank you for your purchase! Rate your experience from 1 to 5.",
        "date_created": "2026-01-03T15:34:10.442726+01:00",
        "date_scheduled": "2026-01-03T16:12:10.442726+01:00",
        "date_graded": "2026-01-04T16:39:10.442726+01:00",
        "date_commented": null,
        "grade": 4,
        "comment": "",
        "custom_fields": [{
            "name": "Service type",
            "value": "Development"
        }]
    }]
}

phone, email, identifier, and subject are left out of a record when they have no value.

Get a feedback request¶

GET /appeals/:id returns one feedback request. It has the same fields as an entry of the list, plus the campaign it belongs to.

GET https://app.instantfeedback.si/api/appeals/1637

{
    "id": 1637,
    "campaign": {
        "id": 17,
        "name": "Webshop – after order pickup"
    },
    "type": "sms",
    "status": "Graded",
    "phone": "+38641279757",
    "text": "Thank you for your purchase! Rate your experience from 1 to 5.",
    "date_created": "2026-01-03T15:34:10.442726+01:00",
    "date_scheduled": "2026-01-03T16:12:10.442726+01:00",
    "date_graded": "2026-01-04T16:39:10.442726+01:00",
    "date_commented": null,
    "grade": 4,
    "comment": "",
    "custom_fields": []
}

Create a feedback request¶

POST /appeals/create creates a feedback request in a campaign. Send the data as JSON in the request body.

POST https://app.instantfeedback.si/api/appeals/create

{
    "campaign": 17,
    "phone": "+38641279757",
    "date_scheduled": "2026-03-21T12:35:00+01:00",
    "custom_fields": [{
        "name": "Service type",
        "value": "Development"
    }]
}

The type of the new feedback request follows the campaign's channel:

• SMS campaigns need phone, email campaigns need email.
• SMS and email campaigns take either: the request is sent as an SMS when you send phone, and as an email when you send email.
• Web campaigns need no contact. The response contains the iframe code of the feedback widget for this request, so a grade given in that widget lands on this request.
• External campaigns need identifier. The response contains the campaign's texts, so your channel can show them to the customer; report the answer with Record a grade and Record a comment.

Custom field values are checked against the field type: a Choice field accepts one of its choices, a Text field a string, other types a value in the field's format. Fields marked as required on the campaign must be present and not empty.

On success the response is HTTP 201 with the feedback request, in the same shape as Get a feedback request. Two campaign channels add a field:

"widget": {
    "iframe": "<iframe id=\"pskwidget-24\" class=\"pskwidgetframe\" width=\"100%\" height=\"400\" src=\"https://app.instantfeedback.si/widgets/feedback/...\" frameBorder=\"0\" scrolling=\"no\"></iframe>"
}

"texts": {
    "initial": "How satisfied were you with our service? Rate it from 1 to 5.",
    "replies": {
        "1": "We are sorry to hear that. What went wrong?",
        "5": "Thank you! What did you like most?"
    },
    "final": "Thank you for your feedback.",
    "instructions": null,
    "disclaimer": null
}

A request that InstantFeedback refuses to create returns HTTP 400 with the reason in detail:

Errors in custom field values come back under custom_fields, one object per field with name and detail, for example Field does not exist., Field is required., Value can not be empty., or 'X' is not a valid value. Choices are: Development, Support..

Record a grade¶

POST /appeals/:id/grade records a grade on a feedback request that is waiting for one, that is in the Request status. Use it when your own channel collected the grade, typically in an external campaign.

POST https://app.instantfeedback.si/api/appeals/1802/grade

{
    "grade": 4,
    "date_graded": "2026-03-21T13:02:00+01:00"
}

InstantFeedback processes the grade like one received through its own channels, so notifications and integrations fire as usual. The response is HTTP 200:

{
    "id": 1802,
    "status": "Graded",
    "grade": 4,
    "date_graded": "2026-03-21T13:02:00+01:00",
    "texts": {
        "reply": "Thank you! What did you like most?",
        "final": "Thank you for your feedback."
    }
}

texts.reply is the campaign's reply for this grade, with variables filled in, and texts.final the final text or null. Show them to the customer when your channel handles the conversation.

Record a comment¶

POST /appeals/:id/comment records a comment on a graded feedback request. It is allowed in the Comment request and Commented statuses; for external feedback requests also in the Graded status. A second comment is appended to the first on a new line.

POST https://app.instantfeedback.si/api/appeals/1802/comment

{
    "comment": "Fast delivery, friendly courier."
}

The response is HTTP 200:

{
    "id": 1802,
    "status": "Commented",
    "comment": "Fast delivery, friendly courier.",
    "date_commented": "2026-03-21T13:04:12.310021+01:00",
    "texts": {
        "final": "Thank you for your feedback."
    }
}

Cancel a feedback request¶

POST /appeals/:id/cancel cancels the sending of one feedback request. This is only possible while the status is Scheduled.

POST https://app.instantfeedback.si/api/appeals/1802/cancel

The response is HTTP 200 with the new status:

{
    "id": 1802,
    "status": "Canceled"
}

A request that is no longer scheduled returns HTTP 400:

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

Troubleshooting¶