Basic request

PUT survey/next

Promana expects a PUT survey/next with specific parameters for each state change, in all three phases. When your application provides the appropriate parameters, PfP will return a success message that contains a JSON structure which includes data that you should present to your user in the subsequent UI.

Parameters explained

There are five possible parameters you can pass to the method, but not every state requires all five. The parameters are:

1. sequence_num integer [required] – starting at 0 for the initial survey state, and incrementing by one for each subsequent state
2. survey_uuid string [required] – a valid assessment_uuid assigned to one of your users
3. user_uuid string [required] – a valid uuid for a user that exists anywhere in your org who has been assigned the survey_uuid
4. choice – string A|B|X [required when sequence_num > 0] – the respondent’s choice for the given statement pair
5. token – string [required when sequence_num > 0] – a token that validates the user’s input is for the expected pair

Initial state parameters

In phase one of the survey, the respondent hasn’t yet begun the survey. They are yet to be presented with the first pair of statements and your application has yet to receive the first pair of statements.

Phase one of the survey is represented in the diagram below as State 0.

Therefore to start a survey sequence, you must initially pass a sequence_num of 0.

• sequence_num must be 0
• survey_uuid
• user_uuid

Second phase state parameters

Promana expects all five parameters. The token value will be the token value delivered in the previous response.

Final phase state parameters

Promana expects at most four parameters:

1. sequence_num
2. survey_uuid
3. user_uuid
4. choice unless sequence_num=0

Usually, in the final (3rd) phase, your application will pass sequence_num=78. However the user’s experience may not be in sync with the survey state (for example they might have more than one browser tab open and the survey - as presented to the user – may be at different states in each; such a case could have a browser state at sequence_num=5).

When the Promana’s survey state is at sequence_num 78, any PUT sequence_num greater than 0 requires the choice parameter. However, if the PUT sequence_num=0, choice is not required.