Skip to content

InstantFeedback API User Guide

 

1. General instructions for using the Instant Feedback API

The Instant Feedback API (hereinafter the API) is available at https://app.instantfeedback.si/api (production) and https://test.instantfeedback.si/api (test).

The API works only over the secure HTTPS protocol. Using the HTTP protocol is not possible and may cause unexpected errors when using the API.

Make sure you are using the HTTPS protocol.

1.1 Authorization

To use the API, you need an API Token, which you can find under the user settings in the web application.

Every API request must include the Authorization header parameter, containing the word Token followed by a space and then your API Token.

Example

Authorization: Token 5094fe531509048213ccffea2363104a655f1d5c

1.2 Data exchange

Data exchange between your system and the API, for both import and export, uses the JSON format, so the Content-Type header parameter with the value application/json must be added.

Successful requests return HTTP status code 200.

1.3 Limits on data export

On export, the number of returned records is limited to 1000 per request. However, the API returns data in a form that makes it easy to retrieve the next or previous set (page) of records when the total number of records exceeds 1000.

Data returned on export always contains the following fields

{
    "count": 0,
    "next": null,
    "previous": null,
    "results": []
}

  • count: Number of returned results.

  • next: When available, the full URL of the next set (page) of results, otherwise null.

  • previous: When available, the full URL of the previous set (page) of results, otherwise null.

  • results: Contains the query results.

 

2. API documentation

2.1 GET /appeals/campaigns

Returns data about the campaigns of the user's organization.

Example API call

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

Parameters

Parameters are sent as part of the URL, as shown in the example above.

  • type: Campaign type

    Required: No
    Possible values: sms, email, mixed, widget, external
    Multiple choice: Yes

  • metric: Metric type

    Required: No
    Possible values: avg, csat, nps
    Multiple choice: Yes

  • stats_from: Limits the statistics to feedback requests sent on or after the selected date.

    Required: No
    Format: 'YYYY-MM-DD'
    Example: '2015-03-21'

  • stats_to: Limits the statistics to feedback requests sent up to the selected date.

    Required: No
    Format: 'YYYY-MM-DD'
    Example: '2015-03-21'

Example response

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [{
        "id": 2,
        "type": "sms",
        "name": "Test 1",
        "grade_list": [1, 2, 3, 4, 5],
        "send_from": null,
        "send_until": null,
        "send_delay": null,
        "is_active": true,
        "custom_fields": [{
            "id": 15,
            "name": "Service type",
            "field_type": "Choice",
            "required": false,
            "choices": ["Development", "Support"]
        }],
        "stats": {
            "appeals_total": 17,
            "appeals_graded": 11,
            "appeals_commented": 9,
            "average_grade": 4.09,
            "grade_counts": {
                "1": 1,
                "2": 0,
                "3": 2,
                "4": 2,
                "5": 6
            }
        }
    }]
}

  • id: Campaign ID.

  • type: Campaign type.

    Possible values: sms, email, mixed, widget

  • name: Campaign name.

  • send_from: Time of day from which feedback requests for this campaign are sent.

  • send_until: Time of day until which feedback requests are sent.

  • send_delay: Send delay.

  • is_active: Whether the campaign is active.

  • custom_fields: List of custom fields defined on the campaign.

    For each field it contains the following data:

    • name: Field name.

    • field_type: Field type.

      Possible values: Text, Integer, Date, Time, Date and time, Yes/No, Choice, URL address

    • required: Whether the field is required.

    • choices: Contains the list of possible values for the field.

      Only for fields of type Choice.

  • stats: Feedback request statistics for the campaign.

    Contains the following data:

    • appeals_total: Number of feedback requests sent.

    • appeals_graded: Number of graded feedback requests.

    • appeals_commented: Number of feedback requests with a comment.

    • average_grade: Average grade.

    • grade_counts: Number of feedback requests per grade.

 

2.2 GET /appeals/campaigns/:id

Returns data about a single campaign. The structure of the returned data is the same as the structure of a single campaign in the GET /appeals/campaigns query.

Example API call

