Expand All Sections Back

Overview

The RapidEngage REST API allows you to query data about your account, Engagement Layers, questions, results, and more. It also allows you to create and manage your Engagement Layers. You can leverage our entire engagement infrastructure without the need to scale, support, or manage it.

Since the API is based on REST principles, it's easy to write and test applications against it using any programming language to interact with the API. We've also created a PHP SDK. If you would like to build an SDK for a particular platform please let us know!

Base URL:

We support GET , POST , and DELETE requests to the following base:

https://rapidengage.com/api

API Key:

You must have an API Key to make requests to our API. For now, you must request your FREE API Key from us through our request form. We'll review your request and what you're building and get back to you ASAP. Once you have your API Key, you pass it into the request using X-API-KEY.

You can pass it into the HEADERS:

curl https://rapidengage.com/api/surveys/survey/1 -H "X-API-KEY: YOUR_API_KEY"

Or with a GET request into the query parameters:

curl https://rapidengage.com/api/surveys/survey/1?X-API-KEY=YOUR_API_KEY

Or with a POST request into the post data:

curl https://rapidengage.com/api/users/forgot -d "X-API-KEY=YOUR_API_KEY&email=SOME_EMAIL"

Authentication Token:

For API requests that require authentication, you will need to pass in a valid authentication token. The authentication token X-AUTH-TOKEN works just like the API Key above.

curl https://rapidengage.com/api/users/me?X-API-KEY=YOUR_KEY_HERE&X-AUTH-TOKEN=VALID_TOKEN

Supported Formats:

We support both JSON and XML. By default JSON will be returned, though you can request which format to be return at the end of the URI or by the "format" URL parameter.

In JSON:

curl https://rapidengage.com/api/surveys/survey/1.json -H "X-API-KEY: YOUR_API_KEY"

or

curl https://rapidengage.com/api/surveys/survey/1?format=json -H "X-API-KEY: YOUR_API_KEY"

In XML:

curl https://rapidengage.com/api/surveys/survey/1.xml -H "X-API-KEY: YOUR_API_KEY"

or

curl https://rapidengage.com/api/surveys/survey/1?format=xml -H "X-API-KEY: YOUR_API_KEY"

Timezone:

All dates are stored in UTC.

Updating Objects:

When updating an object, the POST call requires all of the fields, otherwise the defaults will be used.

Embeds

Once an Engagement Layer is built via the API or RapidEngage website, you can embed it on your website in an iFrame, within your iOS app in a UIWebView, in a WebView on Android, or in the web containers for the other platforms you're developing in.

Websites and iFrames

For a web app, you could simply use our Embed Code, much like a YouTube embed code. Just copy and paste the code onto you website where you want it. Though, primarily what we offer are Engagement Layers. They will appear on the right side of your website in the footer a few seconds after page load. From the Engagement Dashboard, the enabled/active layer will appear in the Engagement Layer on your website.

We've gone ahead and written JavaScript code for you to copy and paste on your website which will load our Engagement Layers in a non-blocking asynchronous way. Though if you want to have full control of the way you load the layers, see the direct links to them below.

Apps

We're currently working on iOS and Android client libraries, though for now, you just need to add the URL to the survey into your app directly.

The following URLs will render an Engagement Layer that is 300x250 pixels. Now, you could just make the API call to get the entire payload of the layer and render it yourself in any design you want. Though, if you want piggyback on all of the hard work we've done to get the layers working and looking just right in all the browsers, you can use our URLs.

Here is the URL to the Engagement Layer for you to embed/display:

https://rapidengage.com/survey/{survey_uid}/embed

Here is the URL to the active layer for the Engagement Layers:

https://rapidengage.com/tab/{user_id}

Link answers to customers (Identity Tracking):

If you want to track your registered users with the Engagement Layers, just push an "identity" object into the RapidEngage Javascript array directly after the main RapidEngage Website Engagement Code.

Example Javascript:

<script type="text/javascript">
    RapidEngage.push(['identity', {
        email: 'danielzev@gmail.com',
        name: 'Daniel Marashlian',
        provider: 'Facebook',
        uri: 'http://danielzev.com',
        gender: 'male',
        birthday: '1982-09-04'
    }]);
</script>
Expand

Authentication

POST /auth/token

This API call is used to get the Authentication Token for authenticated API calls.

Currently, the Authentication Token does NOT expire. Once the RapidEngage OAuth implmentation is finished, we will be putting a 60-day expiration on the auth tokens to force people to upgrade their apps to use OAuth to gain access to the RapidEngage API.

Parameters:

Parameter Required Type Description
email yes string(100) The user's email
password yes string(100) The user's password
X-API-KEY yes string(36) Developer API Key

cURL Example:

curl 'https://rapidengage.com/api/auth/token' -H 'X-API-KEY: YOUR_API_KEY' --data 'email=CLIENT_EMAIL&password=CLIENT_PASSWORD'

JSON Response:

{
    id: "34593",
    token: "0150FB1C-DD05-18F6-D091-5E292CD7D220",
    user_id: "1873",
    created_at: "2013-08-17 10:38:06",
    updated_at: "2013-08-17 10:38:06"
}

Errors:

