API Documentation

RESTful

The Starred API is a RESTful API. It can be used by cURL for example or one of the many similar client solutions readily available.

The only thing you need to get going is an active account with the API enabled. Each request requires the two parameters stated to the right. You can find those at your settings page.

Note that that all calls should be made with HTTP POST. Request data can be set by using HTTP POST parameters.

Default mandatory parameters

The company key which is available from your company settings page

The API key which is available from your company settings page

API endpoint

This shows a basic API endpoint. All endpoints are relative to this path.

        https://api.starred.com/<SOME-ENDPOINT-METHOD>?company=<COMPANY-KEY>&auth=<API-KEY>
                                    

Most endpoints have their own set of additional parameters. Those can either be added to the endpoint url or be set as HTTP POST parameters.

Possible responses

Request successful

Everything is ok, your call to the endpoint succeeded. In the example the /sendinvitations endpoint has been called.

        HTTP/1.1 200 Ok
        Date: Wed, 14 Jun 2017 12:24:22 GMT
        Server: Apache
        Expires: Wed, 14 Jun 2017 12:24:22 GMT
        Host: starred.com
        Content-Length: 60
        Connection: close
        Content-Type: application/json; charset=utf-8

        {
          "status": "ok",
          "message": "Invitations queued for delivery"
        }
                                    

No access

Access is denied because you have not used the proper access token for the request. When you have an active account which supports API usage you can find the credentials at the settings page.

        HTTP/1.1 403 Forbidden
        Date: Wed, 14 Jun 2017 12:24:22 GMT
        Server: Apache
        Expires: Wed, 14 Jun 2017 12:24:22 GMT
        Host: starred.com
        Content-Length: 60
        Connection: close
        Content-Type: application/json; charset=utf-8

        {
          "status": "fail",
          "errorCode": 403,
          "errorMessage": "Forbidden"
        }
                                    

Invalid endpoint

When the endpoint URL is invalid.

        HTTP/1.1 404 Not Found
        Date: Wed, 14 Jun 2017 12:24:22 GMT
        Server: Apache
        Expires: Wed, 14 Jun 2017 12:24:22 GMT
        Host: starred.com
        Content-Length: 69
        Connection: close
        Content-Type: application/json; charset=utf-8

        {
          "status": "fail",
          "errorCode": 404,
          "errorMessage": "Not found"
        }
                                    

Invalid request

When the request is invalid, for example when an empty CSV file or none at all is send with the HTTP POST parameters.

        HTTP/1.1 400 Bad Request
        Date: Wed, 14 Jun 2017 12:24:22 GMT
        Server: Apache
        Expires: Wed, 14 Jun 2017 12:24:22 GMT
        Host: starred.com
        Content-Length: 72
        Connection: close
        Content-Type: application/json; charset=utf-8

        {
          "status": "fail",
          "errorCode": 400,
          "errorMessage": "Please add a CSV file"
        }
                                    

Available endpoints

/sendinvitations - CSV file

With the /sendinvitations call you can link your CRM system to Starred so invitations are sent automatically. This will no longer require any manual action. You can also import additional characteristics directly from your CRM so you can start analyzing results for different client groups. The API allows you to choose exactly the right moment for invitations to be sent automatically, so that your customers can give their feedback when it is most relevant to them.

The parameters on the right are mandatory to make the request succeed.

Parameters

ID of the form that will be sent out

Email address of the sender, must be a registered email

Template ID

The language of the template. For example: nl, en or fr

A CSV file formatted as a regular invitation CSV added as a HTTP POST file. Note that in cURL a file should be preceded by a "@" sign like this:

        curl --form "file=@invitations.csv"
                                    

Whether or not to send a reminder (1 or 0). Defaults to 1


/sendinvitations - Single recipient

Instead of uploading a CSV file, you can also set one recipient per API call by using the following parameters to the URL:

Parameters

ID of the form that will be sent out

Email address of the sender, must be a registered email

Email address of the recipient

First name to address the recipient with

Surname to address the recipient with

Template ID

The language of the template. For example: nl, en or fr

Whether or not to send a reminder (1 or 0). Defaults to 1


Segment/summary

Get form segment summary data

Parameters

ID of the form that will be sent out

Segment ID to get summary data for (defaults to 0)


/InvitationLinks/single

POST request to generate an invitation link for a recipient with optional tags

Parameters

ID of the form that will be sent out

The user's email who is sending the invitation

The email address of the recipient of the email

Any number of invitation tags can be listed. It is in key - value format, e.g. tag1=tag1

First name of user. If left blank, it will use previously used name.

Last name of user. If left blank, it will use previously used name.

        curl --data "company=<COMPANY-KEY>&auth=<API-KEY>&form=1&fromUserEmail=foo@bar.com&recipient=bar@foo.com&tag1=tag1&firstname=foo&lastName=bar" 
                                    

/InvitationLinks/anonymous

POST request to generate from 1 up to, and including, 100 anonymous links. (Anonymous is for when the recipient's email is not known)

Parameters

ID of the form that will be sent out

The user's email who is sending the invitation

Amount of invitation links desired. If not specified then it defaults to 1 and is returned as a string. If specified, the response will always return as an array.

Tags can be added to the anonymous link to make it more personal. These follow the same conventions as other API calls

        curl --data "company=<COMPANY-KEY>&auth=<API-KEY>&form=1&fromUserEmail=foo@bar.com&amount=100&tag1=tag1" 
                                    

/InvitationLinks/csv

POST request to generate links for users from a csv file.

Parameters

ID of the form that will be sent out

The user's email who is sending the invitation

        curl --form "file=@csv.csv" "https://api.starred.com/InvitationLinks/csv?company=<COMPANY-KEY>&auth=<API-KEY>&form=1&fromUserEmail=foo@bar.com" 
                                    

Webhooks

Starred webhooks allow you to be notified automatically as soon as you have received new feedback. The callback URL will be called as an HTTP POST request with a JSON file for each new response you've received.

You can enrich the callback url with tags by adding them as url parameters, like '?tagA=@tagA'. Multiple tags can be added byseperating them using the & sign: '?tagA=@tagA&tagB=@tagB'.

Example callback URL:
https://callbackurl/?parameter=<@TAG>

Setup

Users can easily install a callback URL on the company settings page.

Company Settings »
        [
          {
            "emailAddress": "someone@example.com",
            "elements": [
              {
                "Organization - Professional": 9,
                "Organization - Is Starred competent in its area of business?": "",
                "Organization - Transparent": 9,
                "Organization - Do you feel working with Starred is open and clear?": "",
                "Organization - Quality-driven": 10,
                "Organization - Does Starred aim for delivering high quality products and services?": "",
                "Organization - Result-driven": 9,
                "Organization - Does Starred focus on meeting goals and pursuing solid end-results?": "",
                "Organization - Best in class": 9,
                "Organization - Do you consider Starred to belong to the top of its area of business?": ""
              },
              {
                "People - Skilled": 6,
                "People - Are the people at Starred experts at what they do?": "",
                "People - Reliable": 10,
                "People - Do people at Starred live up to their promise?": "",
                "People - Dedicated": 10,
                "People - Do people at Starred go the extra mile?": "",
                "People - Accessible": 10,
                "People - Are the people at Starred open, approachable and easy to reach?": "",
                "People - Fun": 10,
                "People - Are the people at Starred fun to work with?": ""
              },
              {
                "How likely is it that you would recommend us to a friend or a colleague?": 10,
                "What should we do differently to get a 9 or 10?": "Always willing to help, no matter how trivial the problem!",
                "Your general feedback on our company:": "Pleasure doing business with you."
              }
            ]
          }
        ]