How does a respondent get to and from a Survey using the InnovateMR platform? This is a great question and one that we'll classify as the Respondent-Survey flow throughout the documentation.

The following sections walk through the best practices in routing respondents to the Survey, receiving them back to your platform, and monitoring the results of the respondent's experience.

Overview

The overall Respondent-Survey Flow can be described as the following:

Supplier Platform -> InnovateMR Platform -> Client Survey/Questionnaire -> InnovateMR Platform -> Supplier Platform

To help discuss this flow, we break it down into three legs:

Pre-Survey: Supplier Platform -> InnovateMR Platform

In-Survey: Client Survey/Questionnaire

Post-Survey: InnovateMR Platform -> Supplier Platform

How do we identify a respondent?

This is done through the PID paramater that you'll see used throughout this documentation.

INFO

The expectaction is that this PID value is unique and persistent for a respondent.

Meaning if Sally is a respondent and has wants to take a survey on our platform, you would provide the same PID value for Sally each time you route her to our platform.

This way we can easily identifier her and not repeatedly ask her the same profiling questions.

Routing Respondents to Survey (Pre-Survey)

Survey Entry Link

Each Survey that you are exposed to has an EntryLink which is specific for you - the Supplier - and the Survey.

This is what you use to route your respondents from your platform to the InnovateMR Platform.

Below is an example Survey Entry Link from Get Allocated Surveys API Endpointresponse.

...
{
surveyId": 123456789,
Country": "United States",
"Language": "ENGLISH",
"groupType": "Consumer",
"deviceType": "All",
"reContact": false
"entryLink": "https://edgeapi.innovatemr.net/startSurvey?survNum=zqavdxQZMv&supCode=00000&PID=[%%pid%%]"
"isPIIRequired": false,
"numberOfCompletes": 247,
"numberOfStarts": 266,
...
}
...

Survey Entry Link Data

Important items to note from the Survey Entry Link

https://edgeapi.innovatemr.net/startSurvey? - This is the landing page that all your respondents need to land on to start the Respondent-Survey flow.

survNum - This is an encrypted identifier of the survey you want to route your Respondent to.

supCode - This is the identifier that indicate from whom the Respondent came from. This is how we associate Respondent traffic to you.

PID - This is the unique, persistent ID of the Respondent.

INFO

All of these parameters are mandatory for the Respondent-Survey Flow to be successful.

Supplying Respondent Targeting Information via Url
In addition to the required parameters, you can provide Respondent demographic information via the Survey Entry Link through the use of query string parameters.

This allows the InnovateMR platform to reduce the amount of profiling questions that have to be asked before it is determined if the respondent qualifies for the associated Survey.

Url Format

The profiling information is supplied through appending Query String Paramaters to the end of the Survey Entry Link. The format is &{QuestionKey}={AnswerOptionID}

For example, this is how you would provide respondent test456 value for DEMOGRAPHIC_6796 and GENDER questions/qualifications.

Example URL

https://edgeapi.innovatemr.net/startSurvey?survNum=abc1234&supCode=123&PID=test456&DEMOGRAPHIC_6796=1&GENDER=2

The QuestionKey and AnswerOptionID values can be found through our various Question and Answer endpoints.

Supplying Respondent Targeting Information via Respondent Profiling Endpoint

If you'd prefer not to provide a respondent's profiling information via the Survey Entry Url, you can use the Set Respondent Profiling API Endpoint.

Supplying Session Identifiers
If you need to provide some form of Session or sub-id for the respondent, you can place that data in a query string paramater named trackId

Any value provided via this parameter can be returned to your platform via the Redirect Url or Notification payload.

Routing Respondent to Client Survey (In-Survey)

Once your Respondent reaches the InnovateMR Platform and makes it through the Pre-Survey checks and validations, they will be routed to the actual Client Survey / Questionnaire. Think Confirmit, Decipher, Vision Suite, etc.

The InnovateMR Platform handles all the necessary details of getting your Respondent into the Questionnaire and handles the communications with the various Survey Authoriting tools/platforms that our Clients use.

Once your Respondent has finished their experience on the Client Survey, they will be redirected back to the InnovateMR Platform and shortly therafter (almost immediately) routed back to your platform.

Receiving Respondents Back From InnovateMR Platform (Post-Survey)

To complete the journey of the Respondent making it back to your platform, the InnovateMR Platform has to know where to send them, and with what data, and under what circumstances. To accomplish this, we have what are called Redirect Urls setup.

Redirect Urls

A Redirect Url is the "internet location" you need your Respondent to be returned to when they are Redirected back from the InnovateMR Platform.

A few example Redirect Urls are as follows:

https://bestSupplier.com/redirectlanding/imr/complete
https://anotherReallyGoodSupplier.com/landing?platform=innovatemr&status=terminated

Your Redirect Urls should resolve to web pages that are able to accept the return-bound Respondent, capture the desired details from the Survey experience, and place them on the next iteration of your journey for them.

Redirect Url Types