HTTP CODE Description
400 Bad Request - The required fields were not passed in
402 Payment Required - Locked Account
403 Forbidden - Invalid API Key
403 Forbidden - Canceled Account
403 Forbidden - Bad user credentials
500 Internal Server Error - Something is majorly wrong
Expand

Answers

GET /answers/survey/{survey_id}

This API call is used to get the listing of the respondent's answers to a survey.

*Special Case: The survey_id is part of the URI. Though if your application only has the survey_uid at this point, then just leave the survey_id empty in the URI and pass in the survey_uid as a query parameter. Here's an Example:

curl https://rapidengage.com/api/surveys/survey?survey_uid=8581546d -H "X-API-KEY: YOUR_API_KEY"

Parameters:

Parameter Required Type Default Description
survey_id *special case int - The ID of the survey
survey_uid *special case string(8) - The UID of the survey
uvid no string(100) null The unique visitor ID. If passed in, the answers will be filtered down to just this visitor/respondent.
pvid no string(100) null The unique pageview ID. If passed in, the answers will be filtered down to just this unique answer set.
X-API-KEY yes string(36) - Developer API Key
X-AUTH-TOKEN yes string(36) - User Authentication Token

cURL Example:

curl 'https://rapidengage.com/api/answers/survey/1' -H 'X-API-KEY: YOUR_API_KEY' -H 'X-AUTH-TOKEN: CLIENT_TOKEN'

JSON Response:

{
    id: "1",
    title: "Product Research for, Nike",
    description: null,
    created_at: "2013-05-28 05:13:36",
    updated_at: "2013-08-13 21:10:47",
    user_id: "1",
    status: "live",
    show_results: null,
    publish: "2013-07-18",
    uid: "8581546d",
    complete: "1",
    completion_count: "171",
    start_count: "361",
    metadata: null,
    refresh: "0",
    callback: null,
    answers: [
        {
            id: "7373",
            value: "3",
            survey_id: "1",
            question_id: "6",
            created_at: "2013-07-04 01:38:47",
            updated_at: "2013-07-04 01:38:47",
            uvid: "004f7a19-ab31-f91b-444d-1247fe81da5f",
            pvid: "3BF84B98-D9D7-D4F8-1EAC-774ADA48AB5B",
            ip_address: "70.211.64.133",
            position: "0",
            name: null,
            email: null,
            provider: null,
            option: null
        },
        {
            id: "7373",
            value: "3",
            survey_id: "1",
            question_id: "6",
            created_at: "2013-07-04 01:38:47",
            updated_at: "2013-07-04 01:38:47",
            uvid: "004f7a19-ab31-f91b-444d-1247fe81da5f",
            pvid: "19C61030-EA3F-C902-D82A-DC3752767C7E",
            ip_address: "70.211.64.133",
            position: "0",
            name: null,
            email: null,
            provider: null,
            option: null
        }
    ]
}

Errors:

HTTP CODE Description
400 Bad Request - The required fields were not passed in
401 Unauthorized - Auth Token Required
403 Forbidden - Invalid Auth Token
403 Forbidden - Invalid API Key
403 Forbidden - The passed in Authentication Token does not have access to the survey
404 Not Found - Survey does not exist

GET /answers/question/{question_id}

This API call is used to get the listing of the respondent's answers to a particular question.

Parameters:

Parameter Required Type Description
question_id yes int The ID of the question
X-API-KEY yes string(36) Developer API Key
X-AUTH-TOKEN yes string(36) User Authentication Token

cURL Example:

curl 'https://rapidengage.com/api/answers/question/6' -H 'X-API-KEY: YOUR_API_KEY' -H 'X-AUTH-TOKEN: CLIENT_TOKEN'

JSON Response:

{
    id: "6",
    text: "How does this brand, make you feel?",
    type: "emotion",
    survey_id: "1",
    created_at: "2013-05-28 05:17:32",
    updated_at: "2013-07-25 20:33:45",
    position: "0",
    answers: [
        {
            id: "10451",
            value: "5",
            survey_id: "1",
            question_id: "6",
            created_at: "2013-08-13 21:10:43",
            updated_at: "2013-08-13 21:10:43",
            uvid: "FBC69843-974B-E169-A808-652FD49176B8",
            pvid: "3BF84B98-D9D7-D4F8-1EAC-774ADA48AB5B",
            ip_address: "127.0.0.1"
        },
        {
            id: "10444",
            value: "1",
            survey_id: "1",
            question_id: "6",
            created_at: "2013-08-13 21:09:32",
            updated_at: "2013-08-13 21:09:32",
            uvid: "FBC69843-974B-E169-A808-652FD49176B8",
            pvid: "19C61030-EA3F-C902-D82A-DC3752767C7E",
            ip_address: "127.0.0.1"
        }
    ]
}

Errors:

HTTP CODE Description
400 Bad Request - The required fields were not passed in
401 Unauthorized - Auth Token Required
403 Forbidden - Invalid Auth Token
403 Forbidden - Invalid API Key
403 Forbidden - The passed in Authentication Token does not have access to the question
404 Not Found - Question does not exist

POST /answers/create/{question_id}

This API call is used to record a respondent's answer to a question.