GET https://app.instantfeedback.si/api/appeals/campaigns/2?stats_from=2023-01-01&stats_to=2023-07-01

Parameters

Parameters are sent as part of the URL, as shown in the example above.

  • stats_from: Limits the statistics to feedback requests sent on or after the selected date.

    Required: No
    Format: 'YYYY-MM-DD'
    Example: '2015-03-21'

  • stats_to: Limits the statistics to feedback requests sent up to the selected date.

    Required: No
    Format: 'YYYY-MM-DD'
    Example: '2015-03-21'

2.3 GET /appeals

Exports feedback request data. Returns data for the selected campaign.

Example API call

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

Parameters

Parameters are sent as part of the URL, as shown in the example above.

  • campaign: Campaign ID.

    Required: Yes

  • date_from: Limits the feedback requests to those sent on or after the selected date.

    Required: No
    Format: 'YYYY-MM-DD'
    Example: '2015-03-21'

  • date_to: Limits the feedback requests to those sent up to the selected date.

    Required: No
    Format: 'YYYY-MM-DD'
    Example: '2015-03-21'

  • changed_since: Limits the feedback requests to those whose grade was changed after the selected date.

    Required: No
    Format: 'YYYY-MM-DD'
    Example: '2020-07-01'

Example response

{
    "count": 30,
    "next": null,
    "previous": null,
    "results": [{
        "id": 1797,
        "type": "sms",
        "status": "Commented",
        "phone": "+00001010002",
        "text": "First appeal!",
        "date_created": "2015-01-01T08:48:00",
        "date_scheduled": "2015-01-01T08:48:00",
        "grade": 5,
        "comment": "comment",
        "custom_fields": [{
            "name": "Service type",
            "value": "Development"
        }]
    }]
}

  • id: Feedback request ID.

  • type: Feedback request type.

    Possible values: sms, email, widget

  • status: Feedback request status

    Possible values: Scheduled, Request, Retry, Invalid, Graded, Comment request, Commented, Error, Canceled, Survey request, Survey started, Survey completed

  • phone: Mobile number of the feedback request recipient (only for feedback requests of type "sms").

  • email: Email address of the feedback request recipient (only for feedback requests of type "email").

  • text: Text of the sent feedback request.

  • date_created: Date and time the feedback request was entered into the system.

  • date_scheduled: Date and time the feedback request is sent.

  • grade: Received grade, otherwise null.

  • comment: Received comment, otherwise null.

  • custom_fields: List of values for the campaign's custom fields.

    For each field it contains the following data:

    • name: Field name.

    • value: Field value.

 

2.4 GET /appeals/:id

Returns data about a single feedback request. The structure of the returned data is the same as the structure of a single feedback request in the GET /appeals query.

Example API call

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

 

2.5 POST /appeals/:id/cancel

Cancels the sending of a single feedback request. Only possible for feedback requests in the Scheduled status.
Returns the feedback request data if the cancellation succeeds, or HTTP status 400 if the cancellation is not possible.

Example API call

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

 

2.6 POST /appeals/create

Imports a feedback request into the Instant Feedback system. The feedback request data is sent in JSON format.

Example API call

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

{
    "campaign": 1,
    "phone": "+00001010002",
    "text": "First appeal!",
    "date_scheduled": "2015-01-01 08:48:00",
    "custom_fields": [{
        "name": "Service type",
        "value": "Development"
    }]
}

Parameters

  • campaign: Campaign ID

    Required: Yes

  • type: Feedback request type.

    Required: No
    Possible values: sms, email, widget
    Default: depends on the campaign type.

    Mixed campaigns (SMS + email) default to sms.

  • phone: Mobile number the feedback request will be sent to.

    Required: For feedback request type sms.

  • email: Email address the feedback request will be sent to.

    Required: For feedback request type email.

  • text: Feedback request text.

    Required: No
    Default: the text defined on the campaign

  • date_scheduled: Date and time to send the feedback request.

    Required: No
    Default: current date and time
    Format: 'YYYY-MM-DD HH:MM'
    Example: '2015-03-21 12:35'

  • custom_fields: List of values for custom fields.

    Required: when at least one of the custom fields is required

    For each custom field it must contain the following data:

    • name: Field name, as defined on the campaign

    • value: Field value

 