The InnovateMR Platform has several Redirect Urls that need to be set so that Respondents are always handled correctly back to your platform.

Here is more information regarding the various Redirect Url Types

Type	Description	Assoc. Survey TX Statuses
Success	Used when a Respondent successfully completes a survey.
Failure	Used when a Respondent is terminated while in Client Side survey.	Failed
Over Quota	Used when a Respondent is marked as Over Quota by client.	Over Quota
Quality Terminate survey	Used when a Respondent is marked as Quality terminate by client	Quality Term
Pre-Survey Terminate	Used when a Respondent does not meet the Survey Qualifications, there's pre-survey quality issue, or if the Survey is no longer available for participation.	Pre-Survey Termination, Pre-Survey Over Quota, Pre-Survey Quality Term

Notes

The values of these Redirect Urls do not have to all point to different Urls - it is 100% dependent on the architecture of your platform.

BUT a value has to be set for each of these Redirect Urls; otherwise, there would be situations in which Respondents wouldn't be returned to your platform.

Notifications

To complement Redirect Urls, we also offer Server-to-Server Notifications to be setup between your platform and the InnovateMR Platform.

If Redirect Urls determine where the Respondent is routed, Notifications serve as a direct communication to help you verify that.

The use of Notifications is optional but our recommendation is for them to be implemented so that you can cross-check any Complete you receive from a Redirect.

This means that if a Respondent lands on your platform on a Complete Redirect Url/End page, you should also receive a Notification indicating the same. If not, the survey transaction should be flagged and inspected for fraud.

What is a Notification, Postback, or Server-to-Server (s2s) call?

These all refer to a server-to-server call that is made from the InnovateMR platform to the Supplier platform which contain information about an activity that occurred. Since it is a server-to-server call and not tied to the respondent's browser, they are more secure and the preferred method of passing information between two platforms.

Sometimes they are also known as wehbooks.

Notification Urls

Type	Description	Assoc. Survey TX Statuses
Success	Used when a Respondent successfully completes a survey.	Complete
Failure	Used when a Respondent does not successfully complete a survey.	All but Complete

Notes

The values of these Notification Urls do not have to all point to different Urls - it is 100% dependent on the architecture of your platform.

The use of Notifications is optional but strongly recommended due to the increase in security against fraud it provides.

Redirect/Notification Url Scope

For further flexibility, the InnovateMR Platform allows Redirect & Notification Urls to be set at two differnt levels or scopes.

Survey Specific - These are specific Redirect and Notification Urls that are used for survey transactions that occurr for a specific survey.

Account Level - These are the default values that are used whenever a Survey specific setup is not in effect.

The InnovateMR Platform checks first to see if Survey Specific Redirect or Notification Urls are set. If they are present, the Survey Specific ones are used; otherwise, the Account Level values are used.

Redirect/Notification Data

Along with passing the Respondent to and from Platforms, Redirects and Notifications contain the contextual data that is needed for your Platform to have insight into what took place.

To accomplish this, we offer several properties to be passed along on the Redirect/Nofitication Urls. The table below explains those properties in detail.

Property	Key	Description
token	%%token%%	The unique identifier of a survey transaction.
pid	%%pid%%	The Supplier-provided, unique, persistent Identifier of a respondent
status	%%status%%	Status of survey: Success (1), Termination (2), Over Quota (3), Quality Termination (4), Pre-Survey Termination (5), Pre-Survey Over Quota (7), and Pre-Survey Quality Termination (8)
revenue	%%revenue%%	Supplier final calculated CPI for survey complete.
surveyId	%%surveyId%%	Survey Id of the Survey Transasction.
termReason	%%termReason%%	Detailed reason for the survey termination.
trackId	%%trackId%%	Supplier-provided unique transaction Id which was supplied on the Survey Entry link.
closeQuotaId	%%closeQuotaId%%	ID of the Quota which was closed .
hashdata	%%hashdata%%	The hashed value of the Survey Transaction .

We've built a tool that helps with the construction of Redirect and Notification Urls. https://developer.innovatemr.com/#redirect-url-helper

Url Helper / Buildier

We've created a URL Builder tool to help ensure that your URLs are properly formatted and contain the information you desired.

INFO

Click here to Access Url Builder

Receiving Respondent Profiling Information

Retrieve Respondent Targeting Information via Redirect Url

To ensure that you have access to any profiling information collected on a respondent, we offer the ability to return this information to you via the Redirect Url.

The profiling information is appended to the redirect url using the format of &{QuestionKey}={AnswerOptionID}

In the example below you can see three piece of profiling information have been appended to the Redirect Url.

Example Redirect Url

https://supplier.com/complete?&supplierPID=test456&DEMOGRAPHIC_6796=1&GENDER=2&EDUCATION=5

Retrieve Respondent Targeting Information via Respondent Profiling Endpoint
If you'd prefer to retrieve profiling information outside of the Redirect Url, you can use the Get Respondent Profiling API Endpoint.

This will return all profiling information we have for the provided respondent.