*Special Case: Due to the different question types, we can only accept certain answer values for specific question types. This is so we don't mess up the results when we aggregate the answers.

Valid Answer Values

Question Type Accepted Answers
compare a | b
dropdown Option ID of the selected Answer Option
emotion 1 | 2 | 3 | 4 | 5
mc Option ID of the selected Answer Option
scale 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10
star 1 | 2 | 3 | 4 | 5
text The text that the respondent submitted
vote down | up

Results and Tracking:

If you want to be able to uniquely track a person as they answer a multiple questions on a survey and/or multiple surveys, assign them a unique visitor ID (a.k.a. uvid) and pass that in. When you pull the results, you'll see that data aggregated along with the identity record.

For completion rate tracking, make sure to pass in the proper "milestone" parameter. This is put on the developer to track vs. internally within the RapidEngage API. For example, the developer could randomize the survey questions everytime. If this were the case, the system wouldn't know which answer was the first or last.

The unique pageview ID (a.k.a. pvid) is used to track each time the survey is viewed; even by the same person. This is used to automatically aggregate the different answer permutations. The answer path will be stored and used if you've been sending in a pvid for every answer and once the "finish" or "both" milestone parameter is sent in, the answer path will be saved and counted. Once we've gathered enough data, you'll see the "permutations" value populated in the results object.

Parameters:

Parameter Required Type Default Description
question_id yes int - The ID of the question
answer *special case string(250) - The answer option value
milestone no string(6) null Mark the survey as being started, finished, or both for a survey with only one question. Accepted Values: start | finish | both
uvid no string(100) null The unique visitor ID. Used for tracking.
pvid no string(100) null The pageview ID. Used for tracking the unique pageview for each time a survey is viewed.
X-API-KEY yes string(36) - Developer API Key

cURL Example:

curl 'https://rapidengage.com/api/answers/create/6' -H 'X-API-KEY: YOUR_API_KEY' --data 'answer=2&milestone=start&uvid=456789&pvid=3BF84B98-D9D7-D4F8-1EAC-774ADA48AB5B'

JSON Response:

{
    id: "10460",
    value: "2",
    survey_id: "1",
    question_id: "6",
    created_at: "2013-08-19 10:05:59",
    updated_at: "2013-08-19 10:05:59",
    uvid: "456789",
    pvid: "3BF84B98-D9D7-D4F8-1EAC-774ADA48AB5B",
    ip_address: "127.0.0.1"
}

Errors:

HTTP CODE Description
400 Bad Request - The required fields were not passed in
403 Forbidden - Invalid API Key
404 Not Found - Question does not exist
500 Internal Server Error - Something is majorly wrong

DELETE /answers/survey/{survey_id}

This API call is used to clear a survey's responses, and reset the start and completed counts.

*Special Case: The survey_id is part of the URI. Though if your application only has the survey_uid at this point, then just leave the survey_id empty in the URI and pass in the survey_uid as a query parameter. Here's an Example:

curl https://rapidengage.com/api/surveys/survey?survey_uid=8581546d -H "X-API-KEY: YOUR_API_KEY"

Parameters:

Parameter Required Type Description
survey_id *special case int The ID of the survey
survey_uid *special case string(8) The UID of the survey
X-API-KEY yes string(36) Developer API Key
X-AUTH-TOKEN yes string(36) User Authentication Token

Errors:

HTTP CODE Description
400 Bad Request - The required fields were not passed in
401 Unauthorized - Auth Token Required
403 Forbidden - Invalid Auth Token
403 Forbidden - Invalid API Key
403 Forbidden - The passed in Authentication Token does not have access to the survey
404 Not Found - Survey does not exist
500 Internal Server Error - Something is majorly wrong
Expand

Identities (User Tracking)

POST /identities/create/{survey_id}

This API call is used to track the identity of a survey respondent.

Since answering a survey doesn't require authentication, this is a way to track who is viewing/taking your surveys. Once the survey is loaded, you would call this API with all of the data you have available to you.

The most important part is the "unique visitor ID" or uvid. This should be the same value you use/track when an answer is recorded.

*Special Case: The survey_id is part of the URI. Though if your application only has the survey_uid at this point, then just leave the survey_id empty in the URI and pass in the survey_uid as a query parameter. Here's an Example:

curl https://rapidengage.com/api/surveys/survey?survey_uid=8581546d -H "X-API-KEY: YOUR_API_KEY"

Parameters:

Parameter Required Type Default Description
survey_id *special case int - The ID of the survey
survey_uid *special case string(8) - The UID of the survey
uvid yes string(100) - The unique visitor ID. Used to match the UVID on the answer.
name no string(100) null The name of the visitor/viewer
email no string(100) null The email of the visitor/viewer
provider no string(100) null The social provider that the visitor/viewer authed in with
uri no string(100) null A unique profile URL on the social network for the visitor/viewer
gender no string(100) null The gender of the visitor/viewer
birthday no string(100) null The birthday of the visitor/viewer
X-API-KEY yes string(36) - Developer API Key

cURL Example:

curl 'https://rapidengage.com/api/identities/create/1' -H 'X-API-KEY: YOUR_API_KEY' --data 'uvid=456789&name=Daniel+Marashlian&email=danielzev%40gmail.com&provider=facebook&gender=male'

