apiary.apib

FORMAT: 1A
HOST: https://app.promoter.io

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

# Group Authentication
Promoter uses API keys to allow access to the API. You can register for a Promoter API key with a [Promoter Account](http://app.promoter.io/account/signup). 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```

With curl, you can pass the correct header with each request ```curl "https://app.promoter.io/api"```
 
# Group Feedback
## Get all feedback [GET /feedback/{?score,score_type,survey__campaign,survey__campaign__status,followup__type,hide_completed}]

This endpoint retrieves all feedback existing in your organization.

Since you may have quite a bit of responses in many different campaigns, there’s the ability to filter responses by campaign, show only un-completed responses, filter by score type, along with a few more options as query parameters.
  
  
+ Parameters
    + score: 7, 8, 9 (Number, optional) - You can choose to get feedback with specific scores  
    + score_type: promoter, passive, detractor (String, optional) - Filter feedback by specific score types
    + survey__campaign: (Number, optional) - The id of the campaign you'd like all feedback from
    + survey__campaign__status: ACTIVE, COMPLETE (String, optional) - Filter feedback by their campaign statuses     
    + followup__type:  (String, optional) - Get feedback based the actions already 
    taken on them with **MARKED_COMPLETE**, **REPLIED**, and **FORWARDED** 
    + hide_completed: true, false (Boolean, optional) - Add this parameter if you'd like to only view feedback 
            that has not been replied to or marked complete

+ Request
    + Headers

            Authorization:Token YOUR_API_KEY


+ Response 200


    + Body

            
            {
                "count": 1,
                "next": null,
                "previous": null,
                "results": [
                    {
                        "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"
                    }
                ]
            }
            


## Get a specific feedback [GET /feedback/{feedback_id}/]

This endpoint retrieves a specific feedback in your organization. This can be done by providing the **feedback id**.

+ Parameters
    
    + feedback_id: (Number) -  The id of the specific feedback to retrieve.

+ Request
    + Headers

            Authorization:Token YOUR_API_KEY


+ Response 200


    + Body

            
            {
                "count": 1,
                "next": null,
                "previous": null,
                "results": [
                    {
                        "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"
                    }
                ]
            }
            
        
        
        
# Group Contacts
## Get all contacts [GET /contacts/{id}{?email}]

This endpoint retrieves all contacts that exist in your organization. To get a specific contact, you can provide the **contact id** or query by their **email**.

+ Parameters
    + id: (Number, optional) - The `id` of the contact 
    + email: (String, optional) - The email(s) of the contact you would like to search for

+ Request
    + Headers

            Authorization:Token YOUR_API_KEY


+ Response 200
    + Body

            
            {
                    "count": 1,
                    "next": null,
                    "previous": null,
                    "results": [
                        {
                            "id":12345,
                            "email":"kate@mac.com",
                            "first_name":"Kate",
                            "last_name":"Bell",
                            "created_date":"2014-12-12T10:00:00Z",
                            "attributes":{
                                "plan":"bronze"
                            }
                        },
                    ]
                }
                
            
## Add a Contact + Send Survey [POST /contacts/]   

#Add a contact only
This endpoint will add a contact to a list in your organization.

You can add as many attributes as you’d like along with your contact. These can be useful when filtering responses on the campaign dashboard. **The only attribute 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.

You can add a contact to your list without sending them a survey by passing the data attribute `send = false`. (See 1st request)


#Survey a contact + add

This part of the API can be very powerful and achieve two actions with one command if desired: Send the contact a survey and add the contact to a list. The command used for adding a contact is the same for surveying a contact, but specifying a few different attributes. (See 2nd request)

When sending a contact a survey, the **data attributes required are the campaign id** from which the survey is to be sent from, **and passing `send = true`**. If this contact has not already been added to the list associated with the campaign, they will automatically be added to this list. 

If you're looking to send surveys to all contacts, please reference the [Send Surveys for Campaign](http://docs.promoter.apiary.io/#reference/campaigns/send-surveys-for-a-campaign/send-surveys-for-a-campaign) section.
* **Note**: The campaign must have a contact list associated to it in order for the contact to be added correctly. Otherwise, the contact will be associated to a default generated contact list for your given organization.
* Also note, that depending on your **throttle setting**, your contact may not be surveyed if they have already received a survey within your throttle limit. An email will be sent notifying you of any contacts meeting the throttle limit or have unsubscribed. 


+ Attributes (object)
    + email: (string, required) - Email of the contact
    + first_name: (string, optional) - First name of the contact
    + last_name: (string, optional) - Last name of the contact
    + contact_list: (number, optional) - **Required if adding** The contact list id of which you'd like to add the contact to. If an id is not provided, the contact will be added to a default generated list.
    + attributes: (,optional) - A dictionary of key value pairs of custom attributes that will be associated with the contact
    + send: (boolean,optional) - A boolean value set to true in order to express intent to survey this contact for a given campaign.
    + campaign: (number, optional) - **Required if sending** The campaign id you would like to associate the contact to. 
            

+ Request 
    + Headers

            Authorization:Token YOUR_API_TOKEN
            Content-Type:application/json

    + Body
    
            {"email":"kate@mac.com","first_name":"Kate","last_name":"Bell","attributes":{"plan":"bronze"},"contact_list":[4865]}

+ Response 200


    + Body

            {
                    "id":12345,
                    "email":"kate@mac.com",
                    "first_name":"Kate",
                    "last_name":"Bell",
                    "created_date":"2014-12-12T10:00:00Z",
                    "attributes":{
                        "plan":"bronze"
                    }
                }


+ Request 
    + Headers 
        
            Content-Type: application/json
            Authorization: Token YOUR_API_KEY
            
    
    + Body
    
            {"email":"kate@mac.com", "first_name":"Kate", "last_name":"Bell", "attributes":{"plan":"bronze"}, "campaign":99, "send": true}

+ Response 200


    + Body

            {
                    "id":12345,
                    "email":"kate@mac.com",
                    "first_name":"Kate",
                    "last_name":"Bell",
                    "created_date":"2014-12-12T10:00:00Z",
                    "attributes":{
                        "plan":"bronze"
                    }
                }

## Remove a contact [POST /contacts/remove/]

This endpoint removes a contact for an organization.

* **Note**: This is a delete action and all of the contact’s data will be removed from the organization.

+ Parameter
    + email: (String, required) - The email of the contact to remove from the organization.
    
+ Request 
    + Headers 
        
            Content-Type: application/json
            Authorization: Token YOUR_API_KEY
            
    + Body
    
            {"email":"kate@mac.com"}

+ Response 200


    + Body

            {
                    "id":12345,
                    "email":"kate@mac.com",
                    "first_name":"Kate",
                    "last_name":"Bell",
                    "created_date":"2014-12-12T10:00:00Z",
                    "attributes":{
                        "plan":"bronze"
                    }
                }

# Group Campaigns
## Get all campaigns [GET /campaigns/]
This endpoint retrieves all campaigns and their details including: campaign name, drip duration, current eligible contact count, last date contacts were surveyed, and the original launch date.

+ Request 
    
    + Headers
    
            Authorization: Token YOUR_API_KEY

+ Response 200 

        {
            "count":1,
            "next":null,
            "previous":null,
            "results":[
                {
                    "id":1,
                    "name":"My Campaign's Name",
                    "all_count": 1,
                    "drip_duraction": 7,
                    "eligible_count": 5,
                    "last_sureveyed_date": "2014-10-10T12:00:00Z",
                    "launch_date": null
                }
            ]
        }

## Send surveys for a campaign [POST /campaigns/{id}/send_surveys/]  

This will send surveys for a campaign.

If the **all_contacts** attribute is set to `True`, you can to send to all contacts in your list. Setting to `False` will send only to those who have been newly added since your last launch.

If you're looking to send a survey to a single contact, please reference the [Add a Contact + Send Survey](http://docs.promoter.apiary.io/#reference/contacts/add-a-contact-send-survey/add-a-contact-+-send-survey) section.
* Default behavior for **all_contacts** is `false`
* **Note**: Depending on your **throttle setting**, some contacts may not be surveyed if they have already received a survey within your throttle limit **or have unsubscribed**. An email will be sent notifying you of any contacts meeting the throttle limit or have unsubscribed. 

+ Parameter
    + id: (Number, required) - The id of the campaign you'd like to send surveys from

+ Attributes
    + all_contacts: (boolean, optional) - Can be set to true or false. If set to true, the call will send surveys to all contacts in your specified contact list. If set to false, the call will send surveys to contacts who have been added or updated since you last sent surveys.     
        
+ Request 
    
    + Headers
    
            Authorization: Token YOUR_API_KEY

    + Body
        
            {"all_contacts":false}

+ Response 200 

        ["surveys sent"]
        
# Group Contact Lists
## Get all contact lists [GET /lists/]
Retrives all lists within your organization.

+ Request 
    + Headers
    
            Authorization: Token YOUR_API_KEY

+ Response 200

        {
            "count":1,
            "next":null,
            "previous":null,
            "results":[
                {
                    "id":1,
                    "name":"My Contact List"
                }
            ]
        }


## Get all contacts in a list [GET /lists/{id}/contacts]
This endpoint retrieves all contacts for a contact list.

+ Parameters
    + id: (Number, required) - The id of the list to view contacts

+ Request 
    
    + Headers
    
            Authorization: Token YOUR_API_KEY

+ Response 200 
        
        {
            "count":1,
            "next":null,
            "previous":null,
            "results":[
                {
                    "id":100000
                }
            ]
        }

## Remove a contact from a single list [DELETE /lists/{list_id}/contacts/{contact_id}/]

This removes a contact from a single contact list. The parameters required for this action is the **list id** and **contact id**.

+ Parameter
    + list_id: (Number, required) - The id of the contact list that the contact will be removed from
    + contact_id: (Number, required) - The id of the contact you would like removed from the list
 
+ Request 
    
    + Headers
    
            
            Authorization: Token YOUR_API_KEY

+ Response 204 


## Remove a contact from a single list by email [POST /lists/{list_id}/remove]
An optional way to remove a contact from a single list by using the contact's email.

+ Parameters
    + list_id: (Number, required) - The id if the list the contact will be removed from



+ Attributes
     + email: (string, required) - Email of the contact you'd like to remove from the list
     
+ Request 
    
    + Headers
            
            Content-Type: application/json
            Authorization: Token YOUR_API_KEY

    + Body
            
            '{"email":"kate@mac.com"}'
            
+ Response 200

        {
            "id":1,
            "name":"My Contact List"
        }

## Remove a contact from all lists [POST /lists/remove/]

This endpoint removes a contact from all contact lists. The contact’s data will still exist in the organization. The only parameter needed is the **contact’s email**.

+ Attributes
    + email: (string, required) - The email of the contact you'd like to remove from all lists

+ Request 
    
    + Headers
            
            Content-Type: application/json
            Authorization: Token YOUR_API_KEY

    + Body
    
            {"email":"kate@mac.com"}

+ Response 200 
    
        {
            "count":1,
            "next":null,
            "previous":null,
            "results":[
                {
                    "id":1,
                    "name":"My Contact List"
                }
            ]
        }
    


# Group Metrics
## Get metrics [GET /metrics/]
This endpoint will retrieve all current metrics within your organization. You will also be able to view an organization NPS score that takes into account all of your existing campaigns.

+ Request 
    
    + Headers
            
            Authorization: Token YOUR_API_KEY

+ Response 200 

        {
            "count": 1,
            "next": null,
            "previous": null,
            "results": [
                {
                    "campaign": "My Campaign",
                    "nps": "50.0",
                    "organization_nps": "35.0"
                }
            ]
        }

# Group Error Codes

* `400` - Bad Request – Something is wrong with your request
* `401` - Unauthorized – Your API key is incorrect or invalid
* `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! Slown down!
* `500` - Internal Server Error – We had a problem with our server. Try again later.
* `503` - Service Unavailable – We’re temporarially offline for maintanance. Please try again later.