How to set Redirect and Notification Urls.

Since there are two scopes - Survey specific or Account - you can use the following two API endpoints accordingly:

Set Account Urls

Set Survey Specific Urls

Redirect Url Hashing

To provide an additional layer of protection against fraud, we offer the hashing of Redirect Url. (This is also sometimes referred to as url signing.)

Our approach is that we fully hydrate the redirect url and then using a shared secret key and agreed upoon hashing algorith, we generate a hash value. Next that value is appended to the Redirect url and then the respondent is redirect back to your platform.

This is best illustrated through an example.

Setting	Value
Input
Initial Redirect Url	`https://www.xyz.com/web-service/innovate?pid=ct4JGltDsCS&trackId=28969&status=3&surveyid=123&hash=`
Algo	SHA1
Secret	supersecretkey123
Output
Computed hash	`2e24312e5523dd99e47b9c9bc904986f1835d5e1`
Final Redirect Url	`https://www.xyz.com/web-service/innovate?pid=ct4JGltDsCS&trackId=28969&status=3&surveyid=123&hash=2e24312e5523dd99e47b9c9bc904986f1835d5e1`

This website can be used to test/verify hashed values.

Redirect Url Hashing Notes

Hashing Algorithms

We currently offer the following hashing algorithms:

SHA1

MD5

**Hashing secret ** The hashing secret is not available for retrieval via the API, please reach out to the InnovateMR team for this information.

Commonly Asked Questions

How do I ensure the most security for Redirects and Notifications?

Use HTTPS endpoints

Utilize Notifications

Utilize Redirect Url Hashing

How do I test the Respondent-Survey flow?

Make sure you have your redirects and notifications setup and then you can use the testEntryLink on the desired Survey to perform an end-to-end test.

How do I identify a respondent?

This is done through the PID value/parameter

How can I pass along a session identifier?

You can use the trackId parameter

How do I get a respondent to a survey?

Each survey has an Entry Link that you can utilize.

How do I pick where a respondent is returned to my platform?

This is done through settingnredirect urls

How do I provide or set profiling information for a respondent?

You have two options

via Query String Parameters on the Survey Entry Link

Respondent Profiling API endpoints

How do I get information about the survey experience back?

This can be done via Redirect Url parameters and/or Notification

Does my respondent have to match ALL of the survey targeting? Is 100% match required?

No, 100% match is not required.

If you only have profiling information for some of the targeting question, go ahead and send them to the survey and we will fill in any gaps in targeting information.

Do we provide rediect url hashing?

Yes, please see the Redirect Url hashing section

Do we provide server to server calls?

Yes, please see the Notifications section

How do we handle Returning Respondents?

These are identified by the same PID value being used across survey experiences.

Respondent-Survey Flow

Overview#

How do we identify a respondent?#

Routing Respondents to Survey (Pre-Survey)#

Survey Entry Link#

Survey Entry Link Data#

Routing Respondent to Client Survey (In-Survey)#

Receiving Respondents Back From InnovateMR Platform (Post-Survey)#

Redirect Urls#

Redirect Url Types#

Notifications#

Redirect/Notification Url Scope#

Redirect/Notification Data#

Url Helper / Buildier#

Receiving Respondent Profiling Information#

How to set Redirect and Notification Urls.#

Redirect Url Hashing#

Redirect Url Hashing Notes#

Commonly Asked Questions#

How do I ensure the most security for Redirects and Notifications?#

How do I test the Respondent-Survey flow?#

How do I identify a respondent?#

How can I pass along a session identifier?#

How do I get a respondent to a survey?#

How do I pick where a respondent is returned to my platform?#

How do I provide or set profiling information for a respondent?#

How do I get information about the survey experience back?#

Does my respondent have to match ALL of the survey targeting? Is 100% match required?#

Do we provide rediect url hashing?#

Do we provide server to server calls?#

How do we handle Returning Respondents?#

Overview

How do we identify a respondent?

Routing Respondents to Survey (Pre-Survey)

Survey Entry Link

Survey Entry Link Data

Routing Respondent to Client Survey (In-Survey)

Receiving Respondents Back From InnovateMR Platform (Post-Survey)

Redirect Urls

Redirect Url Types

Notifications

Redirect/Notification Url Scope

Redirect/Notification Data

Url Helper / Buildier

Receiving Respondent Profiling Information

How to set Redirect and Notification Urls.

Redirect Url Hashing

Redirect Url Hashing Notes

Commonly Asked Questions

How do I ensure the most security for Redirects and Notifications?

How do I test the Respondent-Survey flow?

How do I identify a respondent?

How can I pass along a session identifier?

How do I get a respondent to a survey?

How do I pick where a respondent is returned to my platform?

How do I provide or set profiling information for a respondent?

How do I get information about the survey experience back?

Does my respondent have to match ALL of the survey targeting? Is 100% match required?

Do we provide rediect url hashing?

Do we provide server to server calls?

How do we handle Returning Respondents?