JSON Response:

{
    id: "6",
    name: "Daniel Marashlian",
    email: "danielzev@gmail.com",
    provider: "facebook",
    uri: null,
    survey_id: "1",
    uvid: "456789",
    created_at: "2013-08-19 12:28:17",
    updated_at: "2013-08-19 12:28:17",
    gender: "male",
    birthday: null
}

Errors:

HTTP CODE Description
400 Bad Request - The required fields were not passed in
403 Forbidden - Invalid API Key
404 Not Found - Survey does not exist
500 Internal Server Error - Something is majorly wrong
Expand

Images

GET /images/image/{image_id}

This API call is used to get the meta-data of an image.

Parameters:

Parameter Required Type Description
image_id yes int The ID of the image
X-API-KEY yes string(36) Developer API Key

Errors:

HTTP CODE Description
400 Bad Request - The required fields were not passed in
403 Forbidden - Invalid API Key
404 Not Found - Image does not exist

POST /images/create/{question_id}

This API call is used to create/upload a new image for a question.

Parameters:

Parameter Required Type Default Description
question_id yes int - The ID of the question
file yes file - The file to upload
position no int 0 The 0-based position of the image
X-API-KEY yes string(36) - Developer API Key
X-AUTH-TOKEN yes string(36) - User Authentication Token

Errors:

HTTP CODE Description
400 Bad Request - The required fields were not passed in
400 Bad Request - Missing File
401 Unauthorized - Auth Token Required
403 Forbidden - Invalid Auth Token
403 Forbidden - Invalid API Key
403 Forbidden - The passed in Authentication Token does not have access to the question
404 Not Found - Question does not exist
500 Internal Server Error - Something is majorly wrong

DELETE /images/image/{image_id}

This API call is used to delete an image.

Parameters:

Parameter Required Type Description
image_id yes int The ID of the image
X-API-KEY yes string(36) Developer API Key
X-AUTH-TOKEN yes string(36) User Authentication Token

Errors:

HTTP CODE Description
400 Bad Request - The required fields were not passed in
401 Unauthorized - Auth Token Required
403 Forbidden - Invalid Auth Token
403 Forbidden - Invalid API Key
403 Forbidden - The passed in Authentication Token does not have access to the image
404 Not Found - Image does not exist
500 Internal Server Error - Something is majorly wrong
Expand

Layers

POST /layers/rules

This API call is used to set the display options for the Engagement Layers.

Parameters:

Parameter Required Type Default Description
delay yes int - Time in seconds to delay the load of the Engagement Layer
rate yes int - Number of hours to wait before showing the Engagement Layer to the unique visitor
platform no string(7) both Display the Engagement Layer on the specified platform. Accepted Values: both | desktop | mobile
X-API-KEY yes string(36) - Developer API Key
X-AUTH-TOKEN yes string(36) - User Authentication Token

Errors:

HTTP CODE Description
400 Bad Request - The required fields were not passed in
401 Unauthorized - Auth Token Required
403 Forbidden - Invalid Auth Token
403 Forbidden - Invalid API Key
500 Internal Server Error - Something is majorly wrong
Expand

oEmbed

GET /oembed

oEmbed is an open standard for turning a URL into an embeddable piece of content for your site. To find out more about oEmbed read the spec. The RapidEngage oEmbed endpoint will return HTML snippets that you can include on your site. Right now it works for the survey Engagement Layer type.

NOTE: The oEmbed API endpoint is the only API call that DOES NOT require an API KEY.

Parameters:

Parameter Required Type Description
url yes string(100) The ID of the answer option

Errors:

HTTP CODE Description
404 Not Found - Engagement Layer does not exist
Expand

Answer Options

GET /options/option/{option_id}

This API call is used to get the meta-data of an answer option.

Parameters:

Parameter Required Type Description
option_id yes int The ID of the answer option
X-API-KEY yes string(36) Developer API Key

Errors:

HTTP CODE Description
400 Bad Request - The required fields were not passed in
403 Forbidden - Invalid API Key
404 Not Found - Answer Option does not exist

POST /options/create/{question_id}

This API call is used to create a new answer option for a question.

Parameters:

Parameter Required Type Default Description
question_id yes int - The ID of the question
value no string(100) null The string/text for the answer option
position no int 0 The 0-based position of the answer options
X-API-KEY yes string(36) - Developer API Key
X-AUTH-TOKEN yes string(36) - User Authentication Token

Errors:

HTTP CODE Description
400 Bad Request - The required fields were not passed in
401 Unauthorized - Auth Token Required
403 Forbidden - Invalid Auth Token
403 Forbidden - Invalid API Key
403 Forbidden - The passed in Authentication Token does not have access to the question
404 Not Found - Question does not exist
500 Internal Server Error - Something is majorly wrong

POST /options/option/{option_id}

This API call is used to update the meta-data of an answer option.

Parameters:

Parameter Required Type Default Description
option_id yes int - The ID of the answer option
value no string(100) null The string/text for the answer option
position no int 0 The 0-based position of the answer options
X-API-KEY yes string(36) - Developer API Key
X-AUTH-TOKEN yes string(36) - User Authentication Token

