API Reference

The Optimum Feedback 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/. 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/

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/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/subscribers?limit=20&created_after=1544686176 \
-u example_api_token_12334: \
-G

                                 {"page":1,"total_count":3,"total_returned":3,"data":[{"id":"gd7TdO","created":1544659200,"email":"subscriber@optimumfeedback.com","mobile_number":"+1813555555","fname":"Jane","sname":"Doe","last_sms":1544686176,"last_email":null,"country_code":"US","invalid":false,"opt_out":false,"locations":["xd3S6","iF56sC"]},{"id":"gse4Ry","created":1544659200,"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":1544659200,"email":"subscriber3@optimumfeedback.com","mobile_number":"+447810123456","fname":"Ciro","sname":"Marzio","last_sms":1544686176,"last_email":1544659200,"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.

Subscribers

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

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

The Subscriber Object

Attributes
  • id

    Unique identifier for the subscriber.

  • created timestamp

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

  • email string

    The subscriber’s email address.

  • mobile_number string

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

  • fname string

    The subscriber’s first name.

  • sname string

    The subscriber’s last / family name.

  • last_sms timestamp

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

  • last_email timestamp

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

  • country_code string

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

  • invalid boolean

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

  • opt_out boolean

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

  • locations array

    An array of location IDs that the subscriber belongs to.

Subscriber Object
                                 

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

                                 
                              

Create Subscriber

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

If you attempt to create a subscriber 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 subscriber.

Arguments
  • email optional *, default is null

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

  • mobile_number optional *, default is null

    A string representing the subscriber’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 subscriber’s first name.

  • sname optional, default is null

    The subscriber’s last / family name.

  • country_code required

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

  • location required

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

Create Subscriber
$ curl https://optimumfeedback.com/api/v1/subscribers/ \
-u example_api_token_12334: \
-d mobile_number="+1813555555" \
-d email="subscriber@optimumfeedback.com" \
-d country_code="US" \
-d location="xS4rtY"

                                 {"id":"gd7TdO","created":1544659200,"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 Subscriber

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

Arguments
  • id required

    The identifier of the subscriber to be returned

Retrieve a Subscriber
https://optimumfeedback.com/api/v1/subscribers/gd7TdO \
-u example_api_token_12334:

                                 {"id":"gd7TdO","created":1544659200,"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 Subscriber

Updates the specified subscriber 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 subscriber’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 subscriber call.

Arguments
  • email optional

    A string representing the subscriber’s email address.

  • mobile_number optional

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

  • fname optional

    The subscriber’s first name.

  • sname optional

    The subscriber’s last / family name.

  • country_code optional

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

  • opt_out optional

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

  • location_add optional

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

  • location_remove optional

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

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

                                                                  {"id":"gd7TdO","created":1544659200,"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 Subscriber

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

Arguments
  • id required

    The id of the subscriber to remove.

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

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

List all Subscribers

Returns a list of your subscribers. The subscribers are returned sorted by created date, with the most recent subscribers 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 subscriber’s email address. The value is a string

  • mobile_number optional

    A filter on the subscriber’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 subscriber’s first name. The value is a string

  • sname optional

    A filter on the subscriber’s last / family name. The value is a string

  • country_code optional

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

  • invalid optional

    A filter to only return subscribers 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 subscribers based on their opt-out status. The value is a boolean representing opted out by TRUE and not opted out by FALSE

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

                                 {"page":1,"total_count":3,"total_returned":3,"data":[{"id":"gd7TdO","created":1544659200,"email":"subscriber@optimumfeedback.com","mobile_number":"+1813555555","fname":"Jane","sname":"Doe","last_sms":1544686176,"last_email":null,"country_code":"US","invalid":false,"opt_out":false,"locations":["xd3S6","iF56sC"]},{"id":"gse4Ry","created":1544659200,"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":1544659200,"email":"subscriber3@optimumfeedback.com","mobile_number":"+447810123456","fname":"Ciro","sname":"Marzio","last_sms":1544686176,"last_email":1544659200,"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/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":1544659200,"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/locations
$ curl https://optimumfeedback.com/api/v1/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":1544659200,"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/locations/gd7TdO \
-u example_api_token_12334:

                                 {"id":"gd7TdO","created":1544659200,"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/locations/{id}
$ curl https://optimumfeedback.com/api/v1/locations/gd7TdO \
-u example_api_token_12334: \
-d name="The HyperRing"

                                                                  {"id":"gd7TdO","created":1544659200,"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/locations/{id}
$ curl https://optimumfeedback.com/api/v1/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/locations
$ curl https://optimumfeedback.com/api/v1/locations?limit=20&created_after=1483228800 \
-u example_api_token_12334: \
-G

                                 {"page":1,"total_count":3,"total_returned":3,"data":[{"id":"gse4Ry","created":1544659200,"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":1544659200,"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":1544659200,"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/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":1544659200,"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/reviews/gd7TdO \
-u example_api_token_12334:

                                 {"id":"gd7TdO","created":1544659200,"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/reviews
$ curl https://optimumfeedback.com/api/v1/reviews?limit=20&created_after=1483228800 \
-u example_api_token_12334: \
-G

                                 {"page":1,"total_count":3,"total_returned":3,"data":[{"id":"gse4Ry","created":1544659200,"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":1544659200,"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":1544659200,"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/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 happy

  • 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":1544659200,"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","campaign_step_type":"sms"}

                                 
                              

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/feedback/gd7TdO \
-u example_api_token_12334:

                                 {"id":"gd7TdO","created":1544659200,"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","campaign_step_type":"sms"}
                              

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/feedback
$ curl https://optimumfeedback.com/api/v1/feedback?limit=20&created_after=1483228800 \
-u example_api_token_12334: \
-G

                                 {"page":1,"total_count":3,"total_returned":3,"data":[{"id":"gse4Ry","created":1544659200,"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","campaign_step_type":"sms"},{"id":"gd7TdO","created":1544659200,"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","campaign_step_type":"sms"},{"id":"dfar5V","created":1544659200,"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","campaign_step_type":"email"}]}
                              

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/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":1544659200,"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/accounts/ \
-u example_api_token_12334: \
-d name="Savastano and Son" \
-d active=true \
-d verb="use"

                                 {"id":"gd7TdO","created":1544659200,"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/accounts/gd7TdO \
-u example_api_token_12334:

                                 {"id":"gd7TdO","created":1544659200,"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/accounts/{id}
$ curl https://optimumfeedback.com/api/v1/accounts/gd7TdO \
-u example_api_token_12334: \
-d max_locations=100 \
-d sms_allowance="2000"

                                                                  {"id":"gd7TdO","created":1544659200,"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/accounts/{id}
$ curl https://optimumfeedback.com/api/v1/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/accounts
$ curl https://optimumfeedback.com/api/v1/accounts?limit=20&created_after=1483228800 \
-u example_api_token_12334: \
-G

                                 {"page":1,"total_count":3,"total_returned":3,"data":[{"id":"gse4Ry","created":1544659200,"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":1544659200,"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":1544659200,"name":"B613","active":true,"max_locations":1,"max_users":1,"max_campaigns":1,"sms_allowance":5000,"active_locations":1,"active_users":1}]}