Default | Pulse Insights Documentation

get

Returns a specific survey with the provided ID.

Path parameters

survey_idnumberRequired

The survey's unique identifier.

Query parameters

identifierstringRequired

The account's unique ID.

Example: PI-1234567890

device_typestring · enumRequired

The type of device that's requesting the survey/poll. Use 'desktop' if unsure.

Possible values:

callbackstringOptional

Conditionally required. If device_type != 'native_mobile' OR 'email'. Response will be wrapped in callback code. For example, passing "console.debug" will result in "console.debug('{}')".

Example: console.debug

custom_datastringOptional

Also known as "Context Data". Used to specify context in which the survey appeared. See https://docs.pulseinsights.com/implementing-pulse-insights-dev/implementing-on-web-and-mobile-web/ingesting-contextual-data-for-targeting-and-analysis#context-data for more details.

preview_modestringOptional

If 'true' then nothing will be recorded in the database.

Example: true

visit_countnumberOptional

The number of times the user has visited the site. Used to target surveys.

pageview_countnumberOptional

The number of times the user has visited the page. Used to target surveys.

udidstringRequired

The device's unique ID.

Example: 00000000-0000-4000-f000-000000000001

urlstringOptional

The URL from which the submission was made. If not provided HTTP_REFERER will be used as a fallback.

Responses

200

Successful response. Will return empty object if no eligible surveys are found. Otherwise the return type is based on the "device_type" parameter. (native_mobile, email, all others).

application/javascript

stringOptionalExample: {}

or

get

/surveys/{survey_id}

GET /surveys/{survey_id}?identifier=PI-1234567890&device_type=desktop&udid=00000000-0000-4000-f000-000000000001 HTTP/1.1
Host: survey.pulseinsights.com
Accept: */*

200

Successful response. Will return empty object if no eligible surveys are found. Otherwise the return type is based on the "device_type" parameter. (native_mobile, email, all others).

{}

get

Retrieves a survey by its event name.

Path parameters

event_namestringRequired

The name of the event identifying the survey.

Pattern: /[-a-zA-Z0-9]+/

Query parameters

identifierstringRequired

The account's unique ID.

Example: PI-1234567890

device_typestring · enumRequired

The type of device that's requesting the survey/poll. Use 'desktop' if unsure.

Possible values:

callbackstringOptional

Conditionally required. If device_type != 'native_mobile' OR 'email'. Response will be wrapped in callback code. For example, passing "console.debug" will result in "console.debug('{}')".

Example: console.debug

custom_datastringOptional

Also known as "Context Data". Used to specify context in which the survey appeared. See https://docs.pulseinsights.com/implementing-pulse-insights-dev/implementing-on-web-and-mobile-web/ingesting-contextual-data-for-targeting-and-analysis#context-data for more details.

preview_modestringOptional

If 'true' then nothing will be recorded in the database.

Example: true

visit_countnumberOptional

The number of times the user has visited the site. Used to target surveys.

pageview_countnumberOptional

The number of times the user has visited the page. Used to target surveys.

udidstringRequired

The device's unique ID.

Example: 00000000-0000-4000-f000-000000000001

urlstringOptional

The URL from which the submission was made. If not provided HTTP_REFERER will be used as a fallback.

Responses

200

Successful response. Will return empty object if no eligible surveys are found. Otherwise the return type is based on the "device_type" parameter. (native_mobile, email, all others).

application/javascript

stringOptionalExample: {}

or

404

Error response.

text/plain

get

/surveys/{event_name}

GET /surveys/{event_name}?identifier=PI-1234567890&device_type=desktop&udid=00000000-0000-4000-f000-000000000001 HTTP/1.1
Host: survey.pulseinsights.com
Accept: */*

{}

get

Submit an answer to a non free text question. Records the answer in the db unless preview_mode == 'true'. All parameters except (identifier question_id answer_id text redirect preview_mode) will be recorded as ContextData in the submission.

Path parameters

question_idstringRequired

The question's unique ID.

answer_idstringRequired

The possible answer's unique ID.

Query parameters

identifierstringRequired

The account's unique ID.

Example: PI-1234567890

textstringOptional

Text of survey response. Required if free text question.

redirectstringOptional

A URL to redirect to after submission.