Errors:

HTTP CODE Description
400 Bad Request - The required fields were not passed in
401 Unauthorized - Auth Token Required
403 Forbidden - Invalid Auth Token
403 Forbidden - Invalid API Key
403 Forbidden - The passed in Authentication Token does not have access to the answer option
404 Not Found - Answer Option does not exist
500 Internal Server Error - Something is majorly wrong

DELETE /options/option/{option_id}

This API call is used to delete an answer option.

Parameters:

Parameter Required Type Description
option_id yes int The ID of the answer option
X-API-KEY yes string(36) Developer API Key
X-AUTH-TOKEN yes string(36) User Authentication Token

Errors:

HTTP CODE Description
400 Bad Request - The required fields were not passed in
401 Unauthorized - Auth Token Required
403 Forbidden - Invalid Auth Token
403 Forbidden - Invalid API Key
403 Forbidden - The passed in Authentication Token does not have access to the answer option
404 Not Found - Answer Option does not exist
500 Internal Server Error - Something is majorly wrong
Expand

Questions

GET /questions/question/{question_id}

This API call is used to get the meta-data of a question.

Parameters:

Parameter Required Type Description
question_id yes int The ID of the question
X-API-KEY yes string(36) Developer API Key

Errors:

HTTP CODE Description
400 Bad Request - The required fields were not passed in
403 Forbidden - Invalid API Key
404 Not Found - Question does not exist

POST /questions/create/{survey_id}

This API call is used to create a new question on a survey.

*Special Case: The survey_id is part of the URI. Though if your application only has the survey_uid at this point, then just leave the survey_id empty in the URI and pass in the survey_uid as a query parameter. Here's an Example:

curl https://rapidengage.com/api/surveys/survey?survey_uid=8581546d -H "X-API-KEY: YOUR_API_KEY"

Valid Question Types

Type Description
compare Comparison
dropdown Dropdown Menu
emotion Emoticon
mc Multiple Choice
scale Ratings Scale
star Star Rating
text Comment Box
vote Vote

Parameters:

Parameter Required Type Default Description
survey_id *special case int - The ID of the survey
survey_uid *special case string(8) - The UID of the survey
type yes string(100) - The question type
text no string(100) null The string/text for the question
position no int 0 The 0-based position of the survey questions
X-API-KEY yes string(36) - Developer API Key
X-AUTH-TOKEN yes string(36) - User Authentication Token

Errors:

HTTP CODE Description
400 Bad Request - The required fields were not passed in
401 Unauthorized - Auth Token Required
403 Forbidden - Invalid Auth Token
403 Forbidden - Invalid API Key
403 Forbidden - The passed in Authentication Token does not have access to the survey
500 Internal Server Error - Something is majorly wrong

POST /questions/question/{question_id}

This API call is used to update the meta-data of a question.

Parameters:

Parameter Required Type Default Description
question_id yes int - The ID of the question
text no string(100) null The string/text for the question
position no int 0 The 0-based position of the survey questions
X-API-KEY yes string(36) - Developer API Key
X-AUTH-TOKEN yes string(36) - User Authentication Token

Errors:

HTTP CODE Description
400 Bad Request - The required fields were not passed in
401 Unauthorized - Auth Token Required
403 Forbidden - Invalid Auth Token
403 Forbidden - Invalid API Key
403 Forbidden - The passed in Authentication Token does not have access to the question
404 Not Found - Question does not exist
500 Internal Server Error - Something is majorly wrong

DELETE /questions/question/{question_id}

This API call is used to delete a question.

Parameters:

Parameter Required Type Description
question_id yes int The ID of the question
X-API-KEY yes string(36) Developer API Key
X-AUTH-TOKEN yes string(36) User Authentication Token

Errors:

HTTP CODE Description
400 Bad Request - The required fields were not passed in
401 Unauthorized - Auth Token Required
403 Forbidden - Invalid Auth Token
403 Forbidden - Invalid API Key
403 Forbidden - The passed in Authentication Token does not have access to the question
404 Not Found - Question does not exist
500 Internal Server Error - Something is majorly wrong
Expand

Results (Aggregated Answers)

GET /results/survey/{survey_id}

This API call is used to get the results and statistics of a survey and all of its questions.

*Special Case: The survey_id is part of the URI. Though if your application only has the survey_uid at this point, then just leave the survey_id empty in the URI and pass in the survey_uid as a query parameter. Here's an Example:

curl https://rapidengage.com/api/surveys/survey?survey_uid=8581546d -H "X-API-KEY: YOUR_API_KEY"

Parameters:

Parameter Required Type Description
survey_id *special case int The ID of the survey
survey_uid *special case string(8) The UID of the survey
X-API-KEY yes string(36) Developer API Key
X-AUTH-TOKEN yes string(36) User Authentication Token

Errors:

HTTP CODE Description
400 Bad Request - The required fields were not passed in
401 Unauthorized - Auth Token Required
403 Forbidden - Invalid Auth Token
403 Forbidden - Invalid API Key
403 Forbidden - The passed in Authentication Token does not have access to the survey
404 Not Found - Survey does not exist

GET /results/question/{question_id}

This API call is used to get the results of a particular question.

