Getting Started with REST API

👋 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

URL

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

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

URL

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

Headers

x-api-key: YOUR_JWT_HERE

Query Parameters:

source - google | facebook - omit field for all sources. The source can be found from the sources property when calling GET /businesses
showOnWidget - true | false - pull reviews that are marked as show on widget only
sort - desc | asc - ordering of reviews

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).

POST /send-review-invite

Send a review invite to your customer. This will add a contact to a review campaign in Cloutly. Note: you need to have a business (location) and campaign already setup and preconfigured in the dashboard first.

Request

URL

POST https://app.cloutly.com/api/v1/send-review-invite

Headers:

x-api-key: YOUR_JWT_HERE

Query Parameters:

N/A

Request Body:

{
    "firstName": "John", // required
    "lastName": "Smith", // optional
    "channel": { // required
        "email": "useremail@gmail.com",
        // AND / OR
        "phoneNumber": "+4412321321321"
    },
    "source": "api" // optional
    "sourceContactId": "number123", // optional
    "businessId": "44271176-7053-4534-ad6f-b38d132d341e", // required
    "campaignId": "2c07094a-ed58-4cf2-9595-cf1b1d303d9d" // required
}

channel - You can provider email and/or phoneNumber. We recommend providing both properties in channel. However, you need to provide at least one.
businessId - Obtain this ID from the GET /businesses query or from the URL on the location page.
campaignId - Obtain this ID from the URL on the campaigns page.
sourceContactId - Optional sourceId you can provide to the API.
source - Optional source parameter to provide to the API. Mostly used for decoration and tracking if you are inviting from multiples sources.

Response

{
    "contact": {
        "id": "fbd481f1-719e-4f38-b1ab-49109c65f164",
        "firstName": "john",
        "lastName": "smith",
        "email": "abc@icloud.com",
        "phoneNumber": null,
        "source": "api",
        "sourceContactId": "number123"
    },
    "usage": {
        "smsLimitsLeft": 19,
        "renews": "2023-07-28T16:40:27.243Z"
    }
}

Notes:

Example of how to find businessId

Example of how to find campaignId

If you have any questions regarding the REST API, feel free to chat us any time.

Updated on: 21/12/2023

Was this article helpful?

Thank you!