urlstringOptional

The URL from which the submission was made. If no redirect parameter is provided then this will be used as the redirect URL.

udidstringOptional

The device's unique ID.

Example: 00000000-0000-4000-f000-000000000001

preview_modestringOptional

If 'true' then nothing will be recorded in the database.

Example: true

Responses

200

Successful response.

text/plain

itemsstring · enumOptionalPossible values:

302

Successful response. Returned if "redirect" parameter is provided.

text/plain

404

Error response.

text/plain

get

/q/{question_id}/a/{answer_id}

GET /q/{question_id}/a/{answer_id}?identifier=PI-1234567890 HTTP/1.1
Host: survey.pulseinsights.com
Accept: */*

[
  "Thank you!"
]

get

Submit an answer to a free text question. Records the answer in the db unless preview_mode == 'true'. All parameters except (identifier question_id text redirect preview_mode) will be record as ContextData in the submission.

Path parameters

question_idstringRequired

The question's unique ID.

Query parameters

identifierstringRequired

The account's unique ID.

Example: PI-1234567890

textstringOptional

Text of survey response. Required if free text question.

redirectstringOptional

A URL to redirect to after submission.

urlstringOptional

The URL from which the submission was made. If no redirect parameter is provided then this will be used as the redirect URL.

udidstringOptional

The device's unique ID.

Example: 00000000-0000-4000-f000-000000000001

preview_modestringOptional

If 'true' then nothing will be recorded in the database.

Example: true

Responses

200

Successful response.

text/plain

itemsstring · enumOptionalPossible values:

302

Successful response. Returned if "redirect" parameter is provided.

text/plain

404

Error response.

text/plain

get

/q/{question_id}

GET /q/{question_id}?identifier=PI-1234567890 HTTP/1.1
Host: survey.pulseinsights.com
Accept: */*

[
  "Thank you!"
]

get

Retrieve a survey's questions and possible answers.

Path parameters

survey_idstringRequired

The survey's unique ID.

Query parameters

identifierstringRequired

The account's unique ID.

Example: PI-1234567890

Responses

200

Successful response. Will return empty object if no eligible surveys are found.

application/javascript

stringOptionalExample: {}

or

400

Error response.

text/plain

get

/surveys/{survey_id}/questions

GET /surveys/{survey_id}/questions?identifier=PI-1234567890 HTTP/1.1
Host: survey.pulseinsights.com
Accept: */*

{}

get

Returns the first eligible survey along with its questions and possible answers. One of client_key and udid is required.

Query parameters

identifierstringRequired

The account's unique ID.

Example: PI-1234567890

client_keystringOptional

Used to identify a user across devices and advanced survey targeting. See https://docs.pulseinsights.com/implementing-pulse-insights-dev/implementing-on-web-and-mobile-web/client-key for more details.

udidstringRequired

The device's unique ID.

Example: 00000000-0000-4000-f000-000000000001

custom_datastringOptional

Also known as "Context Data". Used to specify context in which the survey appeared. See https://docs.pulseinsights.com/implementing-pulse-insights-dev/implementing-on-web-and-mobile-web/ingesting-contextual-data-for-targeting-and-analysis#context-data for more details.

preview_modestringOptional

If 'true' then nothing will be recorded in the database.

Example: true

Responses

200

Successful response. Will return empty object if no eligible surveys are found. Otherwise the return type is based on the "device_type" parameter. (native_mobile, email, all others).

application/javascript

stringOptionalExample: {}

or

400

Error response.

text/plain

get

/direct_serve

GET /direct_serve?identifier=PI-1234567890&udid=00000000-0000-4000-f000-000000000001 HTTP/1.1
Host: survey.pulseinsights.com
Accept: */*

{}

get

Serves an eligible survey.

Query parameters

identifierstringRequired

The account's unique ID.

Example: PI-1234567890

device_typestring · enumRequired

The type of device that's requesting the survey/poll. Use 'desktop' if unsure.

Possible values:

callbackstringOptional

Conditionally required. If device_type != 'native_mobile' OR 'email'. Response will be wrapped in callback code. For example, passing "console.debug" will result in "console.debug('{}')".

Example: console.debug

udidstringRequired

The device's unique ID.

