Pricing About
Sign up

Existing customer? Sign in

eNPS API Documentation (V1)

The eNPS API enables you to create, deactivate, list, and search your employees. This API is meant to be everything you need to synchronize your other HR tools with eNPS.

Calling the API

V1 of the API is hosted at https://www.enps.co/api/v1. All calls use this URL as the base.

Authentication

eNPS API uses token-based authentication. If you're logged into your eNPS account, you'll see your API key below.

Simply include key as a query parameter or a header parameter in your queries, like this: https://www.enps.co/api/v1/surveys?key=<<log in to see your key>>.

If you don't include an API key or use the wrong one, eNPS will respond with a 401 authorization error.

Status and Error Codes

Here are the most common HTTP status codes you may receive from our API and what they mean.

  • 200: Request and response were successful.
  • 401: The API key you used was not found.
  • 404: The recipient you're looking for wasn't found or is not accessible from your account.
  • 405: The method you attempted was not allowed.
  • 500: There was a server error.

Surveys

List surveys

This is the index call for your surveys. You will need a survey ID in order to perform CRUD operations on recipients.

Example

GET https://www.enps.co/api/v1/surveys?key=<<log in to see your key>>

Result

{
  "status": "SUCCESS",
  "message": "Loaded all surveys.",
  "data": [
    {
      "id": 4,
      "name": "Marketing",
      "frequency": "month",
      "is_active": false,
      "created_at": "2019-09-30T16:58:42.414-12:00",
      "updated_at": "2019-09-30T16:58:44.611-12:00",
      "last_send_at": "2019-04-22T16:58:44.610-12:00",
      "next_send_at": "2019-10-07T16:58:44.610-12:00",
      "prompt": "How cool am I?",
      "low_nps_prompt": "Not really",
      "high_nps_prompt": "Absolutely",
      "reminder_delay": 2,
      "comment_prompt": "Anything else?",
      "phone_number": "+14155551234",
      "reminders_count": 0,
      "status": "active",
      "subject": "Your eNPS survey",
      "survey_type": "enps",
      "team_id": 2
    },
    {
      "id": 3,
      "name": "Sales",
      "frequency": "week",
      "is_active": false,
      "created_at": "2019-09-30T16:58:42.412-12:00",
      "updated_at": "2019-09-30T16:58:43.472-12:00",
      "last_send_at": "2019-04-22T16:58:43.471-12:00",
      "next_send_at": "2019-10-07T16:58:43.471-12:00",
      "prompt": "How cool am I?",
      "low_nps_prompt": "Not really",
      "high_nps_prompt": "Absolutely",
      "reminder_delay": 2,
      "comment_prompt": "Anything else?",
      "phone_number": "+14155551234",
      "reminders_count": 0,
      "status": "active",
      "subject": "Your enPS survey",
      "survey_type": "enps",
      "team_id": 2
    }
  ],
  "last_page": true,
  "total_count": 2
}

Recipients

List recipients

This is the index call for the recipients on a given survey. You will need to provide a survey ID in the path.

Example

GET https://www.enps.co/api/v1/surveys/4/recipients?key=<<log in to see your key>>

Result

{
  "status": "SUCCESS",
  "message": "Loaded all recipients.",
  "data": [
    {
      "id": 5,
      "first_name": "onie",
      "last_name": "dion",
      "department": "engineering",
      "manager_email": "roman@okon.co.uk",
      "hire_date": "2017-11-01",
      "title": "regional secretary",
      "email": "dan@mayert.ca",
      "phone_number": "+15105557777",
      "location": "san francisco",
      "reminded_at": "",
      "created_at": "2019-09-30T16:58:42.459-12:00",
      "updated_at": "2019-09-30T16:58:42.459-12:00",
      "role": "active",
      "team_id": 2
    },
    {
      "id": 19,
      "first_name": "janelle",
      "last_name": "geneva",
      "department": "engineering",
      "manager_email": "avelina@kuvalis.us",
      "hire_date": "2017-12-01",
      "title": "general operations secretary",
      "email": "paul@gaylord.co.uk",
      "phone_number": "+15105557777",
      "location": "phoenix",
      "reminded_at": "",
      "created_at": "2019-09-30T16:58:42.509-12:00",
      "updated_at": "2019-09-30T16:58:42.509-12:00",
      "role": "active",
      "team_id": 2
    },
    {
      "id": 20,
      "first_name": "judy",
      "last_name": "tracey",
      "department": "operations",
      "manager_email": "dalene@wildermantreutel.biz",
      "hire_date": "2015-04-01",
      "title": "corporate secretary",
      "email": "yi@metz.co.uk",
      "phone_number": "+15105557777",
      "location": "san francisco",
      "reminded_at": "",
      "created_at": "2019-09-30T16:58:42.512-12:00",
      "updated_at": "2019-09-30T16:58:42.512-12:00",
      "role": "active",
      "team_id": 2
    },
    {
      "id": 39,
      "first_name": "telma",
      "last_name": "alaine",
      "department": "operations",
      "manager_email": "ahmed@cartwright.ca",
      "hire_date": "2018-10-01",
      "title": "corporate secretary",
      "email": "tawny@gleichner.ca",
      "phone_number": "+15105557777",
      "location": "phoenix",
      "reminded_at": "",
      "created_at": "2019-09-30T16:58:42.587-12:00",
      "updated_at": "2019-09-30T16:58:42.587-12:00",
      "role": "active",
      "team_id": 2
    }
  ],
  "last_page": true,
  "total_count": 4
}