Parameters:

Parameter Required Type Description
question_id yes int The ID of the question
X-API-KEY yes string(36) Developer API Key
X-AUTH-TOKEN yes string(36) User Authentication Token

Errors:

HTTP CODE Description
400 Bad Request - The required fields were not passed in
401 Unauthorized - Auth Token Required
403 Forbidden - Invalid Auth Token
403 Forbidden - Invalid API Key
403 Forbidden - The passed in Authentication Token does not have access to the question
404 Not Found - Question does not exist

GET /results/permutations/{survey_id}

This API call is used to get the min/max result sets (a.k.a. permutations) of a survey.

Parameters:

Parameter Required Type Description
survey_id *special case int The ID of the survey
survey_uid *special case string(8) The UID of the survey
X-API-KEY yes string(36) Developer API Key
X-AUTH-TOKEN yes string(36) User Authentication Token

Errors:

HTTP CODE Description
400 Bad Request - The required fields were not passed in
401 Unauthorized - Auth Token Required
403 Forbidden - Invalid Auth Token
403 Forbidden - Invalid API Key
403 Forbidden - The passed in Authentication Token does not have access to the survey
404 Not Found - Survey does not exist
Expand

Surveys

GET /surveys/survey/{survey_id}

This API call is used to get the meta-data of a survey.

*Special Case: The survey_id is part of the URI. Though if your application only has the survey_uid at this point, then just leave the survey_id empty in the URI and pass in the survey_uid as a query parameter. Here's an Example:

curl https://rapidengage.com/api/surveys/survey?survey_uid=8581546d -H "X-API-KEY: YOUR_API_KEY"

Parameters:

Parameter Required Type Description
survey_id *special case int The ID of the survey
survey_uid *special case string(8) The UID of the survey
X-API-KEY yes string(36) Developer API Key

Errors:

HTTP CODE Description
400 Bad Request - The required fields were not passed in
403 Forbidden - Invalid API Key
404 Not Found - Survey does not exist

GET /surveys/embed/{survey_id}

This API call is used to get the entire survey and all of its questions, images, and answer options. This is the main API call to display a survey as well as track its impression for tracking.

*Special Case: The survey_id is part of the URI. Though if your application only has the survey_uid at this point, then just leave the survey_id empty in the URI and pass in the survey_uid as a query parameter. Here's an Example:

curl https://rapidengage.com/api/surveys/survey?survey_uid=8581546d -H "X-API-KEY: YOUR_API_KEY"

Parameters:

Parameter Required Type Description
survey_id *special case int The ID of the survey
survey_uid *special case string(8) The UID of the survey
X-API-KEY yes string(36) Developer API Key

Errors:

HTTP CODE Description
400 Bad Request - The required fields were not passed in
403 Forbidden - Invalid API Key
404 Not Found - Survey does not exist

GET /surveys/user/{user_id}

This API call is used to get a listing of the surveys owned by a user.

*Special Case: The user_id is part of the URI. Though if your application only has the username at this point, then just leave the user_id empty in the URI and pass in the username as a query parameter. Here's an Example:

curl https://rapidengage.com/api/surveys/user?username=rapidengage -H "X-API-KEY: YOUR_API_KEY"

Parameters:

Parameter Required Type Description
user_id *special case int The ID of the user
username *special case string(100) The username of the user
X-API-KEY yes string(36) Developer API Key

Errors:

HTTP CODE Description
400 Bad Request - The required fields were not passed in
403 Forbidden - Invalid API Key
404 Not Found - User does not exist or their privacy settings are enabled

GET /surveys/mine

This API call is used to get a listing of the surveys with question and response counts for the current user.

Parameters:

Parameter Required Type Description
X-API-KEY yes string(36) Developer API Key
X-AUTH-TOKEN yes string(36) User Authentication Token

Errors:

HTTP CODE Description
401 Unauthorized - Auth Token Required
403 Forbidden - Invalid Auth Token
403 Forbidden - Invalid API Key
404 Not Found - Current user has no surveys

POST /surveys/create

This API call is used to create a new survey.

Parameters:

Parameter Required Type Default Description
name yes string(100) - The name/title of the survey
description no string(300) null A longer description of the survey
refresh no string(5) false A flag (true/false) to have the survey reload after a customer completes it. This takes precedence to the repeat flag
repeat no string(5) false A flag (true/false) to allow the survey respondents to take the survey multiple times.
skip_crop no string(5) false A flag (true/false) to tell the front-end website to skip the copping tool and just upload the original image.
metadata no string(1000) null Put whatever you need here for your app
css no string(10000) null Add your custom css here
callback no string(100) null A URL to send the survey to instead of the Thank You page. The Survey ID and UVID will be appended as query parameters.
X-API-KEY yes string(36) - Developer API Key
X-AUTH-TOKEN yes string(36) - User Authentication Token

Errors:

HTTP CODE Description
400 Bad Request - The required fields were not passed in
401 Unauthorized - Auth Token Required
403 Forbidden - Invalid Auth Token
403 Forbidden - Invalid API Key
500 Internal Server Error - Something is majorly wrong

POST /surveys/survey/{survey_id}

This API call is used to update the meta-data of a survey.

