Introduction

Ratemyservice Developer hub offers a set of Application Programming Interfaces (APIs) that gives you the ability to incorporate various functionality into your projects.

This guide describes how to create an account, get credentials to start building your project and connect to our interface.

Plug and play into possibilities with our simple, powerful APIs in sharing survey data with us for interpretation and us sharing interpretated survey data with you .

Our APIs are built on REST; data entities are represented as HTTP resources and are accessed using HTTP verbs, majorly GET and POST.

API request parameters and responses - including errors - are encoded in JSON. Our APIs response status codes and error codes comply with HTTP status codes as defined in RFC 2616.

Getting started

Getting access to Ratemyservice Developer is as simple as creating a business account.

After you authenticate your email address (which is delivered to your email inbox), you are ready to start developing your first project.

Once you log in to Ratemyservice business account, you will see the api settings. A project within Ratemyservice Developer contains a set of APIs that you can access with one set of credentials. You DO NOT need separate keys to access each API.

API

Want to make something great with Ratemyservice? Get inspired by these innovative solutions created with Ratemyservice technology.

This documentation is intended for developers who want to write applications that can interact with our APIs. This guide will enable you to:

Decide which API is best suited to your needs.
Send your first request or receive the first payload from us.

You can count on our APIs to keep all of your transactions safe. We’ve worked to develop developer APIs that will protect all of the data sent between your online application and our interfaces.

Sharing survey data with us

Prerequisites

Be a registered business on our platform.
Register survey questions on manage survey section of your account.
Generate your API credentials - business_id and api_key – by navigating to Manage settings > Company settings > Integration settings > API settings once logged in. Alternatively, click here once you’re logged in.
The API request is made via HTTP POST to https://api.ratemyservice.co.ke/api/v1/request


{
   "api_key": "t2CnILetL25ciZLq6YvVVwS6n555",
   "business_id": "555",
   "survey_name":"promotion",
   "user_category": "individual",
   "existing_customer": "1",
   "company_department": "Westlands",
   "user_touch_point": "Came for oil change",
   "contact":"[email protected]",
   "review_data":[
      {
         "data":"4",
         "slot_name":"QualityCommunication"
      },
      {
         "data":"4",
         "slot_name":"QualityStaff"
      },
      {
         "data":"4",
         "slot_name":"ValueForMoney"
      },
      {
         "data":"5",
         "slot_name":"QualityService"
      },
      {
         "data":"9",
         "slot_name":"LikeliRecommend"
      },
      {
         "data":"The service was fantastic",
         "slot_name":"Comments"
      },
      {
         "data": "I am very satisfied with your service",
         "slot_name": "How satisfied are you with the level of service from us"
      }
   ]
}


{
    "success": true
}

API Call Parameters

Parameter	Description	Example
api_key	This should match your generated API key	t2CnILetL25ciZLq6YvVVwS6n555
business_id	This should match the business ID of your account	55
survey_name	This is a custom survey name - leave blank for standard survey form	promotion
user_category	This can either be "individual", "sme", or "business"	individual
existing_customer	This flags already registered customer: 0 for new and 1 for already registered.	0
company_department	This is the department or the branch the user is interacting with	Westlands
user_touch_point	This defines how the user is interacting with the company department.	Came for oil change
contact	Reviewer’s email or phone number	[email protected]
QualityService	Response to the question: How would you rate the quality of service you receive from us? Scale (1 - 5)	4
LikeliRecommend	Net Promoter Score (likelihood of a customer recommending you to others) Scale (0 - 10)	7
QualityStaff	Response to the question: How well do our staff treat you as a customer? Scale (1 - 5)	3
ValueForMoney	Response to the question: How would you rate the value for your money? Scale (1 - 5)	4
QualityCommunication	Response to the question: How well do we communicate with you? Scale (1 - 5)	5
Comments	Response to the question: Please let us know why you scored us this way and what would make you happier?	The service was fantastic
How satisfied are you with the level of service from us	This is a custom question	I am very satisfied with your service

Receiving data from us

Prerequisites

