Promoter API

Suggest Edits

Introduction

 

Welcome to the Promoter API! You can use our API to access endpoints, which can get information on various contacts, feedback, and campaign metrics in our database.

We have a robust API to provide tons of options for all needs, but the most popular use is triggering to send surveys, found in the Contacts section below.

API Rate Limiting

Based on your plan, you will be allowed an API request rate of X requests per minute. Your limit can be found by visiting the "API" section of your account.

When the requests per minute exceed the allotment, you will receive the following:

A response status code of: 429 (Too many Requests)
A response body of:

{ "detail": "Request was throttled. Expected available in 42.0 seconds."}

A response header to inform of the client when in time you can retry the call:

Suggest Edits

Authentication

 

Promoter uses API keys to allow access to the API. You can register for a Promoter Account and access the API key in your main account settings under 'API'. Promoter expects for the API key to be included in all API requests to the server in a header that looks like the following: Authorization: Token YOUR_API_KEY. The key should be prefixed by the string literal "Token", with whitespace separating the two strings.

With curl, you can pass the correct header with each request curl "https://app.promoter.io/api".

Suggest Edits

Error Codes

 
Error Code
Message
Meaning

403

Forbidden

The resource requested is hidden for administrators only

404

Not Found

The specified resource could not be found

405

Method Not Allowed

You tried to access a resource with an invalid method

406

Not Acceptable

You requested a format that isn’t json

410

Gone

The resource requested has been removed from our servers

429

Too Many Requests

You’re requesting too much! Slow down!

500

Internal Server Error

We had a problem with our server. Try again later.

503

Service Unavailable

We’re temporarily offline for maintenance. Please try again later.

Suggest Edits

Survey a contact

 
posthttps://app.promoter.io/api/contacts/survey/
curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Authorization: Token YOUR_API_KEY" \
     --data-binary "{
    \"campaign\":99, 
    \"email\":\"kate@mac.com\", 
    \"first_name\":\"Kate\", 
    \"last_name\":\"Bell\", 
    \"attributes\":{
        \"plan\":\"bronze\"
    }
}" \
'https://app.promoter.io/api/contacts/survey/'
var request = new XMLHttpRequest();

request.open('POST', 'https://app.promoter.io/api/contacts/survey/
');

request.setRequestHeader('Content-Type', 'application/json');
request.setRequestHeader('Authorization', 'Token YOUR_API_KEY');

request.onreadystatechange = function () {
  if (this.readyState === 4) {
    console.log('Status:', this.status);
    console.log('Headers:', this.getAllResponseHeaders());
    console.log('Body:', this.responseText);
  }
};

var body = {
  'campaign': 99,
  'email': 'kate@mac.com',
  'first_name': 'Kate',
  'last_name': 'Bell',
  'attributes': {
    'plan': 'bronze'
  }
};

request.send(JSON.stringify(body));
from urllib2 import Request, urlopen

values = """
  {
    "campaign": 99,
    "email": "kate@mac.com",
    "first_name": "Kate",
    "last_name": "Bell",
    "attributes": {
      "plan": "bronze"
    }
  }
"""

headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Token YOUR_API_KEY'
}
request = Request('https://app.promoter.io/api/contacts/survey/
', data=values, headers=headers)

response_body = urlopen(request).read()
print response_body
require 'rubygems' if RUBY_VERSION < '1.9'
require 'rest_client'

values = '{
  "campaign": 99,
  "email": "kate@mac.com",
  "first_name": "Kate",
  "last_name": "Bell",
  "attributes": {
    "plan": "bronze"
  }
}'

headers = {
  :content_type => 'application/json',
  :authorization => 'Token YOUR_API_KEY'
}

response = RestClient.post 'https://app.promoter.io/api/contacts/survey/
', values, headers
puts response
// Maven : Add these dependecies to your pom.xml (java6+)
// <dependency>
//     <groupId>org.glassfish.jersey.core</groupId>
//     <artifactId>jersey-client</artifactId>
//     <version>2.8</version>
// </dependency>
// <dependency>
//     <groupId>org.glassfish.jersey.media</groupId>
//     <artifactId>jersey-media-json-jackson</artifactId>
//     <version>2.8</version>
// </dependency>

import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.MediaType;

Client client = ClientBuilder.newClient();
Entity payload = Entity.json("{  'campaign': 99,  'email': 'kate@mac.com',  'first_name': 'Kate',  'last_name': 'Bell',  'attributes': {    'plan': 'bronze'  }}");
Response response = client.target("https://app.promoter.io/api/contacts/survey/
")
  .request(MediaType.APPLICATION_JSON_TYPE)
  .header("Authorization", "Token YOUR_API_KEY")
  .post(payload);

System.out.println("status: " + response.getStatus());
System.out.println("headers: " + response.getHeaders());
System.out.println("body:" + response.readEntity(String.class));
//Common testing requirement. If you are consuming an API in a sandbox/test region, uncomment this line of code ONLY for non production uses.
//System.Net.ServicePointManager.ServerCertificateValidationCallback = delegate { return true; };

//Be sure to run "Install-Package Microsoft.Net.Http" from your nuget command line.
using System;
using System.Net.Http;

var baseAddress = new Uri("https://app.promoter.io/api/");

using (var httpClient = new HttpClient{ BaseAddress = baseAddress })
{

  
  httpClient.DefaultRequestHeaders.TryAddWithoutValidation("authorization", "Token YOUR_API_KEY");
  
    using (var content = new StringContent("{  \"campaign\": 99,  \"email\": \"kate@mac.com\",  \"first_name\": \"Kate\",  \"last_name\": \"Bell\",  \"attributes\": {    \"plan\": \"bronze\"  }}", System.Text.Encoding.Default, "application/json"))
    {
      using (var response = await httpClient.PostAsync("undefined", content))
      {
        string responseData = await response.Content.ReadAsStringAsync();
      }
  }
}
<?php
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "https://app.promoter.io/api/contacts/survey/
");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, FALSE);

curl_setopt($ch, CURLOPT_POST, TRUE);

curl_setopt($ch, CURLOPT_POSTFIELDS, "{
  \"campaign\": 99,
  \"email\": \"kate@mac.com\",
  \"first_name\": \"Kate\",
  \"last_name\": \"Bell\",
  \"attributes\": {
    \"plan\": \"bronze\"
  }
}");

curl_setopt($ch, CURLOPT_HTTPHEADER, array(
  "Content-Type: application/json",
  "Authorization: Token YOUR_API_KEY"
));

$response = curl_exec($ch);
curl_close($ch);

var_dump($response);
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "id": 744011,                           
    "email": "kate@mac.com",                
    "first_name": "Kate",                   
    "last_name": "Bell",                   
    "created_date": "2014-12-12T10:00:00Z", 
    "unsubscribed": "false",                
    "attributes": {                         
        "plan": "bronze"
        }
}

Body Params

campaign
string
required

Id of the campaign you're surveying from

email
string
required

Email of your contact

