Survey Service

The survey service provides endpoints to request survey content and provide responses to survey questions.

Endpoints

Get Eligible Surveys by Username

GET survey/eligibleSurveys.json

Obtains a list of the survey codes that a guest is currently eligible to take, as well as any date and/or time restrictions for those surveys.

The following authentication methods are allowed for this endpoint:

Query Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant identifier (ID) in which to perform the operation.
  • username (String) – (required) Username associated with the account for which to obtain eligible surveys.
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • surveys (List[Object]) – (required) The list of surveys in which the user is eligible to participate. See EligibleSurvey for the format of these objects.
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The human readable error message of the failure.

Get Eligible Surveys by Printed Card Number

GET survey/eligibleSurveysByPrintedCardNumber.json

Obtains a list of the survey codes that a guest is currently eligible to take, as well as any date and/or time restrictions for those surveys.

The following authentication methods are allowed for this endpoint:

Query Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant identifier (ID) in which to perform the operation.
  • printedCardNumber (String) – (required) Printed card number associated with the account for which to obtain eligible surveys.
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • surveys (List[Object]) – (required) The list of surveys in which the user is eligible to participate. See EligibleSurvey for the format of these objects.
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The human readable error message of the failure.

Opt In To Survey by Username

POST survey/optInToSurvey.json

This makes an individual guest eligible to participate in a specific survey.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant identifier (ID) in which to perform the operation.
  • username (String) – (required) Username of the participant who is being entered into the survey.
  • code (String) – (required) Code of the specific survey to which the participant is being entered. This information is configured and visible in the Paytronix Survey Center.
  • daysAvailableToComplete (Integer) – (optional) Number of days the participant has to complete the survey before the survey becomes inactive.
  • optInTransactionRequestDetailId (Long) – (optional) ID of the transaction that caused the participant to be entered into the survey.
  • campaignOccurrenceId (Integer) – (optional) ID of the campaign occurrence that caused the participant to be entered into the survey.
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • username (String) – (required) Username for the participant who was entered into the survey.
  • code (String) – (required) Code of the specific survey to which the participant was entered.
  • optedInDateTime (String) – (required) Date and time that the participant was entered into the survey, in the format yyyy-MM-dd HH:mm:ss Z, ex: 2016-09-06 16:29:22 -0400
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The human readable error message of the failure.

Opt In To Survey by Printed Card Number

POST survey/optInToSurveyByPrintedCardNumber.json

This makes an individual guest eligible to participate in a specific survey.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant identifier (ID) in which to perform the operation.
  • printedCardNumber (String) – (required) Printed card number for the participant who is being entered into the survey.
  • code (String) – (required) Code of the specific survey to which the participant is being entered. This information is configured and visible in the Paytronix Survey Center.
  • daysAvailableToComplete (Integer) – (optional) Number of days the participant has to complete the survey before the survey becomes inactive.
  • optInTransactionRequestDetailId (Long) – (optional) ID of the transaction that caused the participant to be entered into the survey.
  • campaignOccurrenceId (Integer) – (optional) ID of the campaign occurrence that caused the participant to be entered into the survey.
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • username (String) – (required) Username for the participant who was entered into the survey.
  • code (String) – (required) Code of the specific survey to which the participant was entered.
  • optedInDateTime (String) – (required) Date and time that the participant was entered into the survey, in the format yyyy-MM-dd HH:mm:ss Z, ex: 2016-09-06 16:29:22 -0400
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The human readable error message of the failure.

Get Survey Details by Username

GET survey/surveyDetails.json

Obtains the details (content) of a specific survey by username.

The following authentication methods are allowed for this endpoint:

Query Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant identifier (ID) in which to perform the operation.
  • username (String) – (required) Username of the participant who is requesting the survey details.
  • code (String) – (required) Code of the specific survey for which the details are being requested. This information is configured and visible in the Paytronix Survey Center.
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • details (Object) – (required) Content of the survey to provide to the participant. See Details for the format of this object.
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The human readable error message of the failure.

Get Survey Details by Printed Card Number

GET survey/surveyDetailsByPrintedCardNumber.json

Obtains the details (content) of a specific survey by printed card number.

The following authentication methods are allowed for this endpoint:

Query Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant identifier (ID) in which to perform the operation.
  • printedCardNumber (String) – (required) Printed card number for the participant who is requesting the survey details.
  • code (String) – (required) Code of the specific survey for which the details are being requested. This information is configured and visible in the Paytronix Survey Center.
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • details (Object) – (required) Content of the survey to provide to the participant. See Details for the format of this object.
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The human readable error message of the failure.

Submit Response to Survey by Username

POST survey/submitResponse.json

Submit answers to the survey questions of a specific survey by username.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant identifier (ID) in which to perform the operation.
  • username (String) – (required) Username of the participant who is submitting the survey response.
  • code (String) – (required) Code of the specific survey for which the participant is submitting a response. This information is configured and visible in the Paytronix Survey Center.
  • answers (List[Object]) – (required) List of answers to specific survey questions. See SurveyAnswer for the format of this object.
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • message (String) – (required) Message that can be presented to the survey participant.
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The human readable error message of the failure.
  • errorDetail (List[Integer]) – (optional) List of question codes for errors that were specific to those questions, such as an invalid answer choice.

Submit Response to Survey by Printed Card Number

POST survey/submitResponseByPrintedCardNumber.json