Example: 00000000-0000-4000-f000-000000000001

preview_modestringOptional

If 'true' then it will return surveys in DRAFT status or with frequency caps enabled. (These are not returned otherwise).

Example: true

custom_datastringOptional

Also known as "Context Data". Used to specify context in which the survey appeared. See https://docs.pulseinsights.com/implementing-pulse-insights-dev/implementing-on-web-and-mobile-web/ingesting-contextual-data-for-targeting-and-analysis#context-data for more details.

visit_countnumberOptional

The number of times the user has visited the site. Used to target surveys.

client_keystringOptional

Used to identify a user across devices and advanced survey targeting. See https://docs.pulseinsights.com/implementing-pulse-insights-dev/implementing-on-web-and-mobile-web/client-key for more details.

pageview_countnumberOptional

The number of times the user has visited the page. Used to target surveys.

install_daysnumberOptional

Native-Mobile only. The number of days the app has been installed for.

Example: 1

launch_timesnumberOptional

Native-Mobile only. The number of times the app has been launched.

Example: 7

view_namestringOptional

Native-Mobile only. The view used to access the survey.

Example: domain.com

mobile_typestring · enumOptional

Native-Mobile only. The type of mobile device.

Possible values:

Responses

200

Successful response. Will return empty object if no eligible surveys are found. Otherwise the return type is based on the "device_type" parameter. (native_mobile, email, all others).

application/javascript

stringOptionalExample: {}

or

400

Error response.

text/plain

get

/serve

GET /serve?identifier=PI-1234567890&device_type=desktop&udid=00000000-0000-4000-f000-000000000001 HTTP/1.1
Host: survey.pulseinsights.com
Accept: */*

{}

get

Returns poll results for a survey question. Only works if the survey is configured as poll.

Path parameters

survey_idstringRequired

The survey's unique ID.

Query parameters

identifierstringRequired

The account's unique ID.

Example: PI-1234567890

callbackstringOptional

Conditionally required. If device_type != 'native_mobile' OR 'email'. Response will be wrapped in callback code. For example, passing "console.debug" will result in "console.debug('{}')".

Example: console.debug

device_udidstringOptional

The device's unique ID.

Example: 00000000-0000-4000-f000-000000000001

device_typestring · enumRequired

The type of device that's requesting the survey/poll. Use 'desktop' if unsure.

Possible values:

urlstringOptional

The URL where the event occurred. Conditionally required. Required if device_type = native_mobile.

question_idnumberRequired

The question's unique ID.

custom_datastringOptional

Also known as "Context Data". Used to specify context in which the survey appeared. See https://docs.pulseinsights.com/implementing-pulse-insights-dev/implementing-on-web-and-mobile-web/ingesting-contextual-data-for-targeting-and-analysis#context-data for more details.

preview_modestringOptional

If 'true' then nothing will be recorded in the database.

Example: true

visit_countnumberOptional

The number of times the user has visited the site. Used to target surveys.

pageview_countnumberOptional

The number of times the user has visited the page. Used to target surveys.

Responses

200

Successful response.

application/javascript

400

Error response.

text/plain

403

Forbidden. Poll is not enabled for this survey.

text/plain

get

/surveys/{survey_id}/poll

GET /surveys/{survey_id}/poll?identifier=PI-1234567890&device_type=desktop&question_id=1 HTTP/1.1
Host: survey.pulseinsights.com
Accept: */*

