API Reference

The Optimum Feedback REST API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients.

We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website's client-side code). JSON is returned by all API responses, including errors.

All endpoint URLs begin with https://optimumfeedback.com/api/v1.2/. Additionally, the REST API requires the use of a client which supports SNI.

Parameters must be serialized in JSON and passed in the request body (not in the query string or form parameters). This API is modeled after earlier versions of the JSON API specification.

It is recommended that you use the media type designation of application/vnd.api+json, although we will accept a media type designation of application/json.

https://optimumfeedback.com/api/v1.2/

Authentication

You can authenticate your requests by including your API Token in the request. You can generate and manage your API tokens on the Integrations tab in Settings when you sign into your account. Your API tokens allow access to your account data so be sure to keep them secret! Do not share your API tokens in publicly accessible areas such GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password.

$ curl https://optimumfeedback.com/api/v1.2/subscriber/ \
-u example_api_token_12334:

curl uses the -u flag to pass basic auth credentials (adding a colon after your API key prevents cURL from asking for a password).

Pagination

All top-level API resources have support for bulk fetches via "list" API methods. For instance you can list subsribers, list reviews, and list accounts. These list API methods share a common structure, taking at least these three parameters: limit,sort_by and page.

Arguments
  • limit optional, default is 10

    Limit on the number of objects to be returned, between 1 and 100.

  • page optional, default is 0

    The starting page to return results from beginning at 0. The maximum page will be calculated by the total number of results divided by the limit.

  • sort_by optional, default is reverse chronological

    The field to sort objects by. Indicate direction by appending either '-asc' or '-desc'. e.g. to sort by the oldest objects first, you would use 'created-asc'.

List Response Format
  • data array

    An array containing the actual response elements, paginated by any request parameters.

  • page integer

    The current page number.

  • total_count integer

    The total number of records available.

  • total_returned integer

    The total number of records returned in this query.

Pagination
$ curl https://optimumfeedback.com/api/v1.2/subscribers?limit=20&created_after=1571482958 \
-u example_api_token_12334: \
-G

                                 {"page":1,"total_count":3,"total_returned":3,"data":[{"id":"gd7TdO","created":1571443200,"email":"subscriber@optimumfeedback.com","mobile_number":"+1813555555","fname":"Jane","sname":"Doe","last_sms":1571482958,"last_email":null,"country_code":"US","invalid":false,"opt_out":false,"locations":["xd3S6","iF56sC"]},{"id":"gse4Ry","created":1571443200,"email":"subscriber2@optimumfeedback.com","mobile_number":null,"fname":"Bobby","sname":"Axelrod","last_sms":null,"last_email":null,"country_code":"US","invalid":false,"opt_out":true,"locations":["iF56sC"]},{"id":"dfar5V","created":1571443200,"email":"subscriber3@optimumfeedback.com","mobile_number":"+447810123456","fname":"Ciro","sname":"Marzio","last_sms":1571482958,"last_email":1571443200,"country_code":"GB","invalid":false,"opt_out":false,"locations":["xd3S6","iF56sC"]}]}
                              

Errors

We use conventional HTTP response codes to indicate the success or failure of a request.

In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a subscriber could not be added etc), and codes in the 5xx range indicate an error with our servers.

Attributes
  • type

    The type of error returned. Can be: api_connection_error, api_error, authentication_error, invalid_request_error, or rate_limit_error.

  • message optional

    A human-readable message providing more details about the error.

  • param optional

    The parameter the error relates to if the error is parameter-specific. You can use this to display a message near the correct form field, for example.