Submit answers to the survey questions of a specific survey by printed card number.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant identifier (ID) in which to perform the operation.
  • printedCardNumber (String) – (required) Printed card number for the participant who is submitting the survey response.
  • code (String) – (required) Code of the specific survey for which the participant is submitting a response. This information is configured and visible in the Paytronix Survey Center.
  • answers (List[Object]) – (required) List of answers to specific survey questions. See SurveyAnswer for the format of this object.
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • message (String) – (required) Message that can be presented to the survey participant.
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The human readable error message of the failure.
  • errorDetail (List[Integer]) – (optional) List of question codes for errors that were specific to those questions, such as an invalid answer choice.

Reply Objects

EligibleSurvey

Information about a survey that a participant is eligible to complete.

JSON Parameters:
 
  • code (String) – (required) Unique code of the survey.
  • optedInDatetime (String) – (required) Date and time that the user was made eligible to participate in the survey, in the format yyyy-MM-dd HH:mm:ss Z, ex: 2016-09-06 16:29:22 -0400
  • expirationDatetime (String) – (optional) Date and time after which the participant can no longer submit a response to the survey, in the format yyyy-MM-dd HH:mm:ss Z, ex: 2016-09-06 16:29:22 -0400
Details

More detailed information about a survey that a participant is eligible to complete, including the actual content of the survey questions.

JSON Parameters:
 
  • code (String) – (required) Unique code of the survey.
  • title (String) – (required) Title of the survey.
  • description (String) – (optional) Description of the survey.
  • startDatetime (String) – (required) Date and time after which participants can submit responses to the survey, in the format yyyy-MM-dd HH:mm:ss Z, ex: 2016-09-06 16:29:22 -0400
  • expirationDatetime (String) – (optional) Date and time after which the participant can no longer submit a response to the survey, in the format yyyy-MM-dd HH:mm:ss Z, ex: 2016-09-06 16:29:22 -0400
  • questions (List[Object]) – (required) Questions to be presented to the participant. See Question for the format of these objects.
Question
JSON Parameters:
 
  • code (Integer) – (required) Unique code of the question.
  • title (String) – (required) Title of the question, or a short version of the question itself.
  • description (String) – (optional) Description of the question, or a more detailed version of the question itself.
  • isRequired (Boolean) – (required) True if an answer is required for this question.
  • questionType (Object) – (required) Type of question. See Question Types
  • isNotApplicableAllowed (Boolean) – (required) True if the participant can select “Not Applicable” or an equivalent option in his/her answer.
  • maxResponseLength (Integer) – (optional) Maximum response length for questions of type OPEN_RESPONSE
  • items (List[Object]) – (optional) See Item for the format of these objects.
Answer

A survey participant’s response to a particular question.

JSON Parameters:
 
  • questionCode (Integer) – (required) Unique code of the question that is being answered
  • selectedItems (List[Object]) – (optional) List of selected items. For use only with questions of the following types: SCALE, SINGLE_SELECT, and MULTI_SELECT. For a SCALE or SINGLE_SELECT question, this list must have a single item; however, it can have more than one item for a MULTI_SELECT question.
  • text (String) – (optional) Text response of the participant. For use only with OPEN_RESPONSE questions.
  • isNotApplicable (Boolean) – (optional) Whether or not the user selected the “Not Applicable” choice, if the question allows “Not Applicable” responses
Item

An answer choice within a question that the survey participant can select. Items exist for any one of the following question types: SCALE, SINGLE_SELECT, and MULTI_SELECT.

Item objects are used in server responses (for example, to surveyDetails or to surveyDetailsByPrintedCardNumber) and server requests (for example, to submitResponse or to submitResponseByPrintedCardNumber).

When an item is included in a response from the server to a surveyDetails or surveyDetailsByPrintedCardNumber request, there may or may not be a label for the item. For example, it would be common in a SCALE-type question (such as a 1-5 rating question) to omit interior labels (say, for choices 2-4) in favor of displaying only terminal labels (for 1 and 5 only).

When an item is included in a submitResponse or submitResponseByPrintedCardNumber request, code and value fields must be included, but label does not need to be included.

JSON Parameters:
 
  • code (Integer) – (required) Unique code of the item.
  • label (String) – (optional) Text associated with an answer choice.
  • value (String) – (required) Associated value that accompanies an answer choice.

Question Types

SCALE
“Rating Scale”: Question type where the survey taker must choose one answer choice from a numerical range (1-10, 0-2, etc).
SINGLE_SELECT
“Multiple Choice (Single Answer)”: Question type where the survey taker must choose one of several answer choices. Commonly presented with radio button selectors.
MULTI_SELECT
“Multiple Choice (Multi-Select)”: Question type where the survey taker must choose one or more of several answer choices. Commonly presented with checkbox selectors.
OPEN_RESPONSE
“Paragraph Response”: Question type where the survey taker must provide a text response.

Error Codes

The following are the possible codes and messages that can be returned by the Survey Service.

There are other system-level errors which may be returned which are not documented here.

The caller of the endpoint can use the returned message to display to the end user or, if different wording is desired, can provide their own mapping of code to message.

Code Message
survey.error System error
survey.card_not_found Card not found
survey.user_not_found User not found
survey.not_enabled Surveys not configured
survey.invalid_survey_code Invalid survey code
survey.survey_not_active Survey is not active
survey.user_reached_max_completions User has reached maximum number of survey submissions
survey.not_eligible_for_survey User or card not eligible for survey
survey.survey_ended Survey end date has passed
survey.invalid_answer Invalid answer
survey.answer_not_among_choices Answer not among choices
survey.too_many_items_selected Too many items selected
survey.missing_required_answer Missing required answer
survey.answer_too_long Answer exceeds maximum number of allowed characters
survey.transaction_failed Account adjustment transaction(s) that accompany survey completion failed