Survey Service ============== The survey service provides endpoints to request survey content and provide responses to survey questions. .. contents:: Topics Endpoints --------- Get Eligible Surveys by Username ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http: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: * :ref:`b2b_auth` * :ref:`oauth_auth` :query Integer merchantId: *(required)* Paytronix-assigned merchant identifier (ID) in which to perform the operation. :query String username: *(required)* Username associated with the account for which to obtain eligible surveys. .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam List[Object] surveys: *(required)* The list of surveys in which the user is eligible to participate. See :http:jsonentity:`EligibleSurvey` for the format of these objects. .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The human readable error message of the failure. Get Eligible Surveys by Printed Card Number ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http: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: * :ref:`b2b_auth` * :ref:`oauth_auth` :query Integer merchantId: *(required)* Paytronix-assigned merchant identifier (ID) in which to perform the operation. :query String printedCardNumber: *(required)* Printed card number associated with the account for which to obtain eligible surveys. .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam List[Object] surveys: *(required)* The list of surveys in which the user is eligible to participate. See :http:jsonentity:`EligibleSurvey` for the format of these objects. .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The human readable error message of the failure. Opt In To Survey by Username ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http: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: * :ref:`b2b_auth` * :ref:`oauth_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant identifier (ID) in which to perform the operation. :jsonparam String username: *(required)* Username of the participant who is being entered into the survey. :jsonparam String code: *(required)* Code of the specific survey to which the participant is being entered. This information is configured and visible in the Paytronix Survey Center. :jsonparam Integer daysAvailableToComplete: *(optional)* Number of days the participant has to complete the survey before the survey becomes inactive. :jsonparam Long optInTransactionRequestDetailId: *(optional)* ID of the transaction that caused the participant to be entered into the survey. :jsonparam Integer campaignOccurrenceId: *(optional)* ID of the campaign occurrence that caused the participant to be entered into the survey. .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam String username: *(required)* Username for the participant who was entered into the survey. :jsonparam String code: *(required)* Code of the specific survey to which the participant was entered. :jsonparam String optedInDateTime: *(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`` .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The human readable error message of the failure. Opt In To Survey by Printed Card Number ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http: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: * :ref:`b2b_auth` * :ref:`oauth_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant identifier (ID) in which to perform the operation. :jsonparam String printedCardNumber: *(required)* Printed card number for the participant who is being entered into the survey. :jsonparam String code: *(required)* Code of the specific survey to which the participant is being entered. This information is configured and visible in the Paytronix Survey Center. :jsonparam Integer daysAvailableToComplete: *(optional)* Number of days the participant has to complete the survey before the survey becomes inactive. :jsonparam Long optInTransactionRequestDetailId: *(optional)* ID of the transaction that caused the participant to be entered into the survey. :jsonparam Integer campaignOccurrenceId: *(optional)* ID of the campaign occurrence that caused the participant to be entered into the survey. .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam String username: *(required)* Username for the participant who was entered into the survey. :jsonparam String code: *(required)* Code of the specific survey to which the participant was entered. :jsonparam String optedInDateTime: *(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`` .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The human readable error message of the failure. Get Survey Details by Username ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http:get:: survey/surveyDetails.json Obtains the details (content) of a specific survey by username. The following authentication methods are allowed for this endpoint: * :ref:`b2b_auth` * :ref:`oauth_auth` :query Integer merchantId: *(required)* Paytronix-assigned merchant identifier (ID) in which to perform the operation. :query String username: *(required)* Username of the participant who is requesting the survey details. :query String code: *(required)* Code of the specific survey for which the details are being requested. This information is configured and visible in the Paytronix Survey Center. .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam Object details: *(required)* Content of the survey to provide to the participant. See :http:jsonentity:`Details` for the format of this object. .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The human readable error message of the failure. Get Survey Details by Printed Card Number ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http: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: * :ref:`b2b_auth` * :ref:`oauth_auth` :query Integer merchantId: *(required)* Paytronix-assigned merchant identifier (ID) in which to perform the operation. :query String printedCardNumber: *(required)* Printed card number for the participant who is requesting the survey details. :query String code: *(required)* Code of the specific survey for which the details are being requested. This information is configured and visible in the Paytronix Survey Center. .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam Object details: *(required)* Content of the survey to provide to the participant. See :http:jsonentity:`Details` for the format of this object. .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The human readable error message of the failure. Submit Response to Survey by Username ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http: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: * :ref:`b2b_auth` * :ref:`oauth_auth` * :ref:`guest_user_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant identifier (ID) in which to perform the operation. :jsonparam String username: *(required)* Username of the participant who is submitting the survey response. :jsonparam String code: *(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. :jsonparam List[Object] answers: *(required)* List of answers to specific survey questions. See :http:jsonentity:`SurveyAnswer` for the format of this object. .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam String message: *(required)* Message that can be presented to the survey participant. .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The human readable error message of the failure. :jsonparam List[Integer] errorDetail: *(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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http: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: * :ref:`b2b_auth` * :ref:`oauth_auth` * :ref:`guest_user_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant identifier (ID) in which to perform the operation. :jsonparam String printedCardNumber: *(required)* Printed card number for the participant who is submitting the survey response. :jsonparam String code: *(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. :jsonparam List[Object] answers: *(required)* List of answers to specific survey questions. See :http:jsonentity:`SurveyAnswer` for the format of this object. .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam String message: *(required)* Message that can be presented to the survey participant. .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The human readable error message of the failure. :jsonparam List[Integer] errorDetail: *(optional)* List of question codes for errors that were specific to those questions, such as an invalid answer choice. Reply Objects ------------- .. http:jsonentity:: EligibleSurvey Information about a survey that a participant is eligible to complete. :jsonparam String code: *(required)* Unique code of the survey. :jsonparam String optedInDatetime: *(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`` :jsonparam String expirationDatetime: *(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`` .. http:jsonentity:: Details More detailed information about a survey that a participant is eligible to complete, including the actual content of the survey questions. :jsonparam String code: *(required)* Unique code of the survey. :jsonparam String title: *(required)* Title of the survey. :jsonparam String description: *(optional)* Description of the survey. :jsonparam String startDatetime: *(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`` :jsonparam String expirationDatetime: *(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`` :jsonparam List[Object] questions: *(required)* Questions to be presented to the participant. See :http:jsonentity:`Question` for the format of these objects. .. http:jsonentity:: Question :jsonparam Integer code: *(required)* Unique code of the question. :jsonparam String title: *(required)* Title of the question, or a short version of the question itself. :jsonparam String description: *(optional)* Description of the question, or a more detailed version of the question itself. :jsonparam Boolean isRequired: *(required)* True if an answer is required for this question. :jsonparam Object questionType: *(required)* Type of question. See :ref:`question_types` :jsonparam Boolean isNotApplicableAllowed: *(required)* True if the participant can select "Not Applicable" or an equivalent option in his/her answer. :jsonparam Integer maxResponseLength: *(optional)* Maximum response length for questions of type ``OPEN_RESPONSE`` :jsonparam List[Object] items: *(optional)* See :http:jsonentity:`Item` for the format of these objects. .. http:jsonentity:: Answer A survey participant's response to a particular question. :jsonparam Integer questionCode: *(required)* Unique code of the question that is being answered :jsonparam List[Object] selectedItems: *(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. :jsonparam String text: *(optional)* Text response of the participant. For use only with ``OPEN_RESPONSE`` questions. :jsonparam Boolean isNotApplicable: *(optional)* Whether or not the user selected the "Not Applicable" choice, if the question allows "Not Applicable" responses .. http:jsonentity:: 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. :jsonparam Integer code: *(required)* Unique code of the item. :jsonparam String label: *(optional)* Text associated with an answer choice. :jsonparam String value: *(required)* Associated value that accompanies an answer choice. .. _question_types: 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 | +---------------------------------------------------+-------------------------------------------------------------------------------------------+