API request API response API result

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:

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



{
   "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


API result payload


{
   "payload_id":"21082R1562326832264",
   "nps_score":"49.00",
   "avg_reviews":"4.50",
   "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":"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

nps_score

Current overall net promoter score

56

avg_reviews

Current overall customer satisfaction score

4.00

name

Reviewer’s name (if already registered)

John Doe

contact

Reviewer’s email or phone number

[email protected]

review_data

This is the object containing your set up review questions


[  

      {  

         "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":"The experience was seamless",

         "slot_name":"How was the shopping experience like?"

      }

   ],

Sending SMS surveys to customers

Prerequisites


API result payload


{
        "apikey":"q2qa7dJayWwlrq6LdyAwpMoZ213",
        "profileId":"2",
        "name":"John doe",
        "number":"+254712345678",
}


{
        "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

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.

© Custometrix Limited