*Special Case: The survey_id is part of the URI. Though if your application only has the survey_uid at this point, then just leave the survey_id empty in the URI and pass in the survey_uid as a query parameter. Here's an Example:

curl https://rapidengage.com/api/surveys/survey?survey_uid=8581546d -H "X-API-KEY: YOUR_API_KEY"

Parameters:

Parameter Required Type Default Description
survey_id *special case int - The ID of the survey
survey_uid *special case string(8) - The UID of the survey
name yes string(100) - The name/title of the survey
description no string(300) null A longer description of the survey
refresh no string(5) false A flag (true/false) to have the survey reload after a customer completes it. This takes precedence to the repeat flag
repeat no string(5) false A flag (true/false) to allow the survey respondents to take the survey multiple times.
skip_crop no string(5) false A flag (true/false) to tell the front-end website to skip the copping tool and just upload the original image.
metadata no string(1000) null Put whatever you need here for your app
css no string(10000) null Add your custom css here
callback no string(100) null A URL to send the survey to instead of the Thank You page. The Survey ID and UVID will be appended as query parameters.
X-API-KEY yes string(36) - Developer API Key
X-AUTH-TOKEN yes string(36) - User Authentication Token

Errors:

HTTP CODE Description
400 Bad Request - The required fields were not passed in
401 Unauthorized - Auth Token Required
403 Forbidden - Invalid Auth Token
403 Forbidden - Invalid API Key
403 Forbidden - The passed in Authentication Token does not have access to the survey
404 Not Found - Survey does not exist
500 Internal Server Error - Something is majorly wrong

POST /surveys/copy/{survey_id}

This API call is used to make a copy of a survey.

*Special Case: The survey_id is part of the URI. Though if your application only has the survey_uid at this point, then just leave the survey_id empty in the URI and pass in the survey_uid as a query parameter. Here's an Example:

curl https://rapidengage.com/api/surveys/survey?survey_uid=8581546d -H "X-API-KEY: YOUR_API_KEY"

Parameters:

Parameter Required Type Default Description
survey_id *special case int - The ID of the survey
survey_uid *special case string(8) - The UID of the survey
X-API-KEY yes string(36) - Developer API Key
X-AUTH-TOKEN yes string(36) - User Authentication Token

Errors:

HTTP CODE Description
400 Bad Request - The required fields were not passed in
401 Unauthorized - Auth Token Required
403 Forbidden - Invalid Auth Token
403 Forbidden - Invalid API Key
403 Forbidden - The passed in Authentication Token does not have access to the survey
404 Not Found - Survey does not exist
500 Internal Server Error - Something is majorly wrong

DELETE /surveys/survey/{survey_id}

This API call is used to delete a survey.

*Special Case: The survey_id is part of the URI. Though if your application only has the survey_uid at this point, then just leave the survey_id empty in the URI and pass in the survey_uid as a query parameter. Here's an Example:

curl https://rapidengage.com/api/surveys/survey?survey_uid=8581546d -H "X-API-KEY: YOUR_API_KEY"

Parameters:

Parameter Required Type Description
survey_id *special case int The ID of the survey
survey_uid *special case string(8) The UID of the survey
X-API-KEY yes string(36) Developer API Key
X-AUTH-TOKEN yes string(36) User Authentication Token

Errors:

HTTP CODE Description
400 Bad Request - The required fields were not passed in
401 Unauthorized - Auth Token Required
403 Forbidden - Invalid Auth Token
403 Forbidden - Invalid API Key
403 Forbidden - The passed in Authentication Token does not have access to the survey
404 Not Found - Survey does not exist
500 Internal Server Error - Something is majorly wrong
Expand

Users

GET /users/me

This API call is used to get the meta-data of the current user.

Parameters:

Parameter Required Type Description
X-API-KEY yes string(36) Developer API Key
X-AUTH-TOKEN yes string(36) User Authentication Token

Errors:

HTTP CODE Description
401 Unauthorized - Auth Token Required
403 Forbidden - Invalid Auth Token
403 Forbidden - Invalid API Key

POST /users/signup

This API call is used to create a new account on the 14 day free trial.

Parameters:

Parameter Required Type Default Description
email yes string(100) - The user's email
password yes string(100) - The user's password
notifications no string(5) true A flag (true/false) to enable emails and marketing newsletters
X-API-KEY yes string(36) - Developer API Key

Errors:

HTTP CODE Description
400 Bad Request - The required fields were not passed in
400 Bad Request - The email is already in use
403 Forbidden - Invalid API Key
500 Internal Server Error - Something is majorly wrong

POST /users/forgot

This API call is used to request a reset password token. This will also send out an email to the current user.

Parameters:

Parameter Required Type Description
email yes string(100) The user's email
X-API-KEY yes string(36) Developer API Key

Errors:

HTTP CODE Description
400 Bad Request - The required fields were not passed in
403 Forbidden - Invalid API Key
404 Not Found - Email does not exist
500 Internal Server Error - Something is majorly wrong

POST /users/reset/{reset_token}

This API call is used to reset the password. This will also send out an email to the current user.

Parameters:

Parameter Required Type Description
reset_token yes string(100) The password reset token
password yes string(100) The new password
confirm yes string(100) Confirm the new password
X-API-KEY yes string(36) Developer API Key