Be a registered business on Ratemyservice platform.
Register survey questions on manage survey section of your account.
Set up a call back URL to receive the API result (for example: https://example.com/call-back-url) – by navigating to Manage settings > Company settings > Integrations settings > API settings once logged in. Alternatively, click here once you’re logged in.

API result payload


{
   "payload_id":"21082R1562326832264",
   "survey_name":"firstSurvey",
   "department":"Central Zone",
   "touchpoint":"Came for oil change",
   "review_data":[
      {
         "data": null,
         "slot_name": "Consent"
       },
       {
         "data": null,
         "slot_name": "LikeliRecommend"
       },
       {
         "data": null,
         "slot_name": "QualityService"
       },
       {
         "data": "5",
         "slot_name": "QualityStaff"
       },
       {
         "data": "5",
         "slot_name": "ValueForMoney"
       },
       {
         "data": "5",
         "slot_name": "QualityCommunication"
       },
       {
         "data": null,
         "slot_name": "customer effort score question"
       },
       {
         "data": "The service was fantastic.",
         "slot_name": "Comments"
       },
      {
         "data":"The experience was seamless",
         "slot_name":"How was the shopping experience like?"
      }
   ],
   "contact":"[email protected]",
   "name":"John Doe"
}

Parameter	Description	Example
payload_id	This is the review unique identifier	21082R1562220221436
survey_name	This is the custom survey name	firstSurvey
department	This is the department or the branch the user is interacting with	Central Zone
touchpoint	This defines how the user is interacting with the company department.	Came for oil change
name	Reviewer’s name (if already registered)	John Doe
contact	Reviewer’s email or phone number	[email protected]
review_data	This object contains your survey questions and their responses. The first 8 elements are standard questions and are populated with "null" if the question is not present in your survey.	[ { "data":"null", "slot_name":"Consent" }, { "data":"null", "slot_name":"LikeliRecommend" }, { "data":"null", "slot_name":"QualityService" }, { "data":"5", "slot_name":"QualityStaff" }, { "data":"5", "slot_name":"ValueForMoney" }, { "data":"5", "slot_name":"QualityCommunication" }, { "data":"null", "slot_name":"customer effort score question" }, { "data":"The service was fantastic", "slot_name":"Comments" }, { "data":"The experience was seamless", "slot_name":"How was the shopping experience like?" } ],

Sending SMS surveys to customers

Prerequisites

Be a registered business on Ratemyservice platform.
Register survey questions on manage survey section of your account.
Set up SMS settings. You can either setup a One way (bulk) sender ID or Two way (interactive) shortcode depending on your needs by filling in the required details provided by your SMS provider.
Set up an SMS sending profile by navigating to Manage settings > Company settings > Integrations settings > SMS profiles once logged in. Alternatively, click here once you’re logged in.
Generate an API key from the SMS profiles page.
The API request is made via HTTP POST to https://ratemyservice.co.ke/send-survey

API result payload


{
        "apikey":"q2qa7dJayWwlrq6LdyAwpMoZ213",
        "profileId":"2",
        "name":"John doe",
        "number":"+254712345678",
        "branch":"The Matrix",
        "agent": "Agent Smith",
        "product": "Blue pill",
        "date":"2021-08-18",
}


{
        "message":"Request successful"
}

Parameter	Description	Example
apikey	This should match your generated API key	q2qa7dJayWwlrq6LdyAwpMoZ213
profileId	The ID of the SMS profile you want to use	2
name	Name of customer your sending the SMS to.	John doe
number	Customers phone number.	+254712345678
$surveylens	This is any data that is associated with your respondent. By using this feature, you can make your surveys shorter as you do not need to ask the respondent for this information again during the survey. This feature utilises survey lenses as setup in your profile. Survey lenses can include associated data such as a branch a customer has visited, a department that an employee interacts with, products that have been purchased, an agent that has interacted with a customer, etc. To use this in your API request, you must use the name of the survey lens as the parameter, as named in your profile.	branch: The Matrix agent: Agent Smith product: Blue pill
date	This is the date of the most recent interaction with the customer	2021-08-18

Status codes

API calls will return one of the following HTTP response codes with each request. If the response is anything other than a 200 OK, an API error code and message will also be returned.

Our APIs are built to comply with HTTP Status codes. The following are error codes that will be returned whenever there are errors in a request. Server errors are rare but do occur whenever there are connectivity issues.

Status Code	Meaning
400	Bad Request
401	Unauthorized – Your credentials are wrong
403	Forbidden
404	Not Found – The specified resource could not be found
405	Method Not Allowed
406	Not Acceptable – You requested a format that isn’t json
429	Too Many Requests - Slow down!
500	Internal Server Error – We had a problem with our server. Try again later.
503	Service Unavailable – We’re temporarially offline for maintanance. Please try again later.

Introduction

Getting started

API

Sharing survey data with us

Receiving data from us

Sending SMS surveys to customers

Status codes

Get in touch with us:

© Custometrix Limited