{
  "survey": {
    "id": 1,
    "name": "Fall Customer Engagement Survey",
    "survey_type": 0,
    "invitation": "Would you like to take a survey?",
    "top_position": "10px. 25%",
    "bottom_position": "10px. 25%",
    "left_position": "10px. 25%",
    "right_position": "10px. 25%",
    "width": 300,
    "background_color": "#ff00aa",
    "text_color": "#ff00aa",
    "inline_target_selector": "#survey_container",
    "thank_you": "Would you like to take a survey?",
    "answer_text_color": "#ff00aa",
    "mobile_inline_target_selector": "#mobile_survey_container",
    "sdk_inline_target_selector": "#sdk_survey_container",
    "display_all_questions": "t",
    "fullscreen_margin": 42,
    "invitation_button": "Click here to get started",
    "invitation_button_disabled": "f",
    "single_page": true,
    "ignore_frequency_cap": true,
    "randomize_question_order": "t",
    "all_at_once_empty_error_enabled": "t",
    "all_at_once_submit_label": "Submit",
    "all_at_once_error_text": "Please fill answers",
    "survey_locale_group_id": 1,
    "personal_data_masking_enabled": "t",
    "phone_number_masked": "t",
    "email_masked": "t",
    "background": "https://cdn.pulseinsights.com/background/survey/:survey_id/:background_image_url",
    "pulse_insights_branding": true,
    "custom_data_snippet": "text",
    "onclose_callback_code": "text",
    "oncomplete_callback_code": "text",
    "onanswer_callback_code": "text",
    "onview_callback_code": "text",
    "onclick_callback_code": "text",
    "custom_content_link_click_enabled": "t",
    "inline_target_position": 0,
    "theme_css": "text"
  },
  "question": {
    "id": 1,
    "question_type": "single_choice_question",
    "content": "text",
    "question_locale_group_id": 1
  },
  "results": {
    "poll": [
      {
        "id": 1,
        "content": "text",
        "count": 1
      }
    ],
    "content": "text",
    "question_type": "single_choice_question",
    "answers_via_checkbox": [
      [
        "12",
        "42"
      ]
    ]
  }
}

get

Submits all answers for a survey (all at once survey). Records the answers in the database UNLESS preview_mode is 'true'.

Path parameters

submission_udidstringRequired

The survey submission's unique ID.

Query parameters

identifierstringRequired

The account's unique ID.

Example: PI-1234567890

client_keystringOptional

Used to identify a user across devices and advanced survey targeting. See https://docs.pulseinsights.com/implementing-pulse-insights-dev/implementing-on-web-and-mobile-web/client-key for more details.

custom_datastringOptional

Also known as "Context Data". Used to specify context in which the survey appeared. See https://docs.pulseinsights.com/implementing-pulse-insights-dev/implementing-on-web-and-mobile-web/ingesting-contextual-data-for-targeting-and-analysis#context-data for more details.

preview_modestringOptional

If 'true' then nothing will be recorded in the database.

Example: true

pdf_resultsbooleanOptional

Get the results as a PDF file.

Responses

200

Successful response.

stringOptionalExample: {}

400

Error response.

text/plain

get

/submissions/{submission_udid}/all_answers

GET /submissions/{submission_udid}/all_answers?identifier=PI-1234567890&answers=[object+Object] HTTP/1.1
Host: survey.pulseinsights.com
Accept: */*

{}

get

Submits an answer to a survey question. Records the answer in the database UNLESS preview_mode is 'true'.

Path parameters

submission_udidstringRequired

The survey submission's unique ID.

Query parameters

identifierstringRequired

The account's unique ID.

Example: PI-1234567890

question_idstringRequired

The question ID.

answer_idstringOptional

Required by single choice questions, slider questions, and NPS questions.

text_answerstringOptional

Required if question is a free text question.

next_question_idstringOptional

Required if question is a custom content question.

check_boxesstringOptional

A comma-delimited string of possible answer IDs. Used by multiple choice questions.

Example: 1,23,42

preview_modestringOptional

If 'true' then nothing will be recorded in the database.

Example: true

Responses

200

Successful response. If survey has only one question and "show results instead" is enabled, then returns an object of poll results. Otherwise '{}'.

application/javascript

stringOptional

400

Error response.

text/plain

get

/submissions/{submission_udid}/answer

GET /submissions/{submission_udid}/answer?identifier=PI-1234567890&question_id=text HTTP/1.1
Host: survey.pulseinsights.com
Accept: */*

text

get

Marks a survey as being closed by the survey taker.

Path parameters

submission_udidstringRequired

The survey submission's unique ID.

Query parameters

identifierstringRequired

The account's unique ID.

Example: PI-1234567890

Responses

200

Successful response.

application/javascript

stringOptionalExample: {}

400

Error response.

text/plain

get

/submissions/{submission_udid}/close