Errors:

HTTP CODE Description
400 Bad Request - The required fields were not passed in
403 Forbidden - Invalid API Key
404 Not Found - Password rest token is expired or does not exist
500 Internal Server Error - Something is majorly wrong

POST /users/widget/{survey_id}

This API call is used to update the active layer for the current user's Engagement Layers.

*Special Case: The survey_id is part of the URI. Though if your application only has the survey_uid at this point, then just leave the survey_id empty in the URI and pass in the survey_uid as a query parameter. Here's an Example:

curl https://rapidengage.com/api/surveys/survey?survey_uid=8581546d -H "X-API-KEY: YOUR_API_KEY"

Parameters:

Parameter Required Type Description
survey_id *special case int The ID of the survey
survey_uid *special case string(8) The UID of the survey
X-API-KEY yes string(36) Developer API Key
X-AUTH-TOKEN yes string(36) User Authentication Token

Errors:

HTTP CODE Description
400 Bad Request - The required fields were not passed in
401 Unauthorized - Auth Token Required
403 Forbidden - Invalid Auth Token
403 Forbidden - Invalid API Key
403 Forbidden - The passed in Authentication Token does not have access to the survey
404 Not Found - Survey does not exist
500 Internal Server Error - Something is majorly wrong

POST /users/vanity

This API call is used to update the Custom Vanity URL for the current user.

Parameters:

Parameter Required Type Description
url yes string(100) The new Custom Vanity URL name
X-API-KEY yes string(36) Developer API Key
X-AUTH-TOKEN yes string(36) User Authentication Token

Errors:

HTTP CODE Description
400 Bad Request - The required fields were not passed in
400 Bad Request - The passed in vanity is already in use or is not allowed
401 Unauthorized - Auth Token Required
403 Forbidden - Invalid Auth Token
403 Forbidden - Invalid API Key
500 Internal Server Error - Something is majorly wrong

POST /users/privacy

This API call is used to update the privacy flag for the current user.

Parameters:

Parameter Required Type Default Description
privacy no string(5) false A flag (true/false) to mark the account as private
X-API-KEY yes string(36) - Developer API Key
X-AUTH-TOKEN yes string(36) - User Authentication Token

Errors:

HTTP CODE Description
401 Unauthorized - Auth Token Required
403 Forbidden - Invalid Auth Token
403 Forbidden - Invalid API Key
500 Internal Server Error - Something is majorly wrong

POST /users/email

This API call is used to update the email for the current user.

Parameters:

Parameter Required Type Description
email yes string(100) The new email
X-API-KEY yes string(36) Developer API Key
X-AUTH-TOKEN yes string(36) User Authentication Token

Errors:

HTTP CODE Description
400 Bad Request - The required fields were not passed in
400 Bad Request - The passed in email is already in use
401 Unauthorized - Auth Token Required
403 Forbidden - Invalid Auth Token
403 Forbidden - Invalid API Key
500 Internal Server Error - Something is majorly wrong

POST /users/thanks

This API call is used to update the Thank You Page links for the current user.

Parameters:

Parameter Required Type Default Description
facebook no string(100) null The full URL to a facebook page
twitter no string(100) null The full URL to a twitter page
website no string(100) null The full URL to a website
X-API-KEY yes string(36) - Developer API Key
X-AUTH-TOKEN yes string(36) - User Authentication Token

Errors:

HTTP CODE Description
400 Bad Request - The required fields were not passed in
401 Unauthorized - Auth Token Required
403 Forbidden - Invalid Auth Token
403 Forbidden - Invalid API Key
500 Internal Server Error - Something is majorly wrong

POST /users/password

This API call is used to reset the password for the current user.

Parameters:

Parameter Required Type Description
password yes string(100) The new password
confirm yes string(100) Confirm the new password
X-API-KEY yes string(36) Developer API Key
X-AUTH-TOKEN yes string(36) - User Authentication Token

Errors:

HTTP CODE Description
400 Bad Request - The required fields were not passed in
401 Unauthorized - Auth Token Required
403 Forbidden - Invalid Auth Token
403 Forbidden - Invalid API Key
500 Internal Server Error - Something is majorly wrong

DELETE /users/widget

This API call is used to disable all Engagement Layers for the current user.

Parameters:

Parameter Required Type Description
X-API-KEY yes string(36) Developer API Key
X-AUTH-TOKEN yes string(36) User Authentication Token

Errors:

HTTP CODE Description
401 Unauthorized - Auth Token Required
403 Forbidden - Invalid Auth Token
403 Forbidden - Invalid API Key
500 Internal Server Error - Something is majorly wrong

DELETE /users/user

This API call is used to cancel the current user's account.

Parameters:

Parameter Required Type Description
X-API-KEY yes string(36) Developer API Key
X-AUTH-TOKEN yes string(36) User Authentication Token

Errors:

HTTP CODE Description
401 Unauthorized - Auth Token Required
403 Forbidden - Invalid Auth Token
403 Forbidden - Invalid API Key
500 Internal Server Error - Something is majorly wrong
502 Bad Gateway - Stripe had a failure when removing the customer from the current subscription