Search recipients

Search the recipients on a given survey. You will need to provide a survey ID in the path and a query parameter for your search.

Example

GET https://www.enps.co/api/v1/surveys/4/recipients/search?key=<<log in to see your key>>&query=engineering

Result

{
  "status": "SUCCESS",
  "message": "Loaded all recipients.",
  "data": [
    {
      "id": 5,
      "first_name": "onie",
      "last_name": "dion",
      "department": "engineering",
      "manager_email": "roman@okon.co.uk",
      "hire_date": "2017-11-01",
      "title": "regional secretary",
      "email": "dan@mayert.ca",
      "phone_number": "+15105557777",
      "location": "san francisco",
      "reminded_at": "",
      "created_at": "2019-09-30T16:58:42.459-12:00",
      "updated_at": "2019-09-30T16:58:42.459-12:00",
      "role": "active",
      "team_id": 2
    },
    {
      "id": 19,
      "first_name": "janelle",
      "last_name": "geneva",
      "department": "engineering",
      "manager_email": "avelina@kuvalis.us",
      "hire_date": "2017-12-01",
      "title": "general operations secretary",
      "email": "paul@gaylord.co.uk",
      "phone_number": "+15105557777",
      "location": "phoenix",
      "reminded_at": "",
      "created_at": "2019-09-30T16:58:42.509-12:00",
      "updated_at": "2019-09-30T16:58:42.509-12:00",
      "role": "active",
      "team_id": 2
    },
    {
      "id": 22,
      "first_name": "eloy",
      "last_name": "mariann",
      "department": "engineering",
      "manager_email": "charlotte_batz@stanton.info",
      "hire_date": "2018-05-01",
      "title": "executive finance consultant",
      "email": "joye.hyatt@reingerhirthe.com",
      "phone_number": "+15105557777",
      "location": "phoenix",
      "reminded_at": "",
      "created_at": "2019-09-30T16:58:42.519-12:00",
      "updated_at": "2019-09-30T16:58:42.519-12:00",
      "role": "active",
      "team_id": 2
    },
    {
      "id": 24,
      "first_name": "gonzalo",
      "last_name": "portia",
      "department": "engineering",
      "manager_email": "almeda@kuhicullrich.co.uk",
      "hire_date": "2016-02-01",
      "title": "associate manager",
      "email": "renna_schimmel@wiza.ca",
      "phone_number": "+15105557777",
      "location": "phoenix",
      "reminded_at": "",
      "created_at": "2019-09-30T16:58:42.526-12:00",
      "updated_at": "2019-09-30T16:58:42.526-12:00",
      "role": "active",
      "team_id": 2
    },
    {
      "id": 31,
      "first_name": "tara",
      "last_name": "eleni",
      "department": "engineering",
      "manager_email": "dessie_bashirian@bogisich.us",
      "hire_date": "2018-10-01",
      "title": "associate operations manager",
      "email": "tamela.howell@jenkinskihn.name",
      "phone_number": "+15105557777",
      "location": "san francisco",
      "reminded_at": "",
      "created_at": "2019-09-30T16:58:42.557-12:00",
      "updated_at": "2019-09-30T16:58:42.557-12:00",
      "role": "active",
      "team_id": 2
    },
    {
      "id": 32,
      "first_name": "evita",
      "last_name": "ali",
      "department": "engineering",
      "manager_email": "kristal@rempel.name",
      "hire_date": "2016-10-01",
      "title": "general operations president",
      "email": "debora@larson.us",
      "phone_number": "+15105557777",
      "location": "san francisco",
      "reminded_at": "",
      "created_at": "2019-09-30T16:58:42.560-12:00",
      "updated_at": "2019-09-30T16:58:42.560-12:00",
      "role": "active",
      "team_id": 2
    },
    {
      "id": 40,
      "first_name": "agatha",
      "last_name": "elicia",
      "department": "engineering",
      "manager_email": "sharolyn@jastfritsch.us",
      "hire_date": "2018-02-01",
      "title": "information director",
      "email": "sandra@ryan.info",
      "phone_number": "+15105557777",
      "location": "manila",
      "reminded_at": "",
      "created_at": "2019-09-30T16:58:42.590-12:00",
      "updated_at": "2019-09-30T16:58:42.590-12:00",
      "role": "active",
      "team_id": 2
    },
    {
      "id": 50,
      "first_name": "willena",
      "last_name": "vashti",
      "department": "engineering",
      "manager_email": "logan@barrows.com",
      "hire_date": "2017-03-01",
      "title": "associate information president",
      "email": "winnie@okuneva.biz",
      "phone_number": "+15105557777",
      "location": "utah",
      "reminded_at": "",
      "created_at": "2019-09-30T16:58:42.630-12:00",
      "updated_at": "2019-09-30T16:58:42.630-12:00",
      "role": "active",
      "team_id": 2
    }
  ],
  "last_page": true,
  "total_count": 8
}

