Introduction

Welcome to Relationwise’s API! You can use this API to send Relationwise your customer data so that we in turn can send surveys to your customers (Recipient/New), or extract respondent data (Recipient/List), or get a summary of results (Recipient/Summary).

The API is organized around REST. All requests should be made over SSL. All request and response bodies are encoded in JSON.

We’ve tried to make this documentation user-friendly and example-filled, but if you have any questions, please contact our support at support@relationwise.dk.

Authentication

The Relationwise API 4 uses an API key to authenticate requests. The API key is added as custom header called KEY in your request.
Headers
Required Header Description
Yes key Please login (top right) to view your API key.

Recipient/New

Push data to Relationwise on a transactional* basis when a customer experience (event) triggers a customer experience survey to be sent to the customer. For example, when an invoice is sent or a support ticket is closed, then your system pushes some data about the customer to our system, so that we can then send them a survey by email.

* Please try to avoid batching, this method accepts only a single customer for each request.
Resource
https://www.relationwise.com/rls/restapi4/recipient/new
Method
POST
Headers
Required Header Description
Yes key Please login (top right) to view your API key.
Yes Content-Type application/json
Body
                            
                            
                            
Responses
HTTP
status
code
Internal
message
code
Message
400 1001 In the request the "BODY" is empty or invalid.
400 1002 In the request the header "KEY" is missing or invalid.
400 1003 In the request the header "KEY" doesn't belong to an active customer, your license could be expired.
400 1004 In the request BODY the column "{0}" is associated to a variable that no longer exist in your RLS backend, your API template needs to be updated in order to process future requests correctly.
400 1005 In the request BODY the column "{0}" is associated to a custom question in your survey(s), your API template needs to be updated in order to process future requests correctly.
400 1006 In the request BODY the column "{0}" is missing or invalid.
400 1007 In the request BODY the column "{0}" is missing its corresponding column "{1}".
400 1008 In the request BODY the column "{0}" is missing its corresponding value for column "{1}".
400 1009 In the request BODY the column "{0}" is found more than once, each column name should be unique in your JSON array.
400 1010 In the request BODY the survey version value "{0}" provided doesn't correspond with any of the survey version values defined in your API template.
400 1011 In the request BODY the survey version value "{0}" provided corresponds to a survey version value defined in your API template however the version is no longer available in your backend, your API template needs to be updated in order to process future requests correctly.
400 1012 In the request BODY the survey version column "{0}" was not found.
400 1013 Survey version column was not found in your API template however survey version values are defined, your API template needs to be updated in order to process future requests correctly.
400 1014 Recipient does not match the conditions to be assigned to a survey version.
400 1015 Recipient "{0}" has been rejected because is currently unsubscribed.
400 1016 The request has been rejected because the respondent is within a "rest" period, a safety mechanism that prevents multiple sends to the same respondent.
400 1017 The maximum number of "{0}" successful "{1}" requests for this version has been reached.
400 1020 General request failure.
200 1018 The request was successful. The recipient {0} will receive a customer experience survey on {1}.
200 1019 The request was successful. The recipient {0} will receive a customer experience survey on {1}. Warning: The number of columns in your request don''t match the numbers of columns in your API template.
200 1021 The request was successful however the recipient "{0}" will not receive the survey until the survey is in "ACTIVE" mode, currently your survey is in "NOT IN SERVICE" mode.

Recipient/List

Returns information about recipients who completed the survey sorted by date of completion in descendent order (most recent first). Several filters may be applied to get specific recipient data. The results are paginated in order to provide a fast response. You can request any page and also set the number of rows per page (with a maximum of 100 rows per page) Only 1000 request per day are permitted for this method.
Resource
https://www.relationwise.com/rls/restapi4/recipient/list
Method
GET
Headers
Required Header Description
Yes key Please login (top right) to view your API key.
Querystring filters
Required Name Value Description
No page number The number of the page to be returned.

Example:
https://www.relationwise.com/rls/restapi4/recipient/list?page=2
No page-rows number The number of rows per page. The maximum is 100 rows per page.