Authentication
200 - OK Everything worked well as expected.
400 - Bad Request The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized No valid API key provided.
402 - Request Failed The parameters were valid but the request failed.
404 - Not Found The requested resource doesn't exist.
429 - Too Many Requests Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 - Server Errors Something went wrong on our end.
Errors
Types
api_connection_error Failure to connect to Optimum Feedback's API.
api_error API errors cover any other type of problem (e.g, a temporary problem with our servers and are extremely uncommon.
authentication_error Failure to properly authenticate yourself in the request. Check your API token is being sent as an authentication header.
invalid_request_error Invalid request errors arise when your request has invalid parameters.
rate_limit_error Too many requests hit the API too quickly.

Customers

Customer objects represent the customers in an account that may be the recipient of feedback campaigns. The API allows you to create, delete and update your customers. You can retrieve individual customers as well as a list of all your customers.

https://optimumfeedback.com/api/v1.2/customers

The Customer Object

Attributes
  • id

    Unique identifier for the customer.

  • created timestamp

    Time at which the object was created. Measured in seconds since the Unix epoch.

  • email string

    The customer’s email address.

  • mobile_number string

    The customer’s mobile number in E.164 format (including the country code e.g. +1 for the US).

  • fname string

    The customer’s first name.

  • sname string

    The customer’s last / family name.

  • last_sms timestamp

    The time the last SMS message was sent to this customer. Measured in seconds since the Unix epoch.

  • last_email timestamp

    The time the last email message was sent to this customer. Measured in seconds since the Unix epoch.

  • country_code string

    The customer’s resident country in 2 letter ISO format.

  • invalid boolean

    If an SMS message fails delivery or an email bounces, the customer is marked as invalid.

  • opt_out boolean

    If a customer clicks the unsubscribe or complaint link in an email, the customer is marked as opted out.

  • locations array

    An array of location IDs that the customer belongs to.

Customer Object
                                 

                                    {"id":"gd7TdO","created":1571443200,"email":"subscriber@optimumfeedback.com","mobile_number":"+1813555555","fname":"Jane","sname":"Doe","last_sms":1571482958,"last_email":null,"country_code":"US","invalid":false,"opt_out":false,"locations":["xd3S6","iF56sC"]}

                                 
                              

Create Customer

To create a new customer you create a customer object. Customers are uniquely identified by their email address or mobile number and their location.

If you attempt to create a customer at a location where another exists with the same email address or mobile number, the creation will be treated as an update to the existing record. This means campaigns will not be re-triggered if they have already been completed for that customer.

Arguments
  • email optional *, default is null

    A string representing the customer’s email address. * If mobile_number is not present, this field becomes required

  • mobile_number optional *, default is null

    A string representing the customer’s mobile number in E.164 format (including the country code). * If email is not present, this field becomes required

  • fname optional, default is null

    The customer’s first name.

  • sname optional, default is null

    The customer’s last / family name.

  • country_code required

    The customer’s resident country in in 2 letter ISO format.

  • location required

    A string representing an initial location ID that the customer should be attached to. You can attach the customer to more locations by calling the Update Customer API

Create Customer
$ curl https://optimumfeedback.com/api/v1.2/customers/ \
-u example_api_token_12334: \
-d mobile_number="+1813555555" \
-d email="customer@optimumfeedback.com" \
-d country_code="US" \
-d location="xS4rtY"

                                 {"id":"gd7TdO","created":1571443200,"email":"subscriber@optimumfeedback.com","mobile_number":"+1813555555","fname":null,"sname":null,"last_sms":null,"last_email":null,"country_code":"US","invalid":false,"opt_out":false,"locations":["xS4rtY"]}
                              

Retrieve a Customer

Retrieves the details of an existing customer. You need only supply the unique id that was returned upon customer creation.

Arguments
  • id required

    The identifier of the customer to be returned

Retrieve a Customer
https://optimumfeedback.com/api/v1.2/customers/gd7TdO \
-u example_api_token_12334:

                                 {"id":"gd7TdO","created":1571443200,"email":"subscriber@optimumfeedback.com","mobile_number":"+1813555555","fname":null,"sname":null,"last_sms":null,"last_email":null,"country_code":"US","invalid":false,"opt_out":false,"locations":["xS4rtY"]}
                              

Update a Customer

Updates the specified customer by setting the values of the parameters passed. Any parameters not provided will be left unchanged. For example, if you pass the fname parameter, that becomes the customer's first name which can be used in campaigns in the future. (Remember, any messages or campaigns scheduled before the change will not be affected).

This request accepts mostly the same arguments as the create customer call.

Arguments
  • email optional

    A string representing the customer's email address.

  • mobile_number optional

    A string representing the customer's mobile number in E.164 format (including the country code).

  • fname optional

    The customer's first name.

  • sname optional

    The customer's last / family name.

  • country_code optional

    The customer's resident country in in 2 letter ISO format.

  • opt_out optional

    Opt the customer in or out from further email or SMS communication

  • location_add optional

    An array of location IDs that the customer should be attached to. If the customer already belongs to that location, it will be ignored.

  • location_remove optional

    An array of location IDs that the customer should be removed from. If the customer does not already belong to that location, it will be ignored.

Update Customer
POST https://optimumfeedback.com/api/v1.2/customers/{id}
$ curl https://optimumfeedback.com/api/v1.2/customers/gd7TdO \
-u example_api_token_12334: \
-d opt_out=true \
-d fname="Ciro"

                                                                  {"id":"gd7TdO","created":1571443200,"email":"subscriber@optimumfeedback.com","mobile_number":"+1813555555","fname":"Ciro","sname":null,"last_sms":null,"last_email":null,"country_code":"US","invalid":false,"opt_out":true,"locations":["xS4rtY"]}
                              

Delete a Customer

Makes a customer inactive across an account and all locations. Remember, the customer will effectively be set to inactive rather than removed from our database completely. This is to prevent the same campaign being sent to that customer in the event they are added again to the same location at a later date.

Arguments
  • id required

    The id of the customer to remove.

Delete Customer
DELETE https://optimumfeedback.com/api/v1.2/customers/{id}
$ curl https://optimumfeedback.com/api/v1.2/customers/gd7TdO \
-u example_api_token_12334: \
-X DELETE

                                 {"id":"gd7TdO","deleted":true}
                              

List all Customers

Returns a list of your customers. The customers are returned sorted by created date, with the most recent customers appearing first.

Attributes
  • created_before optional

    A filter on the list based on the created field with this being the upper limit. The value is a string with an integer Unix timestamp

  • created_after optional

    A filter on the list based on the created field with this being the lower limit. The value is a string with an integer Unix timestamp

  • email optional

    A filter on the customer's email address. The value is a string

  • mobile_number optional

    A filter on the customer's mobile number in E.164 format (including the country code e.g. +1 for the US). The value is a string

  • fname optional

    A filter on the customer's first name. The value is a string

  • sname optional

    A filter on the customer's last / family name. The value is a string

  • country_code optional

    A filter on the customer's resident country in 2 letter ISO format. The value is a string

  • invalid optional

    A filter to only return customers that have been flagged as valid / invalid . The value is a boolean representing valid by TRUE and invalid by FALSE

  • opt_out optional

    A filter to return customers based on their opt-out status. The value is a boolean representing opted out by TRUE and not opted out by FALSE

List all Customers
GET https://optimumfeedback.com/api/v1.2/customers
$ curl https://optimumfeedback.com/api/v1.2/customers?limit=20&created_after=1483228800 \
-u example_api_token_12334: \
-G

                                 {"page":1,"total_count":3,"total_returned":3,"data":[{"id":"gd7TdO","created":1571443200,"email":"subscriber@optimumfeedback.com","mobile_number":"+1813555555","fname":"Jane","sname":"Doe","last_sms":1571482958,"last_email":null,"country_code":"US","invalid":false,"opt_out":false,"locations":["xd3S6","iF56sC"]},{"id":"gse4Ry","created":1571443200,"email":"subscriber2@optimumfeedback.com","mobile_number":null,"fname":"Bobby","sname":"Axelrod","last_sms":null,"last_email":null,"country_code":"US","invalid":false,"opt_out":true,"locations":["iF56sC"]},{"id":"dfar5V","created":1571443200,"email":"subscriber3@optimumfeedback.com","mobile_number":"+447810123456","fname":"Ciro","sname":"Marzio","last_sms":1571482958,"last_email":1571443200,"country_code":"GB","invalid":false,"opt_out":false,"locations":["xd3S6","iF56sC"]}]}
                              

Locations

Location objects represent the locations in an account. These locations can be physical outlets or offices in addition to different departments or people within an organization. Think of locations as entities that you may need to collect reviews on. The API allows you to create, delete and update your locations. You can retrieve individual location information as well as a list of all your locations.

https://optimumfeedback.com/api/v1.2/locations

The Location Object

Attributes
  • id

    Unique identifier for the location.

  • created timestamp

    Time at which the object was created. Measured in seconds since the Unix epoch.

  • name string

    The location’s name.

  • address_line_1 string

    The location's first address line.

  • address_line_2 string

    The location's second address line.

  • address_line_3 string

    The location's state or third address line.

  • postal_code string

    The location's zip code or postcode.

  • country_code string

    The location's country in 2 letter ISO format.

Location Object
                                 

                                    {"id":"gd7TdO","created":1571443200,"name":"Apple Park","address_line_1":"The Spaceship, 1 Apple Park Way","address_line_2":"Cupertino","address_line_3":"CA","postal_code":"90210","country_code":"US"}

                                 
                              

Create a Location

To create a new location you create a location object.

Arguments
  • name required

    The location’s name.

  • address_line_1 optional

    The location's first address line.

  • address_line_2 optional

    The location's second address line.

  • address_line_3 optional

    The location's state or third address line.

  • postal_code optional

    The location's zip code or postcode.

  • country_code required

    The location's country in 2 letter ISO format.

Create a Location
POST https://optimumfeedback.com/api/v1.2/locations
$ curl https://optimumfeedback.com/api/v1.2/locations/ \
-u example_api_token_12334: \
-d name="Apple Park" \
-d address_line_1="The Spaceship, 1 Apple Park Way" \
-d address_line_2="Cupertino" \
-d address_line_3="CA" \
-d postal_code="90210" \
-d country_code="US"

                                 {"id":"gd7TdO","created":1571443200,"name":"Apple Park","address_line_1":"The Spaceship, 1 Apple Park Way","address_line_2":"Cupertino","address_line_3":"CA","postal_code":"90210","country_code":"US"}
                              

Retrieve a Location

Retrieves the details of an existing location. You need only supply the unique id that was returned upon location creation.

Arguments
  • id required

    The identifier of the location to be returned

Retrieve a Location
https://optimumfeedback.com/api/v1.2/locations/gd7TdO \
-u example_api_token_12334:

                                 {"id":"gd7TdO","created":1571443200,"name":"Apple Park","address_line_1":"The Spaceship, 1 Apple Park Way","address_line_2":"Cupertino","address_line_3":"CA","postal_code":"90210","country_code":"US"}
                              

Update a Location

Updates the specified location by setting the values of the parameters passed. Any parameters not provided will be left unchanged. For example, if you pass the address_line_1 parameter, that becomes the locations’s first address line which can be used in templating on future campaigns. (Remember, any messages or campaigns scheduled before the change will not be affected).

This request accepts mostly the same arguments as the create location call.

Arguments
  • name optional

    The location’s name.

  • address_line_1 optional

    The location's first address line.

  • address_line_2 optional

    The location's second address line.

  • address_line_3 optional

    The location's state or third address line.

  • postal_code optional

    The location's zip code or postcode.

  • country_code optional

    The location's country in 2 letter ISO format.

Update Location
POST https://optimumfeedback.com/api/v1.2/locations/{id}
$ curl https://optimumfeedback.com/api/v1.2/locations/gd7TdO \
-u example_api_token_12334: \
-d name="The HyperRing"

                                                                  {"id":"gd7TdO","created":1571443200,"name":"The HyperRing","address_line_1":"The Spaceship, 1 Apple Park Way","address_line_2":"Cupertino","address_line_3":"CA","postal_code":"90210","country_code":"US"}
                              

Delete a Location

Makes a location inactive. All campaigns for this location will cease working and any reviews attached to this location will no longer be active.

Arguments
  • id required

    The id of the location to remove.

Delete a Location
DELETE https://optimumfeedback.com/api/v1.2/locations/{id}
$ curl https://optimumfeedback.com/api/v1.2/locations/gd7TdO \
-u example_api_token_12334: \
-X DELETE

                                 {"id":"gd7TdO","deleted":true}
                              

List all Locations

Returns a list of locations. The locations are returned sorted by the location name by default.

Attributes
  • created_before optional

    A filter on the list based on the created field with this being the upper limit. The value is a string with an integer Unix timestamp

  • created_after optional

    A filter on the list based on the created field with this being the lower limit. The value is a string with an integer Unix timestamp

  • name optional

    A filter on the locations's name. The value is a string

  • postal_code optional

    A filter on the location's postal or zip code. The value is a string

  • country_code optional

    A filter on the location’s country in 2 letter ISO format. The value is a string

List all Locations
GET https://optimumfeedback.com/api/v1.2/locations
$ curl https://optimumfeedback.com/api/v1.2/locations?limit=20&created_after=1483228800 \
-u example_api_token_12334: \
-G

                                 {"page":1,"total_count":3,"total_returned":3,"data":[{"id":"gse4Ry","created":1571443200,"name":"Acme Inc","address_line_1":"27 Loony Toon West","address_line_2":null,"address_line_3":"NY","postal_code":"11201","country_code":"US"},{"id":"gd7TdO","created":1571443200,"name":"Apple Park","address_line_1":"The Spaceship, 1 Apple Park Way","address_line_2":"Cupertino","address_line_3":"CA","postal_code":"90210","country_code":"US"},{"id":"dfar5V","created":1571443200,"name":"B613 UK Branch","address_line_1":"85 Albert Embankment","address_line_2":"Lambeth","address_line_3":"London","postal_code":"SE1 7TP","country_code":"GB"}]}
                              

Reviews

Review objects represent the reviews that are left externally for an account's locations. A review object can include both a review (e.g. 'This place is awesome'), a rating (e.g. 5/5) or both.

https://optimumfeedback.com/api/v1.2/reviews

The Review Object

Attributes
  • id

    Unique identifier for the review.

  • created timestamp

    Time at which the object was created. Measured in seconds since the Unix epoch.

  • title string

    The review title if one exists.

  • description string

    The main body of the review.

  • location string

    The location ID that the review belongs to

  • platform string

    The platform ID that the review belongs to.

  • platform_name string

    The name of the platform that the review belongs to.

  • rating float

    The normalized rating attached to the review, out of 5.

  • url string

    The review's url if one exists.

  • reviewer_name string

    The username or name of the individual who left the review.

  • reviewer_image string

    The url of the reviewer's profile image on the platform where the review was left.

  • reviewer_url string

    The url of the reviewer's profile on the platform where the review was left.

Review Object
                                 

                                    {"id":"gd7TdO","created":1571443200,"title":"Possibly the best law firm ever!","description":"What more can I say, these guys are incredible!! Highly recommended","location":"gse4Ry","platform":"dfar5V","platform_name":"The Review Site","rating":5,"url":"https:\/\/thereview.site\/reviews\/12345","reviewer_name":"John Doe","reviewer_image":null,"reviewer_url":null}

                                 
                              

Retrieve a Review

Retrieves the details of an existing review. You need only supply the review's unique id.

Arguments
  • id required

    The identifier of the review to be returned

Retrieve a Review
https://optimumfeedback.com/api/v1.2/reviews/gd7TdO \
-u example_api_token_12334:

                                 {"id":"gd7TdO","created":1571443200,"title":"Possibly the best law firm ever!","description":"What more can I say, these guys are incredible!! Highly recommended","location":"gse4Ry","platform":"dfar5V","platform_name":"The Review Site","rating":5,"url":"https:\/\/thereview.site\/reviews\/12345","reviewer_name":"John Doe","reviewer_image":null,"reviewer_url":null}
                              

List all Reviews

Returns a list of reviews. The reviews are returned sorted by the review date by default with the newest reviews appearing first.

Attributes
  • created_before optional

    A filter on the list based on the created field with this being the upper limit. The value is a string with an integer Unix timestamp

  • created_after optional

    A filter on the list based on the created field with this being the lower limit. The value is a string with an integer Unix timestamp

  • location optional

    A filter on the review's locations. The value is a string representing the location ID.

  • platform optional

    A filter on the review's platform. The value is a string representing the platform ID

  • rating_less_than optional

    A filter on the review’s rating where it is lesser than or equal to the supplied value. The value is a decimal represented by a string

  • rating_greater_than optional

    A filter on the review’s rating where it is greater than or equal to the supplied value. The value is a decimal represented by a string

List all Reviews
GET https://optimumfeedback.com/api/v1.2/reviews
$ curl https://optimumfeedback.com/api/v1.2/reviews?limit=20&created_after=1483228800 \
-u example_api_token_12334: \
-G

                                 {"page":1,"total_count":3,"total_returned":3,"data":[{"id":"gse4Ry","created":1571443200,"title":"Excellent Staff and Great Customer Service","description":"Acme Law firm have been my go to law firm for several years and never disappoint.","location":"gse4Ry","platform":"dfar5V","platform_name":"The Review Site","rating":5,"url":"https:\/\/thereview.site\/reviews\/12367","reviewer_name":null,"reviewer_image":null,"reviewer_url":null},{"id":"gd7TdO","created":1571443200,"title":"Possibly the best law firm ever!","description":"What more can I say, these guys are incredible!! Highly recommended","location":"gse4Ry","platform":"dfar5V","platform_name":"The Review Site","rating":5,"url":"https:\/\/thereview.site\/reviews\/12345","reviewer_name":"John Doe","reviewer_image":null,"reviewer_url":null},{"id":"dfar5V","created":1571443200,"title":null,"description":"Another excellent experience with Acme Law Firm - thanks to the team","location":"gse4Ry","platform":"gse4Ry","platform_name":"Solicitor Reviews","rating":4.5,"url":"https:\/\/solicitor-reviews.net\/reviews\/12345","reviewer_name":"Jane Doe","reviewer_image":null,"reviewer_url":null}]}
                              

Feedback

Feedback objects represent the feedback that is left internally by subscribers for an account's locations.

https://optimumfeedback.com/api/v1.2/feedback

The Feedback Object

Attributes
  • id

    Unique identifier for the review.

  • created timestamp

    Time at which the object was created. Measured in seconds since the Unix epoch.

  • type string

    Currently one of three types - star-rating, nps or csat

  • nps_score integer

    The nps score (0 - 10) left if the type of feedback was nps.

  • star_rating integer

    The star rating (1 - 5) left if the type of feedback was star-rating.

  • happy boolean

    Whether the respondent was happy / unhappy if the type of feedback was happy.

  • comments string

    Comments left by the subscriber if negative feedback has been left.

  • platform_name string

    The platform link that was clicked, if available.

  • subscriber string

    The ID of the subscriber who left feedback if available.

  • subscriber_name string

    The name of the subscriber who left feedback if available.

  • subscriber_email string

    The email address of the subscriber who left feedback if available.

  • location string

    The location ID that the feedback belongs to

  • campaign string

    The campaign ID that generated the feedback request if available.

  • campaign_step string

    The campaign step ID that generated the feedback request if available.

Feedback Object
                                 

                                    {"id":"gd7TdO","created":1571443200,"type":"nps","nps-score":8,"star-rating":null,"happy":null,"comments":null,"platform_name":"The Review Site","subscriber":"pl6R4s","subscriber_name":"John Doe","subscriber_email":"johndoe@email.com","location":"pr64Ct","campaign":"gse4Ry","campaign_step":"dfar5V"}

                                 
                              

Retrieve Feedback

Retrieves the details of feedback left. You need only supply the feedback's unique id.

Arguments
  • id required

    The identifier of the feedback to be returned

Retrieve Feedback
https://optimumfeedback.com/api/v1.2/feedback/gd7TdO \
-u example_api_token_12334:

                                 {"id":"gd7TdO","created":1571443200,"type":"nps","nps-score":8,"star-rating":null,"happy":null,"comments":null,"platform_name":"The Review Site","subscriber":"pl6R4s","subscriber_name":"John Doe","subscriber_email":"johndoe@email.com","location":"pr64Ct","campaign":"gse4Ry","campaign_step":"dfar5V"}
                              

List all Feedback

Returns a list of feedback. Feedback is returned sorted by the creation date by default with the newest feedback appearing first.

Attributes
  • created_before optional

    A filter on the list based on the created field with this being the upper limit. The value is a string with an integer Unix timestamp

  • created_after optional

    A filter on the list based on the created field with this being the lower limit. The value is a string with an integer Unix timestamp

  • type optional

    A filter on the feedback types to return. Either star-rating, nps or happy

  • nps_score_less_than optional

    A filter on nps scores lesser than or equal to the supplied value, where the type of feedback is nps. This value is an integer between 0 and 10.

  • nps_score_greater_than optional

    A filter on nps scores greater than or equal to the supplied value, where the type of feedback is nps. This value is an integer between 0 and 10.

  • star_rating_less_than optional

    A filter on star ratings lesser than or equal to the supplied value, where the type of feedback is star-rating. This value is an integer between 1 and 5.

  • star_rating_greater_than optional

    A filter on star ratings greater than or equal to the supplied value, where the type of feedback is star-rating. This value is an integer between 1 and 5.

  • happy boolean

    A filter on whether the respondent was happy / unhappy if the type of feedback was happy. The value is a boolean representing happy by TRUE and unhappy by FALSE.

  • subscriber string

    A filter on the ID of the subscriber who left feedback if available.

  • location string

    A filter on the location ID that the feedback belongs to.

  • campaign string

    A filter on the campaign ID that generated the feedback request.

  • campaign_step string

    A filter on the campaign step ID that generated the feedback request.

List all Feedback
GET https://optimumfeedback.com/api/v1.2/feedback
$ curl https://optimumfeedback.com/api/v1.2/feedback?limit=20&created_after=1483228800 \
-u example_api_token_12334: \
-G

                                 {"page":1,"total_count":3,"total_returned":3,"data":[{"id":"gse4Ry","created":1571443200,"type":"happy","nps-score":null,"star-rating":null,"happy":false,"comments":"I guess I was expecting more. A disappointing experience","platform_name":null,"subscriber":"ax34eW","subscriber_name":"Jane Doe","subscriber_email":"janedoe@email.com","location":"pr64Ct","campaign":"gse4Ry","campaign_step":"dfar5V"},{"id":"gd7TdO","created":1571443200,"type":"nps","nps-score":8,"star-rating":null,"happy":null,"comments":null,"platform_name":"The Review Site","subscriber":"pl6R4s","subscriber_name":"John Doe","subscriber_email":"johndoe@email.com","location":"pr64Ct","campaign":"gse4Ry","campaign_step":"dfar5V"},{"id":"dfar5V","created":1571443200,"type":"star-rating","nps-score":null,"star-rating":4,"happy":null,"comments":null,"platform_name":"Acme Reviews","subscriber":"vnsRE4","subscriber_name":"Ciro Marzio","subscriber_email":"ciro@email.com","location":"pr64Ct","campaign":"gse4Ry","campaign_step":"o4eWWf"}]}
                              

Feedback Request

Feedback request objects represent a stand-alone feedback request sent to a customer in your account. This is usually a text message or an email sent to request feedback and / or a review.

https://optimumfeedback.com/api/v1.2/feedback-request

The Feedback Request Object

Attributes
  • id

    Unique identifier for the feedback request.

  • created timestamp

    Time at which the object was created (i.e. when the request was made). Measured in seconds since the Unix epoch.

  • due timestamp

    Scheduled time at which the feedback request is to be sent if not immediately. Measured in seconds since the Unix epoch.

  • updated timestamp

    Time at which the object was updated (i.e. when the request was responded to, a message opened or when feedback was left). Measured in seconds since the Unix epoch.

  • subscriber string

    The ID of the subscriber who left feedback if available.

  • template string

    The ID of the message template used. Message template IDs can be found by signing into the app and heading to Campaigns > Message Templates.

  • location string

    The ID of the location to send feedback from.

  • type string

    The type of template that was sent, typically sms or email.

  • message_opened boolean

    Whether or not the message has been opened. Please note that open tracking is not available for SMS text messages.

  • message_clicked boolean

    Whether or not the link to the feedback page has been clicked.

  • message_bounced boolean

    Whether or not the message bounced (email only).

  • bounce_reason string

    If a message bounced, what was the reason (email only).

  • spam_complaint boolean

    Whether or not the recipient reported the message as spam (email only).

  • feedback object

    Any feedback left by the customer, represented as a Feedback object.

Feedback Request Object
                                 

                                    {"id":"gd7TdO","created":1571356800,"due":1571356800,"updated":1571443200,"subscriber":"gse4Ry","template":"dfar5V","location":"re4SWf","type":"email","message_opened":true,"message_clicked":true,"message_bounced":false,"bounce_reason":null,"spam_complaint":false,"feedback":{"id":"gse4Ry","created":1571443200,"type":"happy","nps-score":null,"star-rating":null,"happy":false,"comments":"I guess I was expecting more. A disappointing experience","platform_name":null,"subscriber":"ax34eW","subscriber_name":"Jane Doe","subscriber_email":"janedoe@email.com","location":"pr64Ct","campaign":null,"campaign_step":null}}

                                 
                              

Create a Feedback Request

To create a new stand-alone feedback request you create a feedback request object.

Arguments
  • subscriber required

    The ID of the subscriber to send the feedback request to.

  • template required

    The ID of the message template to be used. Message template IDs can be found by signing into the app and heading to Campaigns > Message Templates.

  • location required

    The ID of the location to send feedback from.

  • due optional

    Scheduled time at which the feedback request is to be sent if not immediately. Measured in seconds since the Unix epoch.

Send a Feedback Request
$ curl https://optimumfeedback.com/api/v1.2/feedback-request/ \
-u example_api_token_12334: \
-d subscriber="gse4Ry" \
-d template="dfar5V"

                                 {"id":"gd7TdO","created":1571443200,"due":1571443200,"updated":1571443200,"subscriber":"gse4Ry","template":"dfar5V","location":"re4SWf","type":"email","message_opened":false,"message_clicked":false,"message_bounced":false,"bounce_reason":null,"spam_complaint":false,"feedback":null}
                              

Retrieve Feedback Request

Retrieves details of a stand-alone feedback request. You need only supply the feedback request's unique id.

Arguments
  • id required

    The identifier of the feedback request to be returned

Retrieve Feedback Request
https://optimumfeedback.com/api/v1.2/feedback-request/gd7TdO \
-u example_api_token_12334:

                                 {"id":"gd7TdO","created":1571356800,"due":1571356800,"updated":1571443200,"subscriber":"gse4Ry","template":"dfar5V","location":"re4SWf","type":"email","message_opened":true,"message_clicked":true,"message_bounced":false,"bounce_reason":null,"spam_complaint":false,"feedback":{"id":"gse4Ry","created":1571443200,"type":"happy","nps-score":null,"star-rating":null,"happy":false,"comments":"I guess I was expecting more. A disappointing experience","platform_name":null,"subscriber":"ax34eW","subscriber_name":"Jane Doe","subscriber_email":"janedoe@email.com","location":"pr64Ct","campaign":null,"campaign_step":null}}
                              

List all Feedback Requests

Returns a list of stand-alone feedback requests. Feedback requests are returned sorted by the request creation date by default with the newest requests appearing first.

Attributes
  • created_before optional

    A filter on the list based on the created field with this being the upper limit. The value is a string with an integer Unix timestamp

  • created_after optional

    A filter on the list based on the created field with this being the lower limit. The value is a string with an integer Unix timestamp

  • due_before optional

    A filter on the list based on the due field with this being the upper limit. The value is a string with an integer Unix timestamp

  • due_after optional

    A filter on the list based on the due field with this being the lower limit. The value is a string with an integer Unix timestamp

  • updated_before optional

    A filter on the list based on the updated field with this being the upper limit. The value is a string with an integer Unix timestamp

  • updated_after optional

    A filter on the list based on the updated field with this being the lower limit. The value is a string with an integer Unix timestamp

  • subscriber optional

    A filter on the ID of the subscriber the request was sent to.

  • template optional

    A filter on the message template ID to return. Message template IDs can be found by signing into the app and heading to Campaigns > Message Templates.

  • location optional

    A filter on the ID of the location feedback was sent from.

  • message_opened optional

    A boolean value representing whether the message sent was clicked.

  • message_clicked optional

    A boolean value representing whether the link in the message was clicked.

  • message_bounced optional

    Whether or not the message bounced (email only).

  • spam_complaint optional

    Whether or not the recipient reported the message as spam (email only).

List all Feedback Requests
GET https://optimumfeedback.com/api/v1.2/feedback-request
$ curl https://optimumfeedback.com/api/v1.2/feedback-request?limit=20&created_after=1546300800 \
-u example_api_token_12334: \
-G

                                 {"page":1,"total_count":3,"total_returned":3,"data":[{"id":"gd7TdO","created":1571356800,"due":1571356800,"updated":1571443200,"subscriber":"gse4Ry","template":"dfar5V","location":"re4SWf","type":"email","message_opened":true,"message_clicked":true,"message_bounced":false,"bounce_reason":null,"spam_complaint":false,"feedback":{"id":"gse4Ry","created":1571443200,"type":"happy","nps-score":null,"star-rating":null,"happy":false,"comments":"I guess I was expecting more. A disappointing experience","platform_name":null,"subscriber":"ax34eW","subscriber_name":"Jane Doe","subscriber_email":"janedoe@email.com","location":"pr64Ct","campaign":null,"campaign_step":null}},{"id":"gd7TdO","created":1571443200,"due":1571443200,"updated":1571443200,"subscriber":"gse4Ry","template":"dfar5V","location":"re4SWf","type":"email","message_opened":false,"message_clicked":false,"message_bounced":false,"bounce_reason":null,"spam_complaint":false,"feedback":null},{"id":"gse4Ry","created":1571011200,"due":1571184000,"updated":1571184000,"subscriber":"pr64Ct","template":"iF56sC","location":"re4SWf","type":"sms","message_opened":true,"message_clicked":true,"message_bounced":false,"bounce_reason":null,"spam_complaint":false,"feedback":{"id":"dfar5V","created":1571443200,"type":"star-rating","nps-score":null,"star-rating":4,"happy":null,"comments":null,"platform_name":"Acme Reviews","subscriber":"vnsRE4","subscriber_name":"Ciro Marzio","subscriber_email":"ciro@email.com","location":"pr64Ct"}}]}
                              

Client Accounts

Account objects represent the companies or client accounts that you create and manage. The API allows you to create and update your client accounts in addition to making them inactive. You can retrieve individual account details as well as a list of all your accounts.

https://optimumfeedback.com/api/v1.2/accounts

The Account Object

Attributes
  • id

    Unique identifier for the account.

  • created timestamp

    Time at which the object was created. Measured in seconds since the Unix epoch.

  • name string

    The company or account name.

  • active boolean

    Whether the account is active or inactive.

  • max_locations integer

    The account's location limit. No value (null) represents unlimited locations.

  • max_users integer

    The account's user limit. No value (null) represents unlimited users.

  • max_campaigns integer

    The account's campaign limit. No value (null) represents unlimited campaigns.

  • sms_allowance integer

    The account's monthly SMS limit. No value (null) represents unlimited SMS messages.

  • active_locations integer

    Total active locations attached to this account.

  • active_users integer

    Total active client users.

Account Object
                                 

                                    {"id":"gd7TdO","created":1571443200,"name":"Savastano and Son","active":true,"max_locations":10,"max_users":3,"max_campaigns":1,"sms_allowance":100,"active_locations":5,"active_users":1}

                                 
                              

Create an Account

To create a new client account you create an account object.

Arguments
  • name required

    The company or account name.

  • active required

    A boolean value representing whether the account is active or inactive. Inactive accounts do not affect billing until they are made active.

  • verb required

    What action consumers typically take with this company. Possible values are use or visit. This will affect how standard templates are written, for example "Thank you for visiting X" or "Thank you for using X".

  • account_template optional, default is null

    The id of an account template to use in creating this account.

  • max_locations optional, default is null

    The account's location limit. No value (null) represents unlimited locations.

  • max_users optional, default is null

    The account's user limit. No value (null) represents unlimited users.

  • max_campaigns optional, default is null

    The account's campaign limit. No value (null) represents unlimited campaigns.

  • sms_allowance optional, default is null

    The account's monthly SMS limit. No value (null) represents unlimited SMS messages.

Create an Account
$ curl https://optimumfeedback.com/api/v1.2/accounts/ \
-u example_api_token_12334: \
-d name="Savastano and Son" \
-d active=true \
-d verb="use"

                                 {"id":"gd7TdO","created":1571443200,"name":"Savastano and Son","active":true,"max_locations":null,"max_users":null,"max_campaigns":null,"sms_allowance":null,"active_locations":0,"active_users":0}
                              

Retrieve an Account

Retrieves the details of an existing client account. You need only supply the unique id that was returned upon account creation.

Arguments
  • id required

    The identifier of the account to be returned

Retrieve an account
https://optimumfeedback.com/api/v1.2/accounts/gd7TdO \
-u example_api_token_12334:

                                 {"id":"gd7TdO","created":1571443200,"name":"Savastano and Son","active":true,"max_locations":10,"max_users":3,"max_campaigns":1,"sms_allowance":100,"active_locations":5,"active_users":1}
                              

Update an Account

Updates the specified cilent account by setting the values of the parameters passed. Any parameters not provided will be left unchanged. For example, if you pass the active parameter, you can toggle the account active or inactive.

This request accepts mostly the same arguments as the create account call.

Arguments
  • name optional

    The company or account name.

  • active optional

    A boolean value representing whether the account is active or inactive. Inactive accounts do not affect billing until they are made active.

  • max_locations optional

    The account's location limit. No value (null) represents unlimited locations.

  • max_users optional

    The account's user limit. No value (null) represents unlimited users.

  • max_campaigns optional

    The account's campaign limit. No value (null) represents unlimited campaigns.

  • sms_allowance optional

    The account's monthly SMS limit. No value (null) represents unlimited SMS messages.

Update an Account
POST https://optimumfeedback.com/api/v1.2/accounts/{id}
$ curl https://optimumfeedback.com/api/v1.2/accounts/gd7TdO \
-u example_api_token_12334: \
-d max_locations=100 \
-d sms_allowance="2000"

                                                                  {"id":"gd7TdO","created":1571443200,"name":"Savastano and Son","active":true,"max_locations":100,"max_users":null,"max_campaigns":null,"sms_allowance":"2000","active_locations":0,"active_users":0}
                              

Delete an Account

Removes a client account. This will cancel all campaigns and messages for this account in addition to preventing landing pages and kiosk pages from working. If you wish to make an account inactive instead, please use the Update API call.

Arguments
  • id required

    The id of the client account to remove.

Delete an Account
DELETE https://optimumfeedback.com/api/v1.2/accounts/{id}
$ curl https://optimumfeedback.com/api/v1.2/accounts/gd7TdO \
-u example_api_token_12334: \
-X DELETE

                                 {"id":"gd7TdO","deleted":true}
                              

List all Accounts

Returns a list of your client accounts. The accounts are returned sorted by created date, with the most recently created accounts appearing first.

Attributes
  • created_before optional

    A filter on the list based on the created field with this being the upper limit. The value is a string with an integer Unix timestamp

  • created_after optional

    A filter on the list based on the created field with this being the lower limit. The value is a string with an integer Unix timestamp

  • name required

    The company or account name.

  • active required

    A boolean value representing whether the account is active or inactive. Inactive accounts do not affect billing until they are made active.

List all Accounts
GET https://optimumfeedback.com/api/v1.2/accounts
$ curl https://optimumfeedback.com/api/v1.2/accounts?limit=20&created_after=1483228800 \
-u example_api_token_12334: \
-G

                                 {"page":1,"total_count":3,"total_returned":3,"data":[{"id":"gse4Ry","created":1571443200,"name":"Drogas la Rebaja","active":true,"max_locations":5,"max_users":10,"max_campaigns":3,"sms_allowance":2000,"active_locations":2,"active_users":4},{"id":"gd7TdO","created":1571443200,"name":"Savastano and Son","active":true,"max_locations":10,"max_users":3,"max_campaigns":1,"sms_allowance":100,"active_locations":5,"active_users":1},{"id":"dfar5V","created":1571443200,"name":"B613","active":true,"max_locations":1,"max_users":1,"max_campaigns":1,"sms_allowance":5000,"active_locations":1,"active_users":1}]}