API Guide  (Transactional)
VIDEO DOC TEST FAQ VARS BEHAV

A. Start video

1Here is a short video exclusively made for explaining how to integrate to Relationwise:


B. Documentation
1 Purpose Push new survey recipient
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.
2 URL https://www.relationwise.com/rls/restapi3/new-recipient
3 Method POST
4 Header params Required
Content-Type = application/json
Key = (Please contact support@relationwise.dk for your API key)
5 Data params The body part of the request will be a JSON string containing a list of variables. A JSON string must be double-quoted. If you are using special characters in your JSON string, you will need to escape the characters using backslash (\). Please consult this introduction to JSON for more details.

Example: {
"name" : "customer's name",
"email" : "customer's email",
"employee-name" : "My description",
"employee-id" : "My description",
"division-name" : "div",
"division-id" : "div",
"product-name" : "the value",
"product-id" : "the identifier"
}

Optionally, you can provide the two specials variables "score" and "comments" in order to create recipients and set their answers. The score variable must be a value between 0 and 10 and the comments variable can contain any text.

example:
{
...
"score" : "9",
"comments" : "congratulations! really good service."
...
}


Rules:
  • If score is valid then score/comments are saved. Recipient, distribution and respondent are created. No emails are sent.
  • If score is not valid or not provided then the recipient and distribution are created and executed following the regular flow.
  • In any case, the "wait" period is ignored.
6 Success response Example:
Status Code:  200 OK
OperationResult:  Success
Details:
The request was successful. The recipient 'recipient@yourdomain.com' will receive a customer experience survey on 20-03-2015 12:42
Content:
{
"Status": 1,
"Details": "The request was successful. The respondent 'recipient@yourdomain.com' will receive a loyalty survey on 20-03-2015 12:42",
"Result": 1
}
7 Error response Example:
Status Code:  401 Unauthorized
OperationResult:  Fail
Details
In the request header the KEY is missing.
Content
{
"Status": 0,
"Details": "In the request header the KEY is missing.",
"Result": 0
}
8 Sample call

// REQUEST
HttpWebRequest request = 
    WebRequest.Create("https://www.relationwise.com/rls/restapi3/new-recipient") 
	as HttpWebRequest;

request.Method = "POST";
request.ContentType = "application/json";
request.Headers["key"] = "API_KEY_HERE";

string jsonData = "{" +
"\"name\" : \"Steven Jensen\"," +
"\"email\" : \"sjensen@mailinator.com\"," +
"\"employee-name\" : \"INSERT_VALUE_HERE\"," +
"\"employee-id\" : \"INSERT_VALUE_HERE\"," +
"\"division-name\" : \"INSERT_VALUE_HERE\"," +
"\"division-id\" : \"INSERT_VALUE_HERE\"," +
"\"product-name\" : \"INSERT_VALUE_HERE\"," +
"\"product-id\" : \"INSERT_VALUE_HERE\"" +
"}"; byte[] data = Encoding.UTF8.GetBytes(jsonData); using (Stream stream = request.GetRequestStream()) stream.Write(data, 0, data.Length); // RESPONSE string status = string.Empty; string details = string.Empty; using (HttpWebResponse response = request.GetResponse() as HttpWebResponse) { status = response.StatusCode.ToString(); details = response.Headers["Details"]; }

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.MalformedURLException;
import java.net.URL;

public class RESTClient{

    public static void main(String []args) throws MalformedURLException, IOException
    {
        URL url = new URL("https://www.relationwise2.com/rls/restapi3/new-recipient");
        HttpURLConnection conn = (HttpURLConnection) url.openConnection();

        conn.setDoOutput(true);
        conn.setRequestMethod("POST");
        conn.addRequestProperty("Content-Type", "application/json");
        conn.addRequestProperty("key", "API_KEY_HERE");

        String input = "{" +
"\"name\" : \"Steven Jensen\"," +
"\"email\" : \"sjensen@mailinator.com\"," +
"\"employee-name\" : \"INSERT_VALUE_HERE\"," +
"\"employee-id\" : \"INSERT_VALUE_HERE\"," +
"\"division-name\" : \"INSERT_VALUE_HERE\"," +
"\"division-id\" : \"INSERT_VALUE_HERE\"," +
"\"product-name\" : \"INSERT_VALUE_HERE\"," +
"\"product-id\" : \"INSERT_VALUE_HERE\"" +
"}"; OutputStream os = conn.getOutputStream(); os.write(input.getBytes()); os.flush(); if (conn.getResponseCode() != 200){ throw new RuntimeException("Failed. HTTP Error:" + conn.getResponseMessage()); } BufferedReader br = new BufferedReader(new InputStreamReader(conn.getInputStream())); String output; System.out.println("Output from server...\n"); while((output = br.readLine()) != null){ System.out.println(output); } conn.disconnect(); } }