Example:
https://www.relationwise.com/rls/restapi4/recipient/list?page-rows=25
No version-uid free text Returns recipients filtered by version.

Example:
https://www.relationwise.com/rls/restapi4/recipient/list?version-uid=UK
No score free text Returns recipients filtered by score(s). Value can be a single number (e.g. score=7), a range (e.g. score:0-6) or sequence of numbers (e.g. score=3,5,8).

Example:
https://www.relationwise.com/rls/restapi4/recipient/list?score=10
https://www.relationwise.com/rls/restapi4/recipient/list?score=0-6
https://www.relationwise.com/rls/restapi4/recipient/list?score=0,3,5
No received-from dd-MM-yyyy Returns recipients filtered by distribution date (if survey was sent since the provided date).

Example:
https://www.relationwise.com/rls/restapi4/recipient/list?received-from=14-01-2016
No received-to dd-MM-yyyy Returns recipients filtered by distribution date (if survey was sent until the provided date).

Example:
https://www.relationwise.com/rls/restapi4/recipient/list?received-to=25-05-2016
No completed-from dd-MM-yyyy Returns recipients filtered by date of complete (if survey was completed since the provided date).

Example:
https://www.relationwise.com/rls/restapi4/recipient/list?completed-from=14-01-2016
No completed-to dd-MM-yyyy Returns recipients filtered by date of complete (if survey was completed until the provided date).

Example:
https://www.relationwise.com/rls/restapi4/recipient/list?completed-to=25-05-2016
No identifier free text Returns recipients filtered by identifier. Email, phone number or global identifier can be provided (search coincidences).

Example:
https://www.relationwise.com/rls/restapi4/recipient/list?identifier=admin@company.com
https://www.relationwise.com/rls/restapi4/recipient/list?identifier=4588970076
No name free text Returns recipients filtered by name (search coincidences).

Example:
https://www.relationwise.com/rls/restapi4/recipient/list?name=John
No subscribed yes/no Returns recipients based on their subscription status.

Example:
https://www.relationwise.com/rls/restapi4/recipient/list?subscribed=yes
No created-from dd-MM-yyyy Returns recipients filtered by creation date (created since the provided date).

Example:
https://www.relationwise.com/rls/restapi4/recipient/list?created-from=14-01-2016
No created-to dd-MM-yyyy Returns recipients filtered by creation date (created until the provided date).

Example:
https://www.relationwise.com/rls/restapi4/recipient/list?created-to=25-05-2016
No variable-name free text Returns recipients that have a value for the provided variable.

Example:
https://www.relationwise.com/rls/restapi4/recipient/list?variable-name=country
No variable-value free text Returns all recipients that have the provided value for the variable name provided in the parameter variable-name. If variable-name parameter is not provided the request is invalid.

Example:
https://www.relationwise.com/rls/restapi4/recipient/list?variable-name=country&variable-value=Denmark
No variable-uid free text Returns all recipients that have the provided uid for the variable name provided in the parameter variable-name. If variable-name parameter is not provided the request is invalid.

Example:
https://www.relationwise.com/rls/restapi4/recipient/list?variable-name=country&variable-uid=DK
No user-actions yes/no If "yes" includes information related to user actions.

Example:
https://www.relationwise.com/rls/restapi4/recipient/list?user-actions=yes
No categorization yes/no If "yes" includes information related to categorization.

Example:
https://www.relationwise.com/rls/restapi4/recipient/list?categorization=yes
Successful response example
Labels inside hard brackets [] for variable uid/value pairs in the output indicate the original variable names used in the Recipient/New request JSON template (putting data into Relationwise). They are inserted in this example only as a helping guide to show how the output relates (maps) to the input. The reason that the output does not follow the same format is that getting data into Relationwise using Recipient/New must be super easy for newcomers to understand - we want fast adoption for our customers - and a flat list of variables is the easiest way. Once the data is inside Relationwise, we pair some of the variables together, for example, a department name (value) with a department code/ unique identifier (uid). This allows us to make some great integrity and performance gains inside Relationwise. This is why, when it comes to output of the data using the Recipient/List method, the JSON is formatted somewhat different from the input. We hope the hard brackets in the example code below help illustrate the connection between In and Out.
                                    
                                    
                                    