If the import succeeds, the request returns HTTP status code 200 and the data of the imported feedback request in JSON format. The feedback request data structure is the same as in the feedback request export query GET /appeals.

 

2.7 GET /appeals/custom-fields

Returns the average grade and the number of feedback requests for each custom field value on the selected campaign.

Example API call

GET https://app.instantfeedback.si/api/appeals/custom-fields/?campaign=1

Parameters

Parameters are sent as part of the URL, as shown in the example above.

  • campaign: Campaign ID.

    Required: Yes

  • date_from: Includes only grades received on or after the selected date.

    Required: No
    Format: 'YYYY-MM-DD'
    Example: '2015-03-21'

  • date_to: Includes only grades received up to and including the selected date.

    Required: No
    Format: 'YYYY-MM-DD'
    Example: '2015-03-21'

 

Example response

[{
    "id": 47,
    "name": "Custom field name",
    "values": [{
        "value": "Value 2",
        "count": 102,
        "average_grade": 5.0
    }] 
}]

  • id: Custom field ID.

  • name: Custom field name.

  • values: List of all entered values of the custom field.

    For each value it contains the following data:

    • value: Field value.

    • count: Number of feedback requests for the value

    • average_grade: Average grade.

 

2.8 GET /contacts/:contact

Method for retrieving data related to a single contact that is stored in the InstantFeedback system.

Example API call

GET https://app.instantfeedback.si/api/contacts/+00001010002

Example response

{
    "contact": "+00001010002",
    "avg_grade": 4.125,
    "num_appeals": 11,
    "num_feedback": 8,
    "last_appeal": "2018-03-18T14:00:00",
    "last_grade": "2017-08-18T14:18:56.842105",
    "last_comment": null,
    "appeals": [
        ...
    ],
    "blacklist": {
        "entry": "+00001010002",
        "date_added": "2018-02-25T12:24:21.501701"
    },
    "graylist": null
}

  • contact: The contact being queried. It can be a mobile number, an email address, or a session ID.

  • avg_grade: Average grade.

  • num_appeals: Number of feedback requests sent to the contact.

  • num_feedback: Number of responses received.

  • last_appeal: Date of the last feedback request sent.

  • last_grade: Date of the last grade received.

  • last_comment: Date of the last comment received.

  • appeals: List of all feedback requests sent to the contact.

    The structure of the returned data is the same as the structure of a single feedback request in the GET /appeals query.

  • blacklist: Indicates whether the contact is on the blacklist.

    Contains the following data:

    • entry: Contact.

    • date_added: Date the contact was added to the list.

  • graylist: Indicates whether the contact is on the graylist.

    Contains the following data:

    • entry: Contact.

    • campaigns: List of campaigns where the contact is on the graylist.

      For each campaign it contains the following data:

      • id: Campaign ID.

      • name: Campaign name.

      • date_added: Date the contact was added to the list.

 

2.9 POST /contacts/:contact/mask

Method for masking (anonymizing) data related to a single contact that is stored in the InstantFeedback system.

Example API call

POST https://app.instantfeedback.si/api/contacts/+00001010002/mask

Example response

{
    "contact": "+00001010002",
    "masked": {
        "appeals": 11,
        "blacklist": 1,
        "graylist": 1
    }
}

  • contact: The contact whose data was masked

  • masked: Indicates which data was masked and how much

    Contains the following data:

    • appeals: Number of masked feedback requests.

    • blacklist: Number of masked blacklist entries.

    • graylist: Number of masked graylist entries.

 

2.10 GET /contacts/:contact/access-log

Displays the audit trail of access to a single contact's data.

Example API call

GET https://app.instantfeedback.si/api/contacts/+00001010002/access-log

Example response

{
    "user": "User name",
    "action": "app-contact-list",
    "date_accessed": "2018-03-28T14:58:52.682913"
}

  • user: The InstantFeedback user who accessed the data.

  • action: Type and method of data access.

  • date_accessed: Date of access.