first_name
string

First name of your contact

last_name
string

Last name of your contact

attributes
mixed type

A dictionary of key value pairs of custom attributes that will be associated with the contact.

unsubscribed
boolean

Update a contact's subscription status. If passing "true", then this contact will no longer receive surveys. Default is "false".

Headers

Authorization
string
required

This is where you'll provide your API key, after inserting the word 'Token' and a space

Content-Type
string
required

Must be "application/json"

 
  1. Before surveying contacts via the API, you'll need to first create a campaign in your account.
  2. Once the campaign is created, you'll visit the API settings in the "Integrations" section.
  3. Click to '+ Add Integration' and choose your campaign.
  4. Choose the delivery settings you prefer for surveys being triggered with the API.

When surveying contacts, you can pass in as many attributes as you’d like along with them. These can be useful when filtering your NPS on the campaign dashboard. The minimum requirements for surveying a contact are the contact’s email and the campaign id to survey them from.

  • Depending on your Survey Throttle setting, your contact may not be surveyed if they have been recently surveyed. (Survey Throttle setting can be found in your account settings.)

24 Hour Survey Throttle

Our system has a 24 hour throttle built in so any contact cannot be surveyed more than once in a 24 hour period. Due to this, you may need to use aliases of your email while testing.

Ex: joe+1@mac.com, joe+2@mac.com...

If you would like this temporarily disabled while testing, please write in to support@promoter.io.

Suggest Edits

Update a Contact

 
posthttps://app.promoter.io/api/contacts/
curl --include \
     --request POST \
     --header "Authorization: Token YOUR_API_TOKEN" \
     --header "Content-Type: application/json" \
     --data-binary "{
    \"email\":\"kate@mac.com\",
    \"first_name\":\"Kate\",
    \"last_name\":\"Bell\",
    \"unsubscribed\":\"false\",
    \"attributes\":{
        \"Source\":\"Support Ticket\", 
        \"plan\":\"bronze\", 
        \"Reference\":\"123456\"
    }
}" \
'https://app.promoter.io/api/contacts/'
var request = new XMLHttpRequest();

request.open('POST', 'https://app.promoter.io/api/contacts/
');

request.setRequestHeader('Authorization', 'Token YOUR_API_TOKEN');
request.setRequestHeader('Content-Type', 'application/json');

request.onreadystatechange = function () {
  if (this.readyState === 4) {
    console.log('Status:', this.status);
    console.log('Headers:', this.getAllResponseHeaders());
    console.log('Body:', this.responseText);
  }
};

var body = {
  'contact_list': [
    4865
  ],
  'email': 'kate@mac.com',
  'first_name': 'Kate',
  'last_name': 'Bell',
  'unsubscribed': 'false',
  'attributes': {
    'Source': 'Support Ticket',
    'plan': 'bronze',
    'Reference': '123456'
  }
};

request.send(JSON.stringify(body));
from urllib2 import Request, urlopen

values = """
  {
    "contact_list": [
      4865
    ],
    "email": "kate@mac.com",
    "first_name": "Kate",
    "last_name": "Bell",
    "unsubscribed": "false",
    "attributes": {
      "Source": "Support Ticket",
      "plan": "bronze",
      "Reference": "123456"
    }
  }
"""

headers = {
  'Authorization': 'Token YOUR_API_TOKEN',
  'Content-Type': 'application/json'
}
request = Request('https://app.promoter.io/api/contacts/
', data=values, headers=headers)

response_body = urlopen(request).read()
print response_body
require 'rubygems' if RUBY_VERSION < '1.9'
require 'rest_client'

values = '{
  "contact_list": [
    4865
  ],
  "email": "kate@mac.com",
  "first_name": "Kate",
  "last_name": "Bell",
  "unsubscribed": "false",
  "attributes": {
    "Source": "Support Ticket",
    "plan": "bronze",
    "Reference": "123456"
  }
}'

headers = {
  :authorization => 'Token YOUR_API_TOKEN',
  :content_type => 'application/json'
}

response = RestClient.post 'https://app.promoter.io/api/contacts/
', values, headers
puts response
// Maven : Add these dependecies to your pom.xml (java6+)
// <dependency>
//     <groupId>org.glassfish.jersey.core</groupId>
//     <artifactId>jersey-client</artifactId>
//     <version>2.8</version>
// </dependency>
// <dependency>
//     <groupId>org.glassfish.jersey.media</groupId>
//     <artifactId>jersey-media-json-jackson</artifactId>
//     <version>2.8</version>
// </dependency>

import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.MediaType;

Client client = ClientBuilder.newClient();
Entity payload = Entity.json("{  'contact_list': [    4865  ],  'email': 'kate@mac.com',  'first_name': 'Kate',  'last_name': 'Bell',  'unsubscribed': 'false',  'attributes': {    'Source': 'Support Ticket',    'plan': 'bronze',    'Reference': '123456'  }}");
Response response = client.target("https://app.promoter.io/api/contacts/
")
  .request(MediaType.APPLICATION_JSON_TYPE)
  .header("Authorization", "Token YOUR_API_TOKEN")
  .post(payload);

System.out.println("status: " + response.getStatus());
System.out.println("headers: " + response.getHeaders());
System.out.println("body:" + response.readEntity(String.class));
//Common testing requirement. If you are consuming an API in a sandbox/test region, uncomment this line of code ONLY for non production uses.
//System.Net.ServicePointManager.ServerCertificateValidationCallback = delegate { return true; };

//Be sure to run "Install-Package Microsoft.Net.Http" from your nuget command line.
using System;
using System.Net.Http;

var baseAddress = new Uri("https://app.promoter.io/api/");

using (var httpClient = new HttpClient{ BaseAddress = baseAddress })
{

  httpClient.DefaultRequestHeaders.TryAddWithoutValidation("authorization", "Token YOUR_API_TOKEN");
  
  
    using (var content = new StringContent("{  \"contact_list\": [    4865  ],  \"email\": \"kate@mac.com\",  \"first_name\": \"Kate\",  \"last_name\": \"Bell\",  \"unsubscribed\": \"false\",  \"attributes\": {    \"Source\": \"Support Ticket\",    \"plan\": \"bronze\",    \"Reference\": \"123456\"  }}", System.Text.Encoding.Default, "application/json"))
    {
      using (var response = await httpClient.PostAsync("undefined", content))
      {
        string responseData = await response.Content.ReadAsStringAsync();
      }
  }
}
<?php
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "https://app.promoter.io/api/contacts/
");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, FALSE);

curl_setopt($ch, CURLOPT_POST, TRUE);

curl_setopt($ch, CURLOPT_POSTFIELDS, "{
  \"contact_list\": [
    4865
  ],
  \"email\": \"kate@mac.com\",
  \"first_name\": \"Kate\",
  \"last_name\": \"Bell\",
  \"unsubscribed\": \"false\",
  \"attributes\": {
    \"Source\": \"Support Ticket\",
    \"plan\": \"bronze\",
    \"Reference\": \"123456\"
  }
}");