Create a recipient

Add a recipient to a given survey. You will need to provide a survey ID in the path.

Parameters

key Your API key required
email Properly formed email address of the new recipient required
phone_number Properly formed phone number of the new recipient required without email
first_name First name of the new recipient optional
last_name Last name of the new recipient optional
department Name of the department (for eNPS score filtering) optional
title Job title of the recipient (for eNPS score filtering) optional
location Office location (for eNPS score filtering) optional
hire_date Date when recipient was hired (for eNPS score filtering) optional (YYYY-MM-DD format)
manager_email Email address of the recipient's direct manager (for eNPS score filtering) optional

Example

POST https://www.enps.co/api/v1/surveys/4/recipients

Result

{
  "status": "SUCCESS",
  "message": "Created recipient.",
  "data": {
    "id": 51,
    "first_name": "ryan",
    "last_name": "buckley",
    "department": "executive",
    "manager_email": "",
    "hire_date": "",
    "title": "",
    "email": "ryan@toofr.llc",
    "phone_number": "",
    "location": "diablo valley",
    "reminded_at": "2020-01-30 22:28:55 -0800",
    "created_at": "2020-01-30T18:28:54.954-12:00",
    "updated_at": "2020-01-30T18:28:55.017-12:00",
    "role": "active",
    "team_id": 2
  }
}

Update a recipient

Edit a recipient to a given survey. You will need to provide a survey ID and recipient ID in the path.

Parameters

key Your API key required
email Properly formed email address of the new recipient required
phone_number Properly formed phone number of the new recipient required without email
first_name First name of the new recipient optional
last_name Last name of the new recipient optional
department Name of the department (for eNPS score filtering) optional
title Job title of the recipient (for eNPS score filtering) optional
location Office location (for eNPS score filtering) optional
hire_date Date when recipient was hired (for eNPS score filtering) optional (YYYY-MM-DD format)
manager_email Email address of the recipient's direct manager (for eNPS score filtering) optional

Example

PUT https://www.enps.co/api/v1/surveys/4/recipients/51

Result

{
  "status": "SUCCESS",
  "message": "Edited recipient.",
  "data": {
    "id": 51,
    "first_name": "ryan",
    "last_name": "bluckley",
    "department": "executive",
    "manager_email": "",
    "hire_date": "",
    "title": "",
    "email": "ryan@enps.co",
    "phone_number": "",
    "location": "diablo valley",
    "reminded_at": "2020-01-30 22:28:55 -0800",
    "created_at": "2020-01-30T18:28:54.954-12:00",
    "updated_at": "2020-01-30T18:33:23.560-12:00",
    "role": "active",
    "team_id": 2
  }
}

Destroy a recipient

Remove a recipient from a given survey. You will need to provide a survey ID and recipient ID in the path.

Example

DELETE https://www.enps.co/api/v1/surveys/4/recipients/51

Result

{
  "status": "SUCCESS",
  "message": "Removed the recipient from your survey."
}

© 2021 Toofr LLC. All rights reserved.

Net Promoter®, NPS®, NPS Prism®, and the NPS-related emoticons are registered trademarks of Bain & Company, Inc., Satmetrix Systems, Inc., and Fred Reichheld. Net Promoter Score℠ and Net Promoter System℠ are service marks of Bain & Company, Inc., Satmetrix Systems, Inc., and Fred Reichheld.