GET /submissions/{submission_udid}/close?identifier=PI-1234567890 HTTP/1.1
Host: survey.pulseinsights.com
Accept: */*

{}

get

Marks a viewed impression.

Path parameters

submission_udidstringRequired

The survey submission's unique ID.

Query parameters

identifierstringRequired

The account's unique ID.

Example: PI-1234567890

viewed_atstring · date-timeRequired

The time the user saw the survey.

Example: 2023-05-31 11:12:07.304719 -0700

Responses

200

Successful response.

application/javascript

stringOptionalExample: {}

400

Error response.

text/plain

get

/submissions/{submission_udid}/viewed_at

GET /submissions/{submission_udid}/viewed_at?identifier=PI-1234567890&viewed_at=2023-05-31+11%3A12%3A07.304719+-0700 HTTP/1.1
Host: survey.pulseinsights.com
Accept: */*

{}

get

Sets a device's data.

Path parameters

deviceUdidstringRequired

The device's unique ID.

Example: 00000000-0000-4000-f000-000000000001

Query parameters

identifierstringRequired

The account's unique ID.

Example: PI-1234567890

Responses

200

Successful response.

application/javascript

stringOptionalExample: {}

400

Error response.

text/plain

get

/devices/{deviceUdid}/set_data

GET /devices/{deviceUdid}/set_data?identifier=PI-1234567890 HTTP/1.1
Host: survey.pulseinsights.com
Accept: */*

{}

get

Get results of survey. Or just a thank_you message.

Path parameters

submission_udidstringRequired

The survey submission's unique ID.

Query parameters

identifierstringRequired

The account's unique ID.

Example: PI-1234567890

acceptstringOptional

If provided a value of 'application/json', response will have JSON data rather than HTML

Responses

200

Successful response. HTML with JS which will download and present the survey results.

text/html; charset=utf-8

stringOptional

400

Error response.

text/plain

get

/results

GET /results?identifier=PI-1234567890 HTTP/1.1
Host: survey.pulseinsights.com
Accept: */*

text

get

If the survey has polling enabled then return the results of the survey, otherwise return a thank_you message.

Path parameters

submission_udidstringRequired

The survey submission's unique ID.

Query parameters

identifierstringRequired

The account's unique ID.

Example: PI-1234567890

Responses

200

Successful response.

application/javascript

or

400

Error response.

text/plain

get

/present_results

GET /present_results?identifier=PI-1234567890 HTTP/1.1
Host: survey.pulseinsights.com
Accept: */*

{"thank_you": "Thank you for taking this survey!"}

get

Record the occurrence of an event.

Query parameters

event_namestringRequired

A descriptive name for the event.

event_propertiesobjectRequired

An object representing the properties to record.

Example: {"test":1}

identifierstringRequired

The account's unique ID.

Example: PI-1234567890

udidstringRequired

The device's unique ID.

Example: 00000000-0000-4000-f000-000000000001

urlstringRequired

The URL where the event occurred.

Responses

200

Successful response.

application/javascript

stringOptionalExample: {}

400

Error response.

text/plain

get

/track_event

GET /track_event?event_name=text&event_properties=[object+Object]&identifier=PI-1234567890&udid=00000000-0000-4000-f000-000000000001&url=text HTTP/1.1
Host: survey.pulseinsights.com
Accept: */*

{}

get

Registers a click for a particular link in a custom content question. Increments the click count of the specified link by one.

Query parameters

client_keystringOptional

Used to identify a user across devices and advanced survey targeting. See https://docs.pulseinsights.com/implementing-pulse-insights-dev/implementing-on-web-and-mobile-web/client-key for more details.

custom_datastringOptional

Also known as "Context Data". Used to specify context in which the survey appeared. See https://docs.pulseinsights.com/implementing-pulse-insights-dev/implementing-on-web-and-mobile-web/ingesting-contextual-data-for-targeting-and-analysis#context-data for more details.

submission_udidstringRequired

The survey submission's unique ID.

question_idnumberRequired

The custom content question's unique ID.

link_identifierstringRequired

The UUID of the link that would be included in the "data-pi-link-id" attribute.

Responses

200

Successful response.

application/javascript

stringOptionalExample: {}

400

Error response.

text/plain

get

/custom_content_link_click

GET /custom_content_link_click?submission_udid=text&question_id=1&link_identifier=text HTTP/1.1
Host: survey.pulseinsights.com
Accept: */*

{}