curl_setopt($ch, CURLOPT_HTTPHEADER, array(
  "Authorization: Token YOUR_API_TOKEN",
  "Content-Type: application/json"
));

$response = curl_exec($ch);
curl_close($ch);

var_dump($response);
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
 {
    "id": 744011,                           
    "email": "kate@mac.com",                
    "first_name": "Kate",                   
    "last_name": "Bell",                    
    "created_date": "2014-12-12T10:00:00Z", 
    "unsubscribed": "false",                
    "attributes": {                         
        "Source": "Support Ticket",
        "Reference": "123456",
        "plan": "bronze"
        }
}

Body Params

contact_list
mixed type

Id of contact list you'd like to add your contact to. Only required when adding. Not required when simply updating contact info.

email
string
required

Email of the contact

first_name
string

First name of the contact

last_name
string

Last name of the contact

attributes
mixed type

A dictionary of key value pairs of custom attributes that will be associated with the contact

Headers

Authorization
string
required

This is where you'll provide your API key, after inserting the word 'Token' and a space

Content-Type
string
required

Must be specified as "application/json"

 

You can add as many attributes as you’d like along with your contact. These can be useful when analyzing NPS data on the campaign dashboard and using the 'Filter Segments' option.

The parameter required when adding a contact is the contact’s email. If you don’t specify a contact list for the contact to be added to, a default list with the name "Default List for (Org Name)" will be automatically created for you, and then the contact will be added to this list.

When updating a contact's info, a contact list does not need to be specified.

This action only adds a contact to a list and does not send them a survey.

Suggest Edits

Unsubscribe a contact and cancel surveys

 
posthttps://app.promoter.io/api/contacts/unsubscribe/
curl --include \
     --request POST \
     --header "Authorization: Token YOUR_API_KEY" \
     --header "Content-Type: application/json" \
     --data-binary "{
    \"emails\":[\"kate@mac.com\"]
}" \
'https://app.promoter.io/api/contacts/unsubscribe/'
var request = new XMLHttpRequest();

request.open('POST', 'https://app.promoter.io/api/contacts/unsubscribe/
');

request.setRequestHeader('Authorization', 'Token YOUR_API_KEY');
request.setRequestHeader('Content-Type', 'application/json');

request.onreadystatechange = function () {
  if (this.readyState === 4) {
    console.log('Status:', this.status);
    console.log('Headers:', this.getAllResponseHeaders());
    console.log('Body:', this.responseText);
  }
};

var body = {
  'emails': [
    'kate@mac.com'
  ]
};

request.send(JSON.stringify(body));
from urllib2 import Request, urlopen

values = """
  {
    "emails": [
      "kate@mac.com"
    ]
  }
"""

headers = {
  'Authorization': 'Token YOUR_API_KEY',
  'Content-Type': 'application/json'
}
request = Request('https://app.promoter.io/api/contacts/unsubscribe/
', data=values, headers=headers)

response_body = urlopen(request).read()
print response_body
require 'rubygems' if RUBY_VERSION < '1.9'
require 'rest_client'

values = '{
  "emails": [
    "kate@mac.com"
  ]
}'

headers = {
  :authorization => 'Token YOUR_API_KEY',
  :content_type => 'application/json'
}

response = RestClient.post 'https://app.promoter.io/api/contacts/unsubscribe/
', values, headers
puts response
// Maven : Add these dependecies to your pom.xml (java6+)
// <dependency>
//     <groupId>org.glassfish.jersey.core</groupId>
//     <artifactId>jersey-client</artifactId>
//     <version>2.8</version>
// </dependency>
// <dependency>
//     <groupId>org.glassfish.jersey.media</groupId>
//     <artifactId>jersey-media-json-jackson</artifactId>
//     <version>2.8</version>
// </dependency>

import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.MediaType;

Client client = ClientBuilder.newClient();
Entity payload = Entity.json("{  'emails': [    'kate@mac.com'  ]}");
Response response = client.target("https://app.promoter.io/api/contacts/unsubscribe/
")
  .request(MediaType.APPLICATION_JSON_TYPE)
  .header("Authorization", "Token YOUR_API_KEY")
  .post(payload);

System.out.println("status: " + response.getStatus());
System.out.println("headers: " + response.getHeaders());
System.out.println("body:" + response.readEntity(String.class));
//Common testing requirement. If you are consuming an API in a sandbox/test region, uncomment this line of code ONLY for non production uses.
//System.Net.ServicePointManager.ServerCertificateValidationCallback = delegate { return true; };

//Be sure to run "Install-Package Microsoft.Net.Http" from your nuget command line.
using System;
using System.Net.Http;

var baseAddress = new Uri("https://app.promoter.io/api/");

using (var httpClient = new HttpClient{ BaseAddress = baseAddress })
{

  httpClient.DefaultRequestHeaders.TryAddWithoutValidation("authorization", "Token YOUR_API_KEY");
  
  
    using (var content = new StringContent("{  \"emails\": [    \"kate@mac.com\"  ]}", System.Text.Encoding.Default, "application/json"))
    {
      using (var response = await httpClient.PostAsync("undefined", content))
      {
        string responseData = await response.Content.ReadAsStringAsync();
      }
  }
}
<?php
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "https://app.promoter.io/api/contacts/unsubscribe/
");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, FALSE);

curl_setopt($ch, CURLOPT_POST, TRUE);

curl_setopt($ch, CURLOPT_POSTFIELDS, "{
  \"emails\": [
    \"kate@mac.com\"
  ]
}");

curl_setopt($ch, CURLOPT_HTTPHEADER, array(
  "Authorization: Token YOUR_API_KEY",
  "Content-Type: application/json"
));

$response = curl_exec($ch);
curl_close($ch);

var_dump($response);
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{"count":0,"next":null,"previous":null,"results":[]}

Body Params

emails
array of strings
required

Email of the contact you'd like to unsubscribe.

Headers

Authorization
string
required

This is where you'll provide your API key, after inserting the word 'Token' and a space

Content-Type
string
required

Must be specified as "application/json"

 

Within our platform, you can unsubscribe a contact and this will prevent the ability to survey them in the future. The unsubscribe action will also cancel all future pending surveys that were scheduled for that contact.

Suggest Edits

Get contacts

 
gethttps://app.promoter.io/api/contacts/
curl --include \
     --header "Authorization: Token YOUR_API_KEY" \
     --header "Content-Type: application/json" \
  'https://app.promoter.io/api/contacts/'
var request = new XMLHttpRequest();

request.open('GET', 'https://app.promoter.io/api/contacts/');

request.setRequestHeader('Authorization', 'Token YOUR_API_KEY');
request.setRequestHeader('Content-Type', 'application/json');

request.onreadystatechange = function () {
  if (this.readyState === 4) {
    console.log('Status:', this.status);
    console.log('Headers:', this.getAllResponseHeaders());
    console.log('Body:', this.responseText);
  }
};

request.send();
from urllib2 import Request, urlopen

headers = {
  'Authorization': 'Token YOUR_API_KEY',
  'Content-Type': 'application/json'
}
request = Request('https://app.promoter.io/api/contacts/', headers=headers)

response_body = urlopen(request).read()
print response_body
require 'rubygems' if RUBY_VERSION < '1.9'
require 'rest_client'

headers = {
  :authorization => 'Token YOUR_API_KEY',
  :content_type => 'application/json'
}

response = RestClient.get 'https://app.promoter.io/api/contacts/', headers
puts response
// Maven : Add these dependecies to your pom.xml (java6+)
// <dependency>
//     <groupId>org.glassfish.jersey.core</groupId>
//     <artifactId>jersey-client</artifactId>
//     <version>2.8</version>
// </dependency>
// <dependency>
//     <groupId>org.glassfish.jersey.media</groupId>
//     <artifactId>jersey-media-json-jackson</artifactId>
//     <version>2.8</version>
// </dependency>

import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.MediaType;

Client client = ClientBuilder.newClient();
Response response = client.target("https://app.promoter.io/api/contacts/")
  .request(MediaType.APPLICATION_JSON_TYPE)
  .header("Authorization", "Token YOUR_API_KEY")
  .get();

System.out.println("status: " + response.getStatus());
System.out.println("headers: " + response.getHeaders());
System.out.println("body:" + response.readEntity(String.class));
//Common testing requirement. If you are consuming an API in a sandbox/test region, uncomment this line of code ONLY for non production uses.
//System.Net.ServicePointManager.ServerCertificateValidationCallback = delegate { return true; };

//Be sure to run "Install-Package Microsoft.Net.Http" from your nuget command line.
using System;
using System.Net.Http;

var baseAddress = new Uri("https://app.promoter.io/api/");

using (var httpClient = new HttpClient{ BaseAddress = baseAddress })
{

  httpClient.DefaultRequestHeaders.TryAddWithoutValidation("authorization", "Token YOUR_API_KEY");
  
  
  using(var response = await httpClient.GetAsync("undefined"))
  {
 
        string responseData = await response.Content.ReadAsStringAsync();
  }
}
<?php
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "https://app.promoter.io/api/contacts/");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, FALSE);

