Introduction

Welcome to Positively's API documentation! We'll help guide you towards implementing the Positively Web API.

Authentication

To use the Positively API, you'll need a private API key. Please treat your key like you'd treat any sensitive information like a password.

Please log in or sign up to see your API key.

All API requests must be made via HTTPS, authenticated with HTTP Basic Authentication. Use your API key as the username, and leave the password blank (use an empty string).

Rate-limiting

To ensure a high level of service for all Positively customers, your use of the API is rate-limited. We've intentionally set rate-limits to greatly exceed normal usage rates, so you shouldn't see them outside of buggy scripts or bulk imports.

Our API will start returning 429 HTTP response codes; if you start receiving these, you should throttle your use of the API.

If the rate-limit is getting in the way of your normal use, please contact us.

Errors

All successful requests return a 200 HTTP status code.

All errors return an appropriate error code with the following JSON, specifying an error type and an error message:

{"type": "error_type",
 "message": "One or more error messages separated by commas"}

The possible error types and their associated status codes are below:

Type Status code(s) Description
authentication_error
401
The API request could not be authenticated. Check your API key.
rate_limit_error
429
You've hit our request rate limit (see section above).
server_error
500
We experienced an error on our servers; retry later.
not_found
404
The resource was not found.
invalid_request_error
422, 412
The request was invalid. May be due to invalid or missing parameters (status code 422) or throttling (code 412).
Customers

Create or update information about a customer in your database.

List customers
Definition
GET https://positively.co/api/v1/customers
Example response
[{"id": "zJVs4z",
  "email": "egnition_sample_8@egnition.com",
  "first_name": "Laura",
  "last_name": "Garcia",
  "properties": 
   {"orders_count": 0,
    "total_spent": "0.0",
    "products_ordered": []},
  "last_surveyed_at": 0,
  "created_at": 1513975644},
 {"id": "BDas7X",
  "email": "egnition_sample_7@egnition.com",
  "first_name": "Gary",
  "last_name": "Stone",
  "properties": 
   {"orders_count": 1,
    "total_spent": "10.0"},
  "last_surveyed_at": 0,
  "created_at": 1513975643}]
Parameters
Name Type Description
since
Integer UTC timestamp to filter
until
Integer UTC timestamp to filter
Create a customer
Definition
POST https://positively.co/api/v1/customers
Example response
{"id": "BDas7X",
"email": "egnition_sample_7@egnition.com",
"first_name": "Gary",
"last_name": "Stone",
"properties": 
 {"orders_count": 1,
  "total_spent": "10.0"},
"last_surveyed_at": 0,
"created_at": 1513975643}
Parameters
Name Type Description
email
String Email of customer. Must be unique across your entire product.
name
String Your customer's name.
properties
Hash/Dictionary Custom properties associated with this customer. You can set whatever you'd like here in order to filter survey responses later.
Get a customer
Definition
GET https://positively.co/api/v1/customers/{id or email}
Example response
{"id": "BDas7X",
 "email": "egnition_sample_7@egnition.com",
 "first_name": "Gary",
 "last_name": "Stone",
 "properties":
   {"orders_count": 0,
    "total_spent": "0.0",
    "products_ordered": [],
    "last_order_fulfilled_at": null},
 "last_surveyed_at": 0,
 "created_at": 1513975643}
Surveys

Send NPS surveys to your customers. You can create a customer and send them a survey with a single call.

List surveys
Definition
GET https://positively.co/api/v1/nps_surveys
Example response
[
  {
    "id": "kzjUJw",
    "trigger": "backfill",
    "medium": "email",
    "surveyed_at": 1513193641,
    "score_completed_at": null,
    "note_completed_at": null,
    "completed_at": null,
    "score": null,
    "note": null,
    "customer_id": "zdmsZE",
    "send_at": 1513193539,
    "reminder_sent_at": null,
    "created_at": 1513193539,
    "email": "example1@email.com"
  },
  {
    "id": "aV7UDP",
    "trigger": "web_interface",
    "medium": "email",
    "surveyed_at": 1513194527,
    "score_completed_at": 1513194691,
    "note_completed_at": 1513194698,
    "completed_at": 1513194698,
    "score": 8,
    "note": "I filled out this survey, and here is the reason I chose 8",
    "customer_id": "Bl2s24",
    "send_at": 1513194509,
    "reminder_sent_at": null,
    "created_at": 1513194509,
    "email": "example2@email.com"
  }
]
Send a survey
Definition
POST https://positively.co/api/v1/nps_surveys

To send a survey later, specify a delay parameter in seconds.

Note: if sending a survey to the email you specify would violate the throttling settings you've set, you'll receive this response with a 412 status code:

{"type": "invalid_request_error",
 "message": "Customer has been surveyed recently"}
Example response
{"id": "kpDU1r",
 "trigger": "web_api",
 "medium": "email",
 "surveyed_at": null,
 "score_completed_at": null,
 "note_completed_at": null,
 "completed_at": null,
 "score": null,
 "note": null,
 "customer_id": "XO7sjr",
 "send_at": 1515692821,
 "reminder_sent_at": null,
 "created_at": 1515692821,
 "email": "example@email.com"}
Parameters
Name Type Description
delay
Integer Seconds to delay sending the survey. By default, the survey is sent as soon as possible.
email
String Email of customer. Must be unique across your entire product.
name
String Your customer's name.
properties
Hash/Dictionary Custom properties associated with this customer. You can set whatever you'd like here in order to filter survey responses later. See the Customers definitions above for more information.
Update a survey