Responses
HTTP
status
code
Internal
message
code
Message
400 2001 In the request the header "KEY" is missing or invalid.
400 2002 In the request the header "KEY" doesn't belong to an active customer, your license could be expired.
400 2003 "PAGE" parameter value is invalid.
400 2004 "PAGE-ROWS" parameter value is invalid.
400 2005 "PAGE-ROWS" exceeds the maximum of {0}.
400 2006 "VERSION-UID" parameter value was not found.
400 2007 "SCORE" parameter value is invalid.
400 2008 "RECEIVED-FROM" parameter value is invalid. Format should be dd-mm-yyyy.
400 2009 "RECEIVED-TO" parameter value is invalid. Format should be dd-mm-yyyy.
400 2010 "COMPLETED-FROM" parameter value is invalid. Format should be dd-mm-yyyy.
400 2011 "COMPLETED-TO" parameter value is invalid. Format should be dd-mm-yyyy.
400 2012 "CREATED-FROM" parameter value is invalid. Format should be dd-mm-yyyy.
400 2013 "CREATED-TO" parameter value is invalid. Format should be dd-mm-yyyy.
400 2014 "SUBSCRIBED" parameter value is invalid.
400 2015 "VARIABLE-NAME" parameter value was not found.
400 2016 "VARIABLE-VALUE" parameter has been provided but VARIABLE-NAME parameter is missing or empty.
400 2017 "VARIABLE-UID" parameter has been provided but VARIABLE-NAME parameter is missing or empty.
400 2018 "USER-ACTIONS" parameter value is invalid.
400 2019 "CATEGORIZATION" parameter value is invalid.
200 2020 A JSON object containing the queried data. Internally our system will log the message "The request was successful."

Recipient/Summary

Returns statistics based on all existing respondent data or within a date range.
Resource
https://www.relationwise.com/rls/restapi4/recipient/summary
Method
GET
Headers
Required Header Description
Yes key Please login (top right) to view your API key.
Querystring filters
Required Name Value Description
No from dd-MM-yyyy Returns the statistics using data filtered from the provided date (if survey was sent since the provided date).

Example:
https://www.relationwise.com/rls/restapi4/recipient/summary?from=14-01-2016
No to dd-MM-yyyy Returns the statistics using data filtered from the provided date (if survey was sent until the provided date).

Example:
https://www.relationwise.com/rls/restapi4/recipient/summary?to=25-05-2016
No variable-name free text Returns recipients that have a value for the provided variable.

Example:
https://www.relationwise.com/rls/restapi4/recipient/summary?variable-name=country
No variable-uid free text Returns all recipients that have the provided uid for the variable name provided in the parameter variable-name. If variable-name parameter is not provided the request is invalid.

Example:
https://www.relationwise.com/rls/restapi4/recipient/summary?variable-name=country&variable-uid=DK
Responses
HTTP
status
code
Internal
message
code
Message
400 3001 In the request the header "KEY" is missing or invalid.
400 3002 In the request the header "KEY" doesn't belong to an active customer, your license could be expired.
400 3003 "FROM" parameter value is invalid. Format should be dd-mm-yyyy.
400 3004 "TO" parameter value is invalid. Format should be dd-mm-yyyy.
400 3005 "VARIABLE-NAME" parameter value was not found.
400 3006 "VARIABLE-VALUE" parameter has been provided but "VARIABLE-NAME" parameter is missing or empty.
400 3007 "VARIABLE-UID" parameter has been provided but "VARIABLE-NAME" parameter is missing or empty.
200 3008 A JSON object containing the queried data. Internally our system will log the message "The request was successful."

Sandbox explorer

Use this sandbox explorer to see the requests that have been made to the Relationwise API, both successful and failed. For the Recipient/New method you can view the data that has been sent to Relationwise via API. For failed requests we give a reason for the failure to help with your debugging.
API method
Time interval
From    To    
Chart

Statistics
No data available.