curl_setopt($ch, CURLOPT_HTTPHEADER, array(
  "Authorization: Token YOUR_API_KEY",
  "Content-Type: application/json"
));

$response = curl_exec($ch);
curl_close($ch);

var_dump($response);
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
 {
    "id": 744011,                           
    "email": "kate@mac.com",                
    "first_name": "Kate",                   
    "last_name": "Bell",                    
    "created_date": "2014-12-12T10:00:00Z", 
    "unsubscribed": "false",                
    "attributes": {                         
        "Source": "Support Ticket",
        "Reference": "123456",
        "plan": "bronze"
    }
}

Query Params

email
string

Query by a contact's email to grab them specifically

contact_list__id
int32

Query by contact list id to grab all contacts within a list

Headers

Authorization
string
required

This is where you'll provide your API key, after inserting the word 'Token' and a space

Content-Type
string
required

Must be specified as "application/json"

 

This endpoint retrieves all contacts in your organization. You can also query by the contact's email to find a particular contact, or query by a contact list id to grab all contacts within a list.

When this call is made, it will return 100 results at a time and will require paginating through the results. To paginate, you would add a page parameter to the url. Ex: <api_call>/api/contacts/?page=3

Suggest Edits

Get a specific contact by id

 
gethttps://app.promoter.io/api/contacts/contact_id/
curl --include \
     --header "Authorization: Token YOUR_API_KEY" \
     --header "Content-Type: application/json" \
  'https://app.promoter.io/api/contacts/744011/'
var request = new XMLHttpRequest();