The most common reason to update a survey is to change the delay if one was specified when the survey was created. If the survey has already been sent, setting a delay will return an error.

You can pass the email or ID of the customer, or the ID of the survey itself.

Definition
POST https://positively.co/api/v1/nps_surveys/{id or email}
PATCH https://positively.co/api/v1/nps_surveys/{id or email}
Example response
{"surveyed_at": null,
 "send_at": 1515694866,
 "id": "X2EUJR",
 "customer_id": "QgJsR1",
 "score": null,
 "note": null,
 "trigger": "web_api",
 "medium": "email",
 "score_completed_at": null,
 "note_completed_at": null,
 "completed_at": null,
 "reminder_sent_at": null,
 "created_at": 1515693041,
 "email": "example@email.com"}
Parameters
Name Type Description
delay
Integer Seconds to delay sending the survey. By default, the survey is sent as soon as possible. Set to `null` to cancel sending a survey.
Get a survey
Definition
GET https://positively.co/api/v1/nps_surveys/{id or email}

You can pass the email or ID of the customer, or the ID of the survey itself.

Example response
{"id": "kzjUJw",
 "trigger": "backfill",
 "medium": "email",
 "surveyed_at": 1513193641,
 "score_completed_at": null,
 "note_completed_at": null,
 "completed_at": null,
 "score": null,
 "note": null,
 "customer_id": "zdmsZE",
 "send_at": 1513193539,
 "reminder_sent_at": null,
 "created_at": 1513193539,
 "email": "xxx@gmail.com"}
Metrics

This endpoint returns your calculated NPS score.

Get metrics
Definition
GET https://positively.co/api/v1/metrics
Example response
{"trailing_30_days": 36.71,
 "last_trailing_30_days": 34.10}
Opt-outs

Opt-outs represent users that have opted out from surveys for your product. You may want to use the API to sync user preferences between your own database and Positively; for example, not sending surveys to users who have unsubscribed from your main mailing list.

List opt-outs
Definition
GET https://positively.co/api/v1/opt_outs
Example response
[{"email": "example1@email.com",
  "created_at": 1513194747,
  "customer_id": "Rl2s24"},
 {"email": "example2@email.com",
  "created_at": 1515563368,
  "customer_id": "B6ssp5"},
 {"email": "example3@email.com",
  "created_at": 1515594351}]
Create an opt-out
Definition
POST https://positively.co/api/v1/opt_outs
Example response
{"email": "example4@gmail.com",
 "created_at": 1515693369}
Parameters
Name Type Description
email
String Email to opt-out. Required.
Delete an opt-out
Definition
DELETE https://positively.co/api/v1/opt_outs/{email}
Example response
{"deleted": true,
 "email": "example1@email.com"}
Webhooks

You can programmatically manage webhooks for receiving events from Positively. We'll send a POST to any endpoint you specify with the following data:

Webhook data
Name Type Description
event
String Type of event. Currently there are two events: nps_survey.updated and opt_out.created
token
String A secret token we generate for your webhook. You can optionally use this to confirm that the POST is actually coming from Positively.
nps_survey
Hash/Dictionary (Only for nps_survey.updated) The survey data, as if you had done a GET request for the survey itself. See the example below or the documentation for the Surveys endpoint.
customer
Hash/Dictionary (Only for opt_out.created) The customer data, as if you had done a GET request for the customer themselves. See the example below or the documentation for the Customers endpoint.
Example POST: nps_survey.updated
{"event": "nps_survey.updated",
 "token": "YOUR-WEBHOOK-TOKEN",
 "nps_survey":
  {"id": "nPjUx6",
   "trigger": "web_api",
   "medium": "email",
   "surveyed_at": 1515695022,
   "score_completed_at": 1515703597,
   "note_completed_at": null,
   "completed_at": 1515703597,
   "score": 5,
   "note": null,
   "customer_id": "QNPs7D",
   "send_at": 1515694998,
   "reminder_sent_at": null,
   "created_at": 1515694998,
   "email": "email@example.com"}
Example POST: nps_survey.updated
{"event": "opt_out.created",
 "token": "YOUR-WEBHOOK-TOKEN",
 "email": "email@example.com",
 "customer":
  {"id": "YehDIH",
   "email": "email@example.com",
   "first_name": nil,
   "last_name": nil,
   "properties": {"user_id": "4736"},
   "last_surveyed_at": 1516743247,
   "created_at": 1516743247}}
List webhooks
Definition
GET https://positively.co/api/v1/webhooks
Example response
[{"id": "9jJh49",
  "product_id": 7,
  "url": "https://example.com/webhooks/positively",
  "description": null,
  "token": "9DS2AF$vjk_7Wx!%n",
  "enabled": false,
  "created_at": 1513698181,
  "updated_at": 1515211454}]
Create a webhook
Definition
POST https://positively.co/api/v1/webhooks
Example response
{"id": "7AkhwR",
"url": "https://google.com",
"description": null,
"token": "Zvx152yUX1J81oqKqxKg",
"enabled": false,
"created_at": 1515694036,
"updated_at": 1515694036}
Parameters
Name Type Description
url
String URL of the webhook. Required.
description
String Description of the webhook for your own use.
enabled
Boolean Whether or not the webhook should receive POSTs from Positively. Default: true.
Update a webhook
Definition
POST https://positively.co/api/v1/webhooks/{id}
PATCH https://positively.co/api/v1/webhooks/{id}
Example response

Returns the same format as the create webhook above.

Delete a webhook
Definition
DELETE https://positively.co/api/v1/webhooks/{id}
Example response
{"deleted": true,
 "id": "7AkhwR"}