Publishing the Survey

Description

The purpose of this endpoint is to publish the survey and distribute it to the Responova Platform, ensuring that the surveys are properly validated, stored, and distributed according to the specified criteria. The process includes handling both basic and additional survey criteria, distributing the survey, and sending notifications as necessary.

Once the survey is published, we will immediately launch and distribute the survey to the users.

Partner Publish Survey

post

Authorizations

Body

surveyIdstringRequired

surveyNamestringRequired

surveyUrlstringRequired

quotaintegerRequired

Quota for SIR Respondent

rewardAmountintegerRequired

lengthOfSurveyintegerOptional

In minutes, if not sent we will set 30 minutes by default

blacklistEmailsstring[]Optional

whitelistEmailsstring[]Optional

Responses

200

OK

application/json

400

Bad Request

application/json

post

HTTPcURLJavaScriptPython

POST /survey/partner/publish HTTP/1.1
Host: localhost:3000
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 520

{
  "surveyId": "string",
  "surveyName": "string",
  "surveyUrl": "string",
  "quota": 100,
  "rewardAmount": 1000,
  "basicCriteria": {
    "gender": [
      "string"
    ],
    "ageMin": 0,
    "ageMax": 0,
    "domicile": {
      "province": [
        "string"
      ],
      "city": [
        "string"
      ],
      "district": [
        "string"
      ],
      "subDistrict": [
        "string"
      ],
      "postalCode": [
        "string"
      ]
    },
    "SES": [
      "string"
    ]
  },
  "additionalCriteria": [
    {
      "criteriaKey": "string",
      "question": "string",
      "type": "string",
      "answerOptions": [
        "string"
      ],
      "expectedAnswer": [
        "string"
      ]
    }
  ],
  "blacklistEmails": [
    "[e-mail]"
  ],
  "whitelistEmails": [
    "[e-mail]"
  ]
}

{
  "success": true,
  "traceId": "string",
  "message": "Survey published succesfully.",
  "error": {},
  "result": {},
  "metadata": {}
}

Field Descriptions:

basicCriteria is required and additionalCriteria is optional. Once we haven't found any available criteria inadditionalCriteria , we will mark it as an additional pre-screening for all the eligible users.

1. surveyId:

   • Type: String

   • Description: Partner survey unique identifier. (required)

2. surveyName:

   • Type: String

   • Description: Partner survey name. (required)

3. surveyUrl:

   • Type: String

   • Description: Partner survey URL. (required)

4. quota:

   • Type: Integer

   • Description: Quota for SIR Respondent. (required)

5. rewardAmount:

   • Type: Integer

   • Description: The amount of reward for completing the survey. (required)

6. basicCriteria:

   • Type: Object

   • Description: Contains the basic filtering criteria for respondents. (required)

   • gender:

     • Type: Array[String]

     • Description: Specifies the allowed genders for respondents. At least one basic attribute is mandatory.

     • Possible values:

       • Female

       • Male

   • ageMin:

     • Type: Integer

     • Description: Minimum age of respondents. At least one basic attribute is mandatory.

   • ageMax:

     • Type: Integer

     • Description: Maximum age of respondents. At least one basic attribute is mandatory.

   • domicile:

     • Type: Object

     • Description: Geographic criteria of the respondent. At least one attribute inside domicile is required if domicile sent. The full list of our valid domicile can be found here.

   • SES:

     • Type: Array[String]

     • Description: Socioeconomic status criteria for respondents. At least one basic attribute is mandatory.

     • Possible value:

       • Upper: We will map it into Upper 1 and Upper 2.

       • Middle: We will map it into Middle 1 and Middle 2.

       • Lower: We will map it into Lower 1 and Lower 2.

7. additionalCriteria:

   • Type: Array[Object]

   • Description: Additional custom filtering criteria for respondents. This attribute needs to be sent if the survey requires additional criteria beyond the basicCriteria. (optional)

   • criteriaKey:

     • Type: String

     • Description: Key for additional filtering criteria. (required if additional criteria exist)

   • question:

     • Type: String

     • Description: The question used to apply the additional filter. (required if additional criteria exist)

   • type:

     • Type: String

     • Description: Specifies the type of additional filtering (e.g., multiple-choice). (required if additional criteria exist)

     • Possible values:

       • DROPDOWN: Single choice option.

       • MULTIPLE_CHOICE: Multiple choice option.

   • answerOptions:

     • Type: Array[String]

     • Description: List of answer options for the additional criteria question. (required if additional criteria exist)

   • expectedAnswer:

     • Type: Array[String]

     • Description: The expected answer(s) for filtering respondents. For DROPDOWN, you need to only sent 1 element of expected answer. (required if additional criteria exist)

8. lengthOfSurvey

   • Type: Integer

   • Description: In minutes, if not sent we will set 30 minutes by default

9. blacklistEmails

   1. Type: Array of strings

   2. Description: List of blacklisted email

10. whitelistEmails

    1. Type: Array of strings

    2. Description: List of whitelisted email

Error Response

If the request encounters an issue, the response will include an error code and message.

Error Example:

Bad Request 400

{
  "error": {
    "code": "INVALID_BODY",
    "errors": [
      {
        "field": "SurveyID",
        "message": "This field is required"
      },
      {
        "field": "SurveyName",
        "message": "This field is required"
      }
    ],
    "message": "Missing Required Information"
  },
  "result": {},
  "success": false,
  "traceId": "8d7d3e7a891e3b3fa17bf867be878143",
  "metadata": {}
}

Common Error Codes:

• 400: Bad request – usually due to invalid parameters.

• 401: Unauthorized – token missing or invalid.

• 404: Not found – respondent not found.

• 500: Internal server error – an issue on the server side.