👋 Welcome to Cloutly's REST API

REST API allows you to access your Cloutly data. Request methods are used in accordance with HTTP:

GET is used to read one or more entities;
POST is used to create or update entities;
DELETE is used to delete entities;
Responses use standard HTTP codes.

Before you start using the API, read through the following five basics 👇

1️⃣ Base API Domain

Cloutly's API is provided on the following HTTPS-only domain:

https://app.cloutly.com/api/v1


2️⃣ Authentication

You should authenticate all your HTTP requests to Cloutly's API with the help of your API key.

To get your API key, go to Developers → Public API and copy your API Key from there.

[Screenshot coming soon]

In order to authenticate your HTTP requests, you should add an x-api-key header to your requests and specify your API key there.

x-api-key: YOUR_JWT_HERE


You don't need to do any extra manipulations with your API key. It is permanent and never expires until rotated from the console.

Make sure you pass the entire key without any spaces or extra symbols.

3️⃣ Rate limiting

In order to protect Cloutly from API traffic spikes that could put our database at risk we utilise rate-limiting. When you get rate-limited, you will start receiving 429 Too Many Requests HTTP errors in response to your requests.

The default overall requests limit is 200 per minute

4️⃣ Errors

Depending on the exact method, you can get one of the following error status codes and responses:

400 Bad Request

The request could not be understood by Cloutly's server due to malformed syntax or invalid attribute value. DO NOT repeat such requests without modifications.

401 Unauthorized

This means that something is wrong with your API key or it's not added to the request headers at all. Make sure you pass it as described in the Authentication section above.

404 Not Found

We were unable to find anything matching your request.

429 Too Many Requests

You reached a rate-limit of 100 API calls per minute.

5️⃣ Endpoints

Here's the list of all available endpoints you can use to access and control your Cloutly data.

GET /businesses

Get list of businesses (locations) and sources connected to this Cloutly account

Request

Headers

x-api-key: YOUR_JWT_HERE


Query Parameters

N/A

Response

[
  {
    "id": "5ef7b45b-2fd2-4719-88fd-96ef62f9d4a4",
    "name": "My Business",
    "sources": ["google", "facebook"],
    ...
  }
]


GET /reviews

Pull a list of reviews for all your connected sources in Cloutly. Note: you need to connect the source as an integration in the dashboard first.

Request

Headers

x-api-key:


Query Parameters

Response

{
  "total": 30,
  "reviews": [
    {
      "authorName": "Tim Crowel",
      "businessId": "634d8ed1-11fd-413d-a9a6-d6b8ba0c95a5",
      "createdAt": "2021-02-03T00:00:00.000Z",
      "email": "[email protected]",
      "id": "cbd42728-9c56-4485-813c-4c85d1e64cf4",
      "isArchived": false,
      "name": "Tim Crowel",
      "phoneNumber": null,
      "photo": "https_link_to_CDN",
      "rating": "5",
      "showOnWidget": true,
      "response": {
        "name": "My Business",
        "date": "2021-02-04",
        "comment": "Thank you for the wonderful feedback Tim. We're glad the process was simple and easy and will be sure to pass your feedback on to the team! :) Thanks Tara"
      },
      "shield": false,
      "source": "trustpilot",
      "sourceFeedbackId": "601a81b4679d9705c86295eb",
      "status": "Responded",
      "reviewUrl": "https://example.com/url/to/review/source", // or null
      "text": "Fantastic. Couldn't be more satisfied. The whole process was Simple, Easy, Efficient and the demonstrated true professionalism by thinking on their feet and finding a way to make it happen. Highly recommended.",
      "type": null,
      "videoRef": "/uploads/xxx/xxx.mp4",
      "gifRef": "/uploads/xxx/xxx.gif",
      "updatedAt": "2021-03-01T00:02:21.739Z",
      ...
    }
  ]
}


Notes:
reviews is ordered by createdAt: desc, which means the latest review will always be at the beginning of the list.
Most fields a nullable so remember to unwrap fields if you are expecting a required value
The ... indicates that new fields may be added over time.
We will consider changing field names or removing fields to be a breaking change and will publish a new version (V2 in this case).

If you have any questions regarding the REST API, feel free to chat us any time.
Was this article helpful?
Cancel
Thank you!