request.open('GET', 'https://app.promoter.io/api/contacts/744011/
');

request.setRequestHeader('Authorization', 'Token YOUR_API_KEY');
request.setRequestHeader('Content-Type', 'application/json');

request.onreadystatechange = function () {
  if (this.readyState === 4) {
    console.log('Status:', this.status);
    console.log('Headers:', this.getAllResponseHeaders());
    console.log('Body:', this.responseText);
  }
};

request.send();
from urllib2 import Request, urlopen

headers = {
  'Authorization': 'Token YOUR_API_KEY',
  'Content-Type': 'application/json'
}
request = Request('https://app.promoter.io/api/contacts/744011/
', headers=headers)

response_body = urlopen(request).read()
print response_body
require 'rubygems' if RUBY_VERSION < '1.9'
require 'rest_client'

headers = {
  :authorization => 'Token YOUR_API_KEY',
  :content_type => 'application/json'
}

response = RestClient.get 'https://app.promoter.io/api/contacts/744011/
', headers
puts response
// Maven : Add these dependecies to your pom.xml (java6+)
// <dependency>
//     <groupId>org.glassfish.jersey.core</groupId>
//     <artifactId>jersey-client</artifactId>
//     <version>2.8</version>
// </dependency>
// <dependency>
//     <groupId>org.glassfish.jersey.media</groupId>
//     <artifactId>jersey-media-json-jackson</artifactId>
//     <version>2.8</version>
// </dependency>

import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.MediaType;

Client client = ClientBuilder.newClient();
Response response = client.target("https://app.promoter.io/api/contacts/{contact_id}/
")
  .request(MediaType.APPLICATION_JSON_TYPE)
  .header("Authorization", "Token YOUR_API_KEY")
  .get();

System.out.println("status: " + response.getStatus());
System.out.println("headers: " + response.getHeaders());
System.out.println("body:" + response.readEntity(String.class));
//Common testing requirement. If you are consuming an API in a sandbox/test region, uncomment this line of code ONLY for non production uses.
//System.Net.ServicePointManager.ServerCertificateValidationCallback = delegate { return true; };

//Be sure to run "Install-Package Microsoft.Net.Http" from your nuget command line.
using System;
using System.Net.Http;

var baseAddress = new Uri("https://app.promoter.io/api/");

using (var httpClient = new HttpClient{ BaseAddress = baseAddress })
{

  httpClient.DefaultRequestHeaders.TryAddWithoutValidation("authorization", "Token YOUR_API_KEY");
  
  
  using(var response = await httpClient.GetAsync("undefined"))
  {
 
        string responseData = await response.Content.ReadAsStringAsync();
  }
}
<?php
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "https://app.promoter.io/api/contacts/{contact_id}/
");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, FALSE);

curl_setopt($ch, CURLOPT_HTTPHEADER, array(
  "Authorization: Token YOUR_API_KEY",
  "Content-Type: application/json"
));

$response = curl_exec($ch);
curl_close($ch);

var_dump($response);
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
        "id": 744011,                           
        "email": "kate@mac.com",                
        "first_name": "Kate",                   
        "last_name": "Bell",                    
        "created_date": "2014-12-12T10:00:00Z", 
        "unsubscribed": "false",                
        "attributes": {                         
            "Source": "Support Ticket",
            "Reference": "123456",
            "plan": "bronze"
        }
    }

Path Params

contact_id
int32
required

The contact's id you'd like to grab info for

Headers

Authorization
string
required

This is where you'll provide your API key, after inserting the word 'Token' and a space

Content-Type
string
required

Must be "application/json"

 

Retrieves a specific contact in your organization by providing the contact id.

Suggest Edits

Remove a contact

 
deletehttps://app.promoter.io/api/contacts/remove/
curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Authorization: Token YOUR_API_KEY" \
     --data-binary "{\"email\":\"kate@mac.com\"}" \
'https://app.promoter.io/api/contacts/remove/'
var request = new XMLHttpRequest();

request.open('POST', 'https://app.promoter.io/api/contacts/remove/
');

request.setRequestHeader('Content-Type', 'application/json');
request.setRequestHeader('Authorization', 'Token YOUR_API_KEY');

request.onreadystatechange = function () {
  if (this.readyState === 4) {
    console.log('Status:', this.status);
    console.log('Headers:', this.getAllResponseHeaders());
    console.log('Body:', this.responseText);
  }
};

var body = {
  'email': 'kate@mac.com'
};

request.send(JSON.stringify(body));
from urllib2 import Request, urlopen

values = """
  {
    "email": "kate@mac.com"
  }
"""

headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Token YOUR_API_KEY'
}
request = Request('https://app.promoter.io/api/contacts/remove/
', data=values, headers=headers)

response_body = urlopen(request).read()
print response_body
require 'rubygems' if RUBY_VERSION < '1.9'
require 'rest_client'

values = '{
  "email": "kate@mac.com"
}'

headers = {
  :content_type => 'application/json',
  :authorization => 'Token YOUR_API_KEY'
}

response = RestClient.post 'https://app.promoter.io/api/contacts/remove/
', values, headers
puts response
// Maven : Add these dependecies to your pom.xml (java6+)
// <dependency>
//     <groupId>org.glassfish.jersey.core</groupId>
//     <artifactId>jersey-client</artifactId>
//     <version>2.8</version>
// </dependency>
// <dependency>
//     <groupId>org.glassfish.jersey.media</groupId>
//     <artifactId>jersey-media-json-jackson</artifactId>
//     <version>2.8</version>
// </dependency>

import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.MediaType;

Client client = ClientBuilder.newClient();
Entity payload = Entity.json("{  'email': 'kate@mac.com'}");
Response response = client.target("https://app.promoter.io/api/contacts/remove/
")
  .request(MediaType.APPLICATION_JSON_TYPE)
  .header("Authorization", "Token YOUR_API_KEY")
  .post(payload);

System.out.println("status: " + response.getStatus());
System.out.println("headers: " + response.getHeaders());
System.out.println("body:" + response.readEntity(String.class));
//Common testing requirement. If you are consuming an API in a sandbox/test region, uncomment this line of code ONLY for non production uses.
//System.Net.ServicePointManager.ServerCertificateValidationCallback = delegate { return true; };

//Be sure to run "Install-Package Microsoft.Net.Http" from your nuget command line.
using System;
using System.Net.Http;

var baseAddress = new Uri("https://app.promoter.io/api/");

using (var httpClient = new HttpClient{ BaseAddress = baseAddress })
{

  
  httpClient.DefaultRequestHeaders.TryAddWithoutValidation("authorization", "Token YOUR_API_KEY");
  
    using (var content = new StringContent("{  \"email\": \"kate@mac.com\"}", System.Text.Encoding.Default, "application/json"))
    {
      using (var response = await httpClient.PostAsync("undefined", content))
      {
        string responseData = await response.Content.ReadAsStringAsync();
      }
  }
}
<?php
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "https://app.promoter.io/api/contacts/remove/
");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, FALSE);

curl_setopt($ch, CURLOPT_POST, TRUE);

curl_setopt($ch, CURLOPT_POSTFIELDS, "{
  \"email\": \"kate@mac.com\"
}");

curl_setopt($ch, CURLOPT_HTTPHEADER, array(
  "Content-Type: application/json",
  "Authorization: Token YOUR_API_KEY"
));

$response = curl_exec($ch);
curl_close($ch);

var_dump($response);
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "count": 0,
  "next": null,
  "previous": null,
  "results": []
}

Body Params

email
string
required

The email of the contact to remove from the organization

Headers

Authorization
string
required

This is where you'll provide your API key, after inserting the word 'Token' and a space

Content-Type
string
required

Must be "application/json"

 

This endpoint removes a contact for an organization. This is a delete action and all of the contact’s data and history will be removed from the organization.

Suggest Edits

Get all feedback

 
gethttps://app.promoter.io/api/feedback/
curl --include \
     --header "Authorization: Token YOUR_API_KEY" \
     --header "Content-Type: application/json" \
  'https://app.promoter.io/api/feedback/'
var request = new XMLHttpRequest();

request.open('GET', 'https://app.promoter.io/api/feedback/');

request.setRequestHeader('Authorization', 'Token YOUR_API_KEY');
request.setRequestHeader('Content-Type', 'application/json');

request.onreadystatechange = function () {
  if (this.readyState === 4) {
    console.log('Status:', this.status);
    console.log('Headers:', this.getAllResponseHeaders());
    console.log('Body:', this.responseText);
  }
};

request.send();
from urllib2 import Request, urlopen

headers = {
  'Authorization': 'Token YOUR_API_KEY',
  'Content-Type': 'application/json'
}
request = Request('https://app.promoter.io/api/feedback/', headers=headers)

response_body = urlopen(request).read()
print response_body
require 'rubygems' if RUBY_VERSION < '1.9'
require 'rest_client'

headers = {
  :authorization => 'Token YOUR_API_KEY',
  :content_type => 'application/json'
}

response = RestClient.get 'https://app.promoter.io/api/feedback/', headers
puts response
// Maven : Add these dependecies to your pom.xml (java6+)
// <dependency>
//     <groupId>org.glassfish.jersey.core</groupId>
//     <artifactId>jersey-client</artifactId>
//     <version>2.8</version>
// </dependency>
// <dependency>
//     <groupId>org.glassfish.jersey.media</groupId>
//     <artifactId>jersey-media-json-jackson</artifactId>
//     <version>2.8</version>
// </dependency>

import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.MediaType;

Client client = ClientBuilder.newClient();
Response response = client.target("https://app.promoter.io/api/feedback/
")
  .request(MediaType.APPLICATION_JSON_TYPE)
  .header("Authorization", "Token YOUR_API_KEY")
  .get();

System.out.println("status: " + response.getStatus());
System.out.println("headers: " + response.getHeaders());
System.out.println("body:" + response.readEntity(String.class));
//Common testing requirement. If you are consuming an API in a sandbox/test region, uncomment this line of code ONLY for non production uses.
//System.Net.ServicePointManager.ServerCertificateValidationCallback = delegate { return true; };

//Be sure to run "Install-Package Microsoft.Net.Http" from your nuget command line.
using System;
using System.Net.Http;

var baseAddress = new Uri("https://app.promoter.io/api/");

using (var httpClient = new HttpClient{ BaseAddress = baseAddress })
{

  httpClient.DefaultRequestHeaders.TryAddWithoutValidation("authorization", "Token YOUR_API_KEY");
  
  
  using(var response = await httpClient.GetAsync("undefined"))
  {
 
        string responseData = await response.Content.ReadAsStringAsync();
  }
}
<?php
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "https://app.promoter.io/api/feedback/
");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, FALSE);

curl_setopt($ch, CURLOPT_HTTPHEADER, array(
  "Authorization: Token YOUR_API_KEY",
  "Content-Type: application/json"
));

$response = curl_exec($ch);
curl_close($ch);

var_dump($response);
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "id": 1600,                                                                   
    "href": "https://app.promoter.io/api/feedback/1600/",                         
    "followup_href": "https://app.promoter.io/org/50/campaign/101/responses/all/response/1600/",
    "contact": {    
        "first_name": "Kate",                                                    
        "last_name": "Bell",                                                       
        "id": 60000,                                                               
        "email": "kate-bell@email.com",                                           
        "attributes": {                                                           
            "plan": "gold"
        }
    },
        "score": 8,                                                      
        "score_type": "passive",                           
        "comment": "Price is great! Service is ok.",      
        "posted_date": "2014-12-01T20:00:00Z",             
        "comment_updated_date":"2014-12-01T20:04:00Z",   
        "tags": {                                         
            "positive":[
                "price",
            ],
            "neutral":[
                "service",
            ],
            "negative":[
			      ]
        }
}

Query Params

survey__contact__email
string

Search for all feedback from a specific contact by using their email address

score
int32

Choose to get feedback with specific scores. 0 - 10

score_type
string

Filter feedback by specific score types. Ex: promoter, passive, detractor

survey__campaign
int32

The id of the campaign you'd like all feedback from

survey__campaign__status
string

Filter feedback by their campaign statuses, Ex: ACTIVE, COMPLETE

followup__type
string

Get feedback based on the actions already taken on them. Values: REPLIED, FORWARDED

posted_date_1
date

Use this parameter to get all feedback before a specific date. Ex: 2016-10-23

posted_date_0
date

Use this parameter to get all feedback after a specific date. Ex: 2016-10-21

Headers

Authorization
string
required

This is where you'll provide your API key, after inserting the word 'Token' and a space

Content-Type
string
required

Must be "application/json"

 

Since you may have lots of feedback in different campaigns, there’s the ability to filter feedback by campaign_id, show only un-completed feedback, filter by score type, along with a few more options as query parameters.

When this call is made, it will return 100 results at a time and will require paginating through the results. To paginate, you would add a page parameter to the url. Ex: <api_call>/api/feedback/?page=3

You can feedback for a specific time period by date queries in the URL. All dates are using UTC time. Due to this, you may see slightly different number of feedbacks than what's displayed on your dashboard since your dashboard respects your timezone settings. Date formats accepted are yyyy-mm-dd and mm/dd/yyyy.

Date Examples

All feedback before a specific date: /api/feedback/?posted_date_1=2016-10-23

All feedback after a specific date: /api/feedback/?posted_date_0=2016-10-31

Feedback for a specific time period: /api/feedback/?posted_date_0=2016-10-03&posted_date_1=2016-10-23

Suggest Edits

Get a feedback by id

 
gethttps://app.promoter.io/api/feedback/feedback_id/
curl --include \
     --header "Authorization: Token YOUR_API_KEY" \
     --header "Content-Type: application/json" \
  'https://app.promoter.io/api/feedback/1600/'
var request = new XMLHttpRequest();

request.open('GET', 'https://app.promoter.io/api/feedback/1600/
');

request.setRequestHeader('Authorization', 'Token YOUR_API_KEY');
request.setRequestHeader('Content-Type', 'application/json');

request.onreadystatechange = function () {
  if (this.readyState === 4) {
    console.log('Status:', this.status);
    console.log('Headers:', this.getAllResponseHeaders());
    console.log('Body:', this.responseText);
  }
};

request.send();
from urllib2 import Request, urlopen

headers = {
  'Authorization': 'Token YOUR_API_KEY',
  'Content-Type': 'application/json'
}
request = Request('https://app.promoter.io/api/feedback/1600/
', headers=headers)

response_body = urlopen(request).read()
print response_body
require 'rubygems' if RUBY_VERSION < '1.9'
require 'rest_client'

headers = {
  :authorization => 'Token YOUR_API_KEY',
  :content_type => 'application/json'
}

response = RestClient.get 'https://app.promoter.io/api/feedback/{feedback_id}/
', headers
puts response
// Maven : Add these dependecies to your pom.xml (java6+)
// <dependency>
//     <groupId>org.glassfish.jersey.core</groupId>
//     <artifactId>jersey-client</artifactId>
//     <version>2.8</version>
// </dependency>
// <dependency>
//     <groupId>org.glassfish.jersey.media</groupId>
//     <artifactId>jersey-media-json-jackson</artifactId>
//     <version>2.8</version>
// </dependency>

import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.MediaType;

Client client = ClientBuilder.newClient();
Response response = client.target("https://app.promoter.io/api/feedback/{feedback_id}/
")
  .request(MediaType.APPLICATION_JSON_TYPE)
  .header("Authorization", "Token YOUR_API_KEY")
  .get();

System.out.println("status: " + response.getStatus());
System.out.println("headers: " + response.getHeaders());
System.out.println("body:" + response.readEntity(String.class));
//Common testing requirement. If you are consuming an API in a sandbox/test region, uncomment this line of code ONLY for non production uses.
//System.Net.ServicePointManager.ServerCertificateValidationCallback = delegate { return true; };

//Be sure to run "Install-Package Microsoft.Net.Http" from your nuget command line.
using System;
using System.Net.Http;

var baseAddress = new Uri("https://app.promoter.io/api/");

using (var httpClient = new HttpClient{ BaseAddress = baseAddress })
{

  httpClient.DefaultRequestHeaders.TryAddWithoutValidation("authorization", "Token YOUR_API_KEY");
  
  
  using(var response = await httpClient.GetAsync("undefined"))
  {
 
        string responseData = await response.Content.ReadAsStringAsync();
  }
}
<?php
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "https://app.promoter.io/api/feedback/{feedback_id}/
");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, FALSE);

curl_setopt($ch, CURLOPT_HTTPHEADER, array(
  "Authorization: Token YOUR_API_KEY",
  "Content-Type: application/json"
));

$response = curl_exec($ch);
curl_close($ch);

var_dump($response);
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "id": 1600,                                                                   
    "href": "https://app.promoter.io/api/feedback/1600/",                         
    "followup_href": "https://app.promoter.io/org/50/campaign/101/responses/all/response/1600/",
    "contact": {    
        "first_name": "Kate",                                                    
        "last_name": "Bell",                                                       
        "id": 60000,                                                               
        "email": "kate-bell@email.com",                                           
        "attributes": {                                                           
            "plan": "gold"
        }
    },
        "score": 8,                                                      
        "score_type": "passive",                           
        "comment": "Price is great! Service is ok.",      
        "posted_date": "2014-12-01T20:00:00Z",             
        "comment_updated_date":"2014-12-01T20:04:00Z",   
        "tags": {                                         
            "positive":[
                "price",
            ],
            "neutral":[
                "service",
            ],
            "negative":[
			      ]
        }
}

Path Params

feedback_id
int32
required

The id of the feedback you'd like to retrieve

Headers

Authorization
string
required

This is where you'll provide your API key, after inserting the word 'Token' and a space

Content-Type
string
required

Must be "application/json"

 

Retrieves a specific feedback in your organization by providing the feedback id.

Suggest Edits

Get contact lists

 
gethttps://app.promoter.io/api/lists/
curl --include \
     --header "Authorization: Token YOUR_API_KEY" \
     --header "Content-Type: application/json" \
  'https://app.promoter.io/api/lists/'
var request = new XMLHttpRequest();

request.open('GET', 'https://app.promoter.io/api/lists/
');

request.setRequestHeader('Authorization', 'Token YOUR_API_KEY');
request.setRequestHeader('Content-Type', 'application/json');

request.onreadystatechange = function () {
  if (this.readyState === 4) {
    console.log('Status:', this.status);
    console.log('Headers:', this.getAllResponseHeaders());
    console.log('Body:', this.responseText);
  }
};

request.send();
from urllib2 import Request, urlopen

headers = {
  'Authorization': 'Token YOUR_API_KEY',
  'Content-Type': 'application/json'
}
request = Request('https://app.promoter.io/api/lists/
', headers=headers)

response_body = urlopen(request).read()
print response_body
require 'rubygems' if RUBY_VERSION < '1.9'
require 'rest_client'

headers = {
  :authorization => 'Token YOUR_API_KEY',
  :content_type => 'application/json'
}

response = RestClient.get 'https://app.promoter.io/api/lists/
', headers
puts response
// Maven : Add these dependecies to your pom.xml (java6+)
// <dependency>
//     <groupId>org.glassfish.jersey.core</groupId>
//     <artifactId>jersey-client</artifactId>
//     <version>2.8</version>
// </dependency>
// <dependency>
//     <groupId>org.glassfish.jersey.media</groupId>
//     <artifactId>jersey-media-json-jackson</artifactId>
//     <version>2.8</version>
// </dependency>

import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.MediaType;

Client client = ClientBuilder.newClient();
Response response = client.target("https://app.promoter.io/api/lists/
")
  .request(MediaType.APPLICATION_JSON_TYPE)
  .header("Authorization", "Token YOUR_API_KEY")
  .get();

System.out.println("status: " + response.getStatus());
System.out.println("headers: " + response.getHeaders());
System.out.println("body:" + response.readEntity(String.class));
//Common testing requirement. If you are consuming an API in a sandbox/test region, uncomment this line of code ONLY for non production uses.
//System.Net.ServicePointManager.ServerCertificateValidationCallback = delegate { return true; };

//Be sure to run "Install-Package Microsoft.Net.Http" from your nuget command line.
using System;
using System.Net.Http;

var baseAddress = new Uri("https://app.promoter.io/api/");

using (var httpClient = new HttpClient{ BaseAddress = baseAddress })
{

  httpClient.DefaultRequestHeaders.TryAddWithoutValidation("authorization", "Token YOUR_API_KEY");
  
  
  using(var response = await httpClient.GetAsync("undefined"))
  {
 
        string responseData = await response.Content.ReadAsStringAsync();
  }
}
<?php
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "https://app.promoter.io/api/lists/
");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, FALSE);

curl_setopt($ch, CURLOPT_HTTPHEADER, array(
  "Authorization: Token YOUR_API_KEY",
  "Content-Type: application/json"
));

$response = curl_exec($ch);
curl_close($ch);

var_dump($response);
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "id":1,                     
  "name":"My Contact List"    
}

Headers

Authorization
string
required

This is where you'll provide your API key, after inserting the word 'Token' and a space

Content-Type
string
required

Must be "application/json"

 

Retrieves all lists within your organization.

Suggest Edits

Get metrics

 
gethttps://app.promoter.io/api/metrics/
curl --include \
     --header "Authorization: Token YOUR_API_KEY" \
     --header "Content-Type: application/json" \
  'https://app.promoter.io/api/metrics/'
var request = new XMLHttpRequest();

request.open('GET', 'https://app.promoter.io/api/metrics/
');

request.setRequestHeader('Authorization', 'Token YOUR_API_KEY');
request.setRequestHeader('Content-Type', 'application/json');

request.onreadystatechange = function () {
  if (this.readyState === 4) {
    console.log('Status:', this.status);
    console.log('Headers:', this.getAllResponseHeaders());
    console.log('Body:', this.responseText);
  }
};

request.send();
from urllib2 import Request, urlopen

headers = {
  'Authorization': 'Token YOUR_API_KEY',
  'Content-Type': 'application/json'
}
request = Request('https://app.promoter.io/api/metrics/
', headers=headers)

response_body = urlopen(request).read()
print response_body
require 'rubygems' if RUBY_VERSION < '1.9'
require 'rest_client'

headers = {
  :authorization => 'Token YOUR_API_KEY',
  :content_type => 'application/json'
}

response = RestClient.get 'https://app.promoter.io/api/metrics/
', headers
puts response
// Maven : Add these dependecies to your pom.xml (java6+)
// <dependency>
//     <groupId>org.glassfish.jersey.core</groupId>
//     <artifactId>jersey-client</artifactId>
//     <version>2.8</version>
// </dependency>
// <dependency>
//     <groupId>org.glassfish.jersey.media</groupId>
//     <artifactId>jersey-media-json-jackson</artifactId>
//     <version>2.8</version>
// </dependency>

import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.MediaType;

Client client = ClientBuilder.newClient();
Response response = client.target("https://app.promoter.io/api/metrics/
")
  .request(MediaType.APPLICATION_JSON_TYPE)
  .header("Authorization", "Token YOUR_API_KEY")
  .get();

System.out.println("status: " + response.getStatus());
System.out.println("headers: " + response.getHeaders());
System.out.println("body:" + response.readEntity(String.class));
//Common testing requirement. If you are consuming an API in a sandbox/test region, uncomment this line of code ONLY for non production uses.
//System.Net.ServicePointManager.ServerCertificateValidationCallback = delegate { return true; };

//Be sure to run "Install-Package Microsoft.Net.Http" from your nuget command line.
using System;
using System.Net.Http;

var baseAddress = new Uri("https://app.promoter.io/api/");

using (var httpClient = new HttpClient{ BaseAddress = baseAddress })
{

  httpClient.DefaultRequestHeaders.TryAddWithoutValidation("authorization", "Token YOUR_API_KEY");
  
  
  using(var response = await httpClient.GetAsync("undefined"))
  {
 
        string responseData = await response.Content.ReadAsStringAsync();
  }
}
<?php
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "https://app.promoter.io/api/metrics/
");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, FALSE);

curl_setopt($ch, CURLOPT_HTTPHEADER, array(
  "Authorization: Token YOUR_API_KEY",
  "Content-Type: application/json"
));

$response = curl_exec($ch);
curl_close($ch);

var_dump($response);
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{ 
    "href": "https://app.promoter.io/api/campaigns/123/", 
    "nps": 25,                                             
    "campaign_name": "My Campaign Name",                     
    "promoter_percentage": 25,                              
    "passive_percentage": 25,                               
    "detractor_percentage": 50,                             
    "score_analysis": "AT RISK",                             
    "feedback_count": 4,                                    
    "surveys_delivered_count": 33106,                       
    "surveys_scheduled_count": 2415,                        
    "followup_count": 2,                                    
    "followups_outstanding": 2,                            
    "followup_rate_percentage": "50",                      
    "feedback_rate_percentage": "30",                       
    "average_revenue_per_customer": 210,                        
    "short_term_revenue_at_risk": 210,                       
    "long_term_revenue_at_risk": 63,                        
    "potential_new_revenue": 63                             
}

Query Params

posted_date_1
string

Use this parameter to get all metrics before a specific date. Ex: 2016-10-23

posted_date_0
string

Use this parameter to get all metrics after a specific date. Ex: 2016-10-21

Headers

Authorization
string
required

This is where you'll provide your API key, after inserting the word 'Token' and a space

Content-Type
string
required

Must be "application/json"

 

This endpoint will retrieve all current campaign metrics within your organization.

When retrieving metrics, the default is to show metrics for the past 30 days.

You can grab metrics for a specific time period by date queries in the URL. All dates are using UTC time. Due to this, you may see slightly different metrics than what's displayed on your dashboard since your dashboard respects your timezone settings. Date formats accepted are yyyy-mm-dd and mm/dd/yyyy.

Date Examples

All metrics before a specific date: /api/metrics/?posted_date_1=2016-10-23

All metrics after a specific date: /api/metrics/?posted_date_0=2016-10-31

Metrics for a specific time period: /api/metrics/?posted_date_0=2016-10-03&posted_date_1=2016-10-23

Score analysis values:

(-100) - (-1): "AT RISK"

0 - 49: "GOOD"

50 - 74: "EXCELLENT"

75 - 100: "WORLD CLASS"

Suggest Edits

Webhooks

 
posthttps://app.promoter.io/api/hooks
curl --include \
     --request POST \
     --header "Authorization: Token YOUR_API_KEY" \
     --header "Content-Type: application/json" \
     --data-binary "{
    \"event\":\"feedback.added_or_changed\",
    \"target\": \"https://requestb.in/140amoa1\"
}" \
'https://app.promoter.io/api/hooks'
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
No response examples available

Body Params

event
string
required
target
string
required

The URL for the webhook to post to.

Headers

Content-Type
string
required

Must be 'application/json'

Authorization
string
required

This is where you'll provide your API key, after inserting the word 'Token' and a space

 

Events we currently support

  • feedback.added_or_changed - Anytime feedback is created or changed, e.g., a user submitted a score and/or provided a comment.
  • feedback.removed - Anytime feedback is removed, e.g., a specific feedback was deleted by a user or admin.
  • metric.score_changed - Anytime the NPS score changes for a given campaign.
  • contact.unsubscribed - Anytime a contact unsubscribes from receiving surveys

To add a new webhook using the Promoter web application:

  1. Navigate to your Account Settings in Promoter.
  2. Click Webhooks from the menu.
  3. Click + Create Webhook at the top of the page.
  4. Choose the event you want to listen for (for example, feedback is added).
  5. Add your webhook URL under "Target URL".
  6. Choose the campaign you would like this webhook tied to.
  7. Click Create.

You can use RequestBin to test what our HTTP client is sending or to inspect and debug webhook requests. Data will be returned in JSON format:

feedback.added_or_changed

{
  "hook": {
    "id": 2416,
    "event": "feedback.added_or_changed",
    "target": "http://requestb.in/1ftjak41"
  },
  "data": {
    "comment": "I love my new tablet!",
    "posted_date": "2017-05-04T16:42:33Z",
    "score": 10,
    "campaign": 583,
    "score_type": "passive",
    "contact": {
      "attributes": {
        "plan": "bronze"
      },
      "first_name": "Kate",
      "last_name": "Bell",
      "id": 12345,
      "email": "kate@mac.com"
    },
    "comment_updated_date": "2017-05-04T16:42:40Z",
    "id": 1520285
  }
}

feedback.removed

{
  "hook": {
    "id": 104,
    "event": "feedback.removed",
    "target": "http://requestb.in/1ftjak41"
  },
  "data": {
    "comment": "I love my new tablet!",
    "posted_date": "2017-05-04T16:42:33Z",
    "score": 10,
    "campaign": 583,
    "score_type": "passive",
    "contact": {
      "attributes": {
        "plan": "bronze"
      },
      "first_name": "Kate",
      "last_name": "Bell",
      "id": 12345,
      "email": "kate@mac.com"
    },
    "comment_updated_date": "2017-05-04T16:42:40Z",
    "id": 1520285
  }
}

metric.score_changed

{
  "hook": {
    "target": "http://requestb.in/1ftjak41",
    "id": 251,
    "event": "metric.score_changed"
  },
  "data": {
    "potential_new_revenue": 73,
    "average_revenue_per_customer": 123,
    "formatted_long_term_revenue_at_risk": 73,
    "campaign_name": "Pear Computers",
    "followups_outstanding": 5,
    "promoter_percentage": 34,
    "formatted_potential_new_revenue": 73,
    "followup_rate_percentage": 17,
    "followup_count": 1,
    "formatted_surveys_scheduled_count": "0",
    "surveys_scheduled_count": 0,
    "formatted_surveys_delivered_count": "0",
    "score_analysis": GOOD,
    "detractor_percentage": 33,
    "formatted_average_revenue_per_customer": 0,
    "long_term_revenue_at_risk": 0,
    "passive_percentage": 0,
    "surveys_delivered_count": 10,
    "nps": 1,
    "feedback_count": 6,
    "formatted_short_term_revenue_at_risk": 123,
    "feedback_rate_percentage": 60,
    "short_term_revenue_at_risk": 123
  }
}

contact.unsubscribed

{
  "hook": {
    "target": "http://requestb.in/1ftjak41",
    "id": 249,
    "event": "contact.unsubscribed"
  },
  "data": {
    "attributes": {    
    	"plan": "bronze"
    },
    "first_name": "Kate",
    "last_name": "Bell",
    "id": 12345,
    "email": "kate@mac.com"
  }
}