<?php
    function CallRESTAPI($method, $url, $data = false)
    {
        $curl = curl_init();

        if ($data)
        {
            curl_setopt($curl, CURLOPT_POST, 1);
            curl_setopt($curl, CURLOPT_URL, $url);
            curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
            curl_setopt($curl, CURLOPT_POST, true);
            curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
            curl_setopt($curl, CURLOPT_HTTPHEADER, 

            array('Content-Type: application/json', 'Key: API_KEY_HERE'));
        }

        $result = curl_exec($curl);

        if(curl_errno($curl))
            print 'Curl error: ' . curl_error($curl); // Error (based on business rules)
        else if ($result == null)
            print 'result is null'; // Error
        else
            print $result; // Success!

        curl_close($curl);
    }

    $data = "{" .
"\"name\" : \"Steven Jensen\"," .
"\"email\" : \"sjensen@mailinator.com\"," .
"\"employee-name\" : \"INSERT_VALUE_HERE\"," .
"\"employee-id\" : \"INSERT_VALUE_HERE\"," .
"\"division-name\" : \"INSERT_VALUE_HERE\"," .
"\"division-id\" : \"INSERT_VALUE_HERE\"," .
"\"product-name\" : \"INSERT_VALUE_HERE\"," .
"\"product-id\" : \"INSERT_VALUE_HERE\"" .
"}" // Calling REST API print CallRESTAPI('POST', 'https://www.relationwise.com/rls/restapi3/new-recipient', $data); ?>
1 Purpose Get recipients and answers
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.
2 URL https://www.relationwise.com/rls/restapi3/get-recipients
3 Method GET
4 Header params Required
Key = (Please contact support@relationwise.dk for your API key)
5 Filters Filters provide a way to get more specific data based on your needs. Filters can be used individually or in combination with other filters.
 
(no filters) Returns the most recent 100 recipients that completed the survey. example: https://www.relationwise.com/rls/restapi3/get-recipients
page = <page-number> The number of the page to be returned. example: https://www.relationwise.com/rls/restapi3/get-recipients?page=2
page-rows = <rows-per-page> The number of rows per page. The maximum is 100 rows per page. example: https://www.relationwise.com/rls/restapi3/get-recipients?page-rows=25
version-uid = <version-uid> Returns recipients filtered by version. example: https://www.relationwise.com/rls/restapi3/get-recipients?version-uid=UK
score = <number|number1-number2|number1,number2,...,numberN> 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) examples: https://www.relationwise.com/rls/restapi3/get-recipients?score=10
https://www.relationwise.com/rls/restapi3/get-recipients?score=0-6
https://www.relationwise.com/rls/restapi3/get-recipients?score=0,3,5
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/restapi3/get-recipients?received-from=14-01-2016
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/restapi3/get-recipients?received-to=25-05-2016
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/restapi3/get-recipients?completed-from=14-01-2016
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/restapi3/get-recipients?completed-to=25-05-2016
identifier = <email-address|mobile-number|guid-value> Returns recipients filtered by identifier. Email, phone number or global identifier can be provided (search coincidences) examples: https://www.relationwise.com/rls/restapi3/get-recipients?identifier=admin@company.com
https://www.relationwise.com/rls/restapi3/get-recipients?identifier=4588970076
name = <recipient-name> Returns recipients filtered by name (search coincidences) example: https://www.relationwise.com/rls/restapi3/get-recipients?name=John
subscribed = <yes|no> Returns recipients based on their subscription status. example: https://www.relationwise.com/rls/restapi3/get-recipients?subscribed=yes
created-from = <dd-MM-yyyy> Returns recipients filtered by creation date (created since the provided date) example: https://www.relationwise.com/rls/restapi3/get-recipients?created-from=14-01-2016
created-to = <dd-MM-yyyy> Returns recipients filtered by creation date (created until the provided date) example: https://www.relationwise.com/rls/restapi3/get-recipients?created-to=25-05-2016
variable-name = <variable-name> Returns recipients that have a value for the provided variable. example: https://www.relationwise.com/rls/restapi3/get-recipients?variable-name=country
variable-value = <variable-value> 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/restapi3/get-recipients?variable-value=Denmark
variable-uid = <variable-uid> 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/restapi3/get-recipients?variable-uid=DK
6 Success response Example:
Status Code:  200 OK
OperationResult:  Success
Content (example):
{
"recipients" :
[
    {
        "name": "Arthur Smith",
        "identifier": "arthursmith@mycompany.com",
        "version": "FR",
        "received_at": "12-09-2015 08:30",
        "completed_at": "14-09-2015 11:42",
        "score": 8,
        "comment": "Thanks for a good service",
        "unsubscribed_at": "22-10-2015 09:06",
        "variables":
        [
	    {
	        "name": "Country",
	        "value": "FRANCE",
	        "uid": "FR"
	    },
	    {
	        "name": "Department",
	        "value": "Marketing"
	    },
	    {...}
        ]
    }
    ,
    {...}
],
"paging":
    {
        "pages": 12,
        "next": "https://www.relationwise.com/rls/restapi3/get-recipients?page=4",
        "previous": "https://www.relationwise.com/rls/restapi3/get-recipients?page=2"
    }
}
7 Error response Example:
Status Code:  401 Unauthorized
OperationResult:  Fail
Details
In the request header the KEY is missing.
Content
{
"Status": 0,
"Details": "In the request header the KEY is missing.",
"Result": 0
}
1 Purpose Get statistics based on responses
Returns statistics based on all existing respondent data or within a date range.
2 URL https://www.relationwise.com/rls/restapi3/get-summary
3 Method GET
4 Header params Required
Key = (Please contact support@relationwise.dk for your API key)
5 Filters
(no filters) Returns all statistics for the entire account. example: https://www.relationwise.com/rls/restapi3/get-summary
received-from = <dd-MM-yyyy> Returns the statistics using data filtered from the provided date. example: https://www.relationwise.com/rls/restapi3/get-summary?from=14-01-2016
received-to = <dd-MM-yyyy> Returns the statistics using data filtered until the provided date. example: https://www.relationwise.com/rls/restapi3/get-summary?to=25-05-2016
6 Success response Example:
Status Code:  200 OK
OperationResult:  Success
Content (example):

