The Hellopeter Business API is structured using standard HTTP RESTful principles based on predictable resource-oriented URLs. It accepts form-encoded request payloads and returns JSON-encoded responses, uses standard HTTP response codes and verbs.

The API uses standard error codes consistent with REST so that you can programmatically react to our API responses. For example, if you make a call to the /reviews resource and pass in a permalink, when you receive an HTTP status code of 404, it means that either the permalink is incorrect OR that the review was subsequently removed from our platform.

Over time, we will make more resources available via our API making it even easier for your business to fully integrate our platform into your CRM.

Our intention is to make the full review management process that you're familiar with in our Business Portal, as accessible from our API.

Every API call requires authentication using a unique API Key that you can manage from the Hellopeter Business Portal. The very first time you use the API, you would need to generate a key. To do this, once logged into your business profile, navigate to the Integrations → API menu-item and click on the GENERATE NEW KEY button.

If you already have an API Key and you need to change it, simply click the REGENERATE KEY button. This is especially useful if you know or suspect that your API Key has been compromised.

curl --location --request GET 'https://api.hellopeter.com/v5/api/reviews' \
  --header 'Accept: application/vnd.api+json' \
  --header 'Content-Type: application/json' \
  --header 'apiKey: 12345'

Pagination meta data is available on successful GET requests to list resources i.e when making a successful GET request to a resource without passing a unique identifier to the URL as a parameter and this will return two objects:

1. meta - the meta data related to pagination
2. data - an array of objects based on the resource requested

The meta data contains all the values commonly associated with RESTful pagination so that you can programmatically navigate the entire list of the returned resource objects.

Meta Data Fields

{
  "data": [],
  "meta": {
    "totalRecords": "12",
    "perPage": "10",
    "previousPage": "null",
    "current": "1",
    "nextPage": "https://api.hellopeter.com/v5/api/reviews?page=2",
    "lastPage": "2",
    "from": "1",
    "to": "10"
  }
}

The reviews resource only allows GET requests to be performed. One can perform an HTTP GET request to retrieve a paginated list of reviews or one could request the detail for a single review.

When requesting to get the detail for a single review, you have to pass in the review permalink as a parameter to the reviews resource.

Endpoints

curl --location --request GET 'https://api.hellopeter.com/v5/api/reviews/an-example-review-56789' \
  --header 'Accept: application/vnd.api+json' \
  --header 'Content-Type: application/json' \
  --header 'apiKey: 12345'

Parameter Fields

The API provides the option to add filters to the reviews list. You have the option to pass any or all of the following filters as parameters to the /reviews resource. Should you choose not to pass any filters, all reviews will be returned.

Response Fields

{
  "permalink": "3-star-baddf43947cac263f2ea4923135fb554ba648880-3098948",
  "user": "Batman G",
  "rating": "3",
  "nps": "null",
  "npsScore": "null",
  "channel": "HELLOPETER",
  "status": "REPLIED",
  "title": "3 star",
  "body": "3 star",
  "responseReceived": "true",
  "responseTimestamp": "2021-12-09 10:06:29",
  "timeToRespond": "2",
  "created_at": "2021-12-09T08:03:50.0000002",
  "images": [],
  "customerData": {
    "name": "Batman G",
    "phone": "0823333333",
    "email": "bat@man.com",
    "idNumber": "8001232323232",
    "refNumber": "Not provided",
    "error": "null"
  },
  "notes": [],
  "replies": [
    {
      "private": "false",
      "created_at": "2021-12-09 10:06:29",
      "edited_at": "2021-12-09 10:06:29",
      "id": "12345",
      "body": "this is a another private reply",
      "user_id": "12345",
      "first_name": "Business-API",
      "last_name": "Plug nation",
      "from_business": "true"
    }
  ],
  "branches": [],
  "tags": []
}

The replies resource is a sub-resource of Reviews i.e to perform any HTTP action relating to replies, you would need to supply the review permalink as a parameter for the reply intent - whether that is to create, update or delete a reply.

When requesting to get the detail for a single review, you have to pass in the review permalink as a parameter to the reviews resource.

Endpoints

Request Body (POST / PUT)

Response Fields

Examples

curl --location --request GET '/reviews/an-example-review-56789/replies' \
  --header 'Accept: application/vnd.api+json' \
  --header 'Content-Type: application/json' \
  --header 'apiKey: 12345'

curl --location --request POST '/reviews/fwefwe-3098949/replies' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'apiKey: 12345' \
  --data-raw '{"reply": { "body": "this is a test public reply", "private" : false }}'

curl --location --request PUT '/reviews/fwefwe-3098949/replies/12345' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'apiKey: 12345' \
  --data-raw '{"reply": { "body": "this is a test public reply", "private" : false }}'

curl --location --request DELETE '/reviews/fwefwe-3098949/replies/12345' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'apiKey: 12345'