Accessing the Return API

The Return API allows you to query your feedback and return appropriate information for:

• Live feedback details - e.g. feedback ID, date created, customer contact details, etc.

• Deleted feedbacks - e.g. feedback ID, date deleted, person who deleted the feedback, etc.

Before making a request through the API, you must authenticate your credentials. Once authorised, you can view your response data.

Note: The Return API only retrieves feedback information, i.e. responses, not solicitations, i.e. questions. The feedback data may contain some metadata that has been copied from the solicitation request., e.g. case ID or agent name.

Authentication

The API uses HTTP Basic authentication. For all of the API requests, any variables are marked in <red>.

You can access the API from the following URL where you will be prompted to provide your user credentials: https://<eu-app.rantandrave.com>/RapideIntegration/feedback-details.

curl https://eu-app.rantandrave.com/RapideIntegration/feedback-details?query=score:3 \

-u <username>:<password>

Note: In the event the user passes an invalid data expression, HTTP 400 status will be returned.

API Credentials and System User Accounts

Access to the Return API requires a System User account — a dedicated account type within the Rant & Rave platform created specifically for machine-to-machine integrations. System User credentials are not shared with interactive user accounts and are managed independently.

System User credentials are provided securely during onboarding. Each integration can be issued its own unique System User account, ensuring credential isolation between systems.

Your credentials are used in every API request via the HTTP Authorization header:

Authorization: Basic <base64(username:password)>

All API communication is encrypted in transit using TLS 1.2.

Note: API access must be enabled on your System User account by Mobile Commons during provisioning. If your credentials are valid but you receive an HTTP 403 response, please contact Support to confirm that API access has been correctly configured for your account.

Data Access & Permission Scoping

The Return API supports two levels of data access control on System User accounts:

Field-level access: A System User account is configured to return only the specific data fields relevant to the integration. Fields that have not been granted will not appear in responses, regardless of what is queried. To adjust the fields available, contact Support.

Record-level access (data expressions): A System User account may be configured with a data expression — a filter that restricts which feedback records the integration can retrieve. For example, the account's access may be scoped to feedback from a specific region, team, or product line.

Contact your Customer Success Manager or Support to review or adjust the data access configured for your integration.

Making a request

The following table lists the parameters for this service using the Simple API:

*When using the enhanced API query string the from and to in the above Simple table are not mandatory

The following table lists the parameters for this service using the Enhanced API:

Lucene parse functionality

The API utilizes a Lucene parser. This enables you to chain different fields together such as age and gender.

Example: https://<eu-app.rantandrave.com>/RapideIntegration/feedbackdetails?query=age:[25 TO 30] AND gender:MALE&page=1.

Limitations

Please be aware that you are not able to query the following:

• Id on the feedback table

• Categories

• Insights

When using the extending functionality to search for text items, there is some formatting that needs to be adhered to in order for this to work. If the string item contains one element, then you can enter this into the query string as normal, but if the item contains multiple elements, then you will need to wrap the string in double quotes.

Response data

The returned data is in XML and contains all the columns that you would see in the dashboard plus the insights and categories within the verbatim that have been found by the sentiment engine.

Note: Please be advised that notes are also returned by the API.

The available items of feedback based on your date parameters are paginated into pages of 100 items of feedback. You need to pass in the page number as described above starting at page=1 and incrementing page by 1. The maximum page number is determined when the returned XML has no feedback-item nodes in the returned XML.

The data you retrieve will depend on the endpoint used and the query entered. For more information, refer to our examples of queries using the return API.

For guidance on storing, rotating and revoking your API credentials, see API Security and Technical Reference.

Query Argument

Queries should be written in Lucene Query Syntax. To learn more, click the link.

The queries should be encoded properly. Users can specify any column on the feedback table and return data from that column.

Example: Column: Data (e.g. Age:25)

For Date Ranges, you have to wrap your date expression in square brackets and include T before time portion of the dateTime, e.g. [2017-01-01 T00:00:00 TO 2017-01-01 T00:00:00].

Example: ?query=updated:[2017-01-01 T00:00:00: TO 2017-01-31 T00:00:00]

This will return all data on the updated column that is from the 1st of Jan to the 31st using the Return API to return date ranges in a greater than/less than syntax.

For DateTime ranges, the lucene parser does not handle the less than (<) or greater than (>) symbols. You will need to use the following syntax. So you need to use wildcards to state if you want data greater than or less than a desired range.

Example: (Requires to be URL encoded) ?query=updated:[* TO 2017-01-01 T00:00:00]

Example: ?query=updated%3A%5B*%20TO%202017-01-01%20T00%3A00%3A00%5D

This will return all data up to and including the desired date. If you would like to return data greater than a desired date, you need to swap the wildcard with the datetime.

Example: (Requires to be URL encoded): ?query=updated:[2017-01-01 T00:00:00 TO *]

Example: ?query=updated%3A%5B2017-01-01%20T00%3A00%3A00%20TO%20*%5D

Examples of Query Usage:

• http://localhost:8083/RapideIntegration/feedback-details?query=gender:FEMALE

• http://localhost:8083/RapideIntegration/feedback-details?query=age%3E39

• http://localhost:8083/RapideIntegration/feedback-details?query=gender:FEMALE%20OR%20MALE

• Query: Updated: [2017-10-04T00:00:00 TO 2017-12-04T23:59:59]

  • http://localhost:8083/RapideIntegration/feedback-details?query=updated%3A%20%5B2017-10-04T00%3A00%3A00%20TO%202017-12-04T23%3A59%3A59%5D

You also have access to some fields on the notes object. A user can query any item that has had a note added within a time period using a query like this:

• Query: query=(notes.time:[2019-02-28T15:00:00 TO 2019-03-01T15:00:00])

  • https://localhost:8083/RapideIntegration/feedback-details?query=(notes.time%3A%5B2019-02-28T15%3A00%3A00%20TO%202019-03-01T15%3A00%3A00%5D)

Below is an example response with a series of tables explaining each object that is returned:

<?xml version="1.0" encoding="UTF-8"?>

<feedback-items>

<feedback-item id="1001">

<message>The message</message>

<sentiment-score>3</sentiment-score>

<channel>SMS</channel>

<structured-fields>

<structured-field>

<name>loyalty_card_number</name>

<value>123456</value>

</structured-field>

<structured-field>

<name>given_score</name>

<value>6</value>

</structured-field>

</structured-fields>

<categories>

<category>People</category>

<category>Process</category>

<category>Product</category>

<category>Place</category>

</categories>

<insights>

<insight>

<category>People</category>

<sentiment-score>1</sentiment-score>

</insight>

</insights>

<notes>

<note>

<id>1</id>

<username>Bob</username>

<created>2012-12-11 09:00:00</created>

<content>The customer was happy</content>

</note>

</notes>

</feedback-item>

</feedback-items>

Output

Feedback-item

Structured field

The number of structured fields returned is dependent on the fields the API user is configured to be able to access and the fields that are available on the project.

All fields are returned as a string type with the exception of the original text type. This type is returned as base64 encoded string to better facilitate the transfer of data into systems that might not be able to handle non-ASCII characters.

Insight

Note