{
    "NPS": "67",  
    "completes": 1000,
    "promoters": 720,
    "passives": 220,
    "detractors": 50,
}
			    
7 Error response Example:
Status Code:  401 Unauthorized
OperationResult:  Fail
Details
In the request header the KEY is missing.
Content
{
"Status": 0,
"Details": "In the request header the KEY is missing.",
"Result": 0
}

C. Testing centre

1Use this section to monitor the success or failure of your request and why:

0 new requests from your system since 25th of October 2017
change period
0 Successful requests. Show successful requests0 Rejected requests because respondent is RESTing.0 Failed requests.
 

2Get automated notifications of errors and API inactivity

A.  Send automatic notification emails to:
Use ; to denote multiple recipients.
 
B.  Send an notification if there are or more API errors.
 
C.  Send a notification if there has been day(s) of inactivity (no API request received).



3Test your JSON against our API with this RESTClient for Firefox, a debugger for RESTful Web Services:

https://addons.mozilla.org/en-US/firefox/addon/restclient/


D. Frequently Asked Questions
1 What type of API is this?
Our web service is an JSON-based REST API. On this page, we will only document how to push data to Relationwise (one-way data flow). This is our “new-recipient” method, and the only request required for an ultra-simple one-way transactional integration (send and forget).
2 How do you manage security and authentication?
This is an SSL-only API. To authenticate your requests, we require that you insert your account’s API token in the header of each request.
3 What are the most common problems when integrating to Relationwise?
We only require a simple of JSON string of data. There is honestly not much that can go wrong. Any details about how the data is handled when received is managed inside our Admin. The most typical problem is that the data to be sent, the variables, have not yet been clearly defined and approved by your project owner. Before any coding begins, please make sure you have a clear agreement with the project owner about exactly which data will be sent to Relationwise.
4 Can I send multiple customers in a single request?
No. This request is transactional. The data push is triggered by a single customer interaction (touch point). Multiple customers cannot be batched in a single request.
5 Do I need to manage the timing of the requests so that the customer’s receive the survey at a certain time of day?
No, we can manage that for you. We can either send the survey invitation mail immediately, after X number of ours, or the next day at XX:00
6 Do I need to manage the timing of the requests to avoid spamming the customer with surveys too frequently?
No, we can manage that for you. We can automatically give each customer a “resting period”, typically 30-90 days, in which subsequent requests from your system about that customer will be ignored.
7 How do I manage which (language) version of the invitation email and survey the customer will receive?
By default if you do not explicitly state which version of the survey the customer will receive, then we simply send them your account’s default version. However, if the use of multiple versions of the survey has already been defined and approved by your project owner, then send a variable in the request that explicitly states by ID, which version of the survey the customer will receive.
For example:
<variable name="language" value="DK" />

E. Variables

1Let's brainstorm some variable ideas now


  ?

  ?
Variable name Type Description Dashboard name
Name Identity name
(mandatory)
The respondent's name
Email Identity email
(mandatory)
The respondent's email
Employee Key My description
Division Key div Country
Product Key

F. Behaviours

0Which (language) version of your survey you want to work with?

1ID of this version?

2Asign new recipients to this survey version if they match the following conditions:

 = 
+

3After your system triggers Relationwise (new-recipient), how long should we wait to send the survey?

4As a safety against accidentaly spamming customers, please set a "rest" period during which we will not disturb
           recipients with additional surveys:

 days.

5Automatically move no-responders to CATI list?

if a recipient has not responded within days from the day the survey was sent then move the recipient to CATI list.


 

 

Resources

NPS explained

Questions?

Don't forget our awesome support; mail us support@relationwise.dk or call (+45) 70 268 264

Best regards
Your Wise Team