Check Respondent Availability

Description

Check Respondent Availability endpoint is designed to verify the availability of a specific respondent for a given criteria before launch the survey. This endpoint helps survey administrators ensure that potential participants are available and willing to partake in the survey at a specified time, thereby optimizing scheduling and improving response rates.

Check Respondent Availability

post

Authorizations

x-api-key

x-api-keystringRequired

Body

application/json

blacklistEmailsstring[]Optional

whitelistEmailsstring[]Optional

Responses

200

OK

application/json

successbooleanOptional

traceIdstringOptional

messagestringOptional

errorobjectOptional

resultobjectOptional

metadataobjectOptional

400

Bad Request

application/json

post

/user/respondent/availability

HTTPcURLJavaScriptPython

POST /user/respondent/availability HTTP/1.1
Host: localhost:3000
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 362

{
  "criteria": {
    "gender": [
      "Male",
      "Female"
    ],
    "ageMin": 18,
    "ageMax": 50,
    "domicile": {
      "province": [
        "Jawa Timur",
        "Jawa Barat"
      ],
      "city": [
        "string1",
        "string2"
      ],
      "district": [
        "string1",
        "string2"
      ],
      "subdistrict": [
        "string1",
        "string2"
      ],
      "postalCode": [
        "string1",
        "string2"
      ]
    },
    "SES": [
      "string1",
      "string2"
    ]
  },
  "blacklistEmails": [
    "[email protected]"
  ],
  "whitelistEmails": [
    "[email protected]"
  ]
}

{
  "status": true,
  "trace_id": "string",
  "message": "string",
  "error": {},
  "result": {
    "totalRespondents": 100
  },
  "metadata": {}
}

Field Descriptions:

1. criteria:

   • Type: Object

   • Description: You can sent only the required criteria to find the total respondent. At least one criteria is required.

2. gender:

   • Type: Array of strings

   • Description: Accepts values: Male, Female.

3. ageMin:

   • Type: Integer

   • Description: Minimum age of the respondent. If not sent we will set to 0.

4. ageMax:

   • Type: Integer

   • Description: Maximum age of the respondent. If not sent we will set to 100.

5. 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.

     • province: Array of strings representing provinces.

     • city: Array of strings representing cities.

     • district: Array of strings representing districts.

     • subdistrict: Array of strings representing subdistricts.

     • postalCode: Array of strings representing postal codes.

6. SES:

   • Type: Array of strings

   • Description: Socio-Economic Status (SES) of the respondent. Accepts values: Upper, Middle, Lower.

7. blacklistEmails

   1. Type: Array of strings

   2. Description: List of blacklisted email

8. whitelistEmails

   1. Type: Array of strings

   2. Description: List of whitelisted email

Response Structure

The API will return a JSON object indicating the availability of the respondent.

Successful Response Example:

{
  "error": {},
  "result": {
    "totalRespondents": 100
  },
  "status": true,
  "message": "string",
  "metadata": {},
  "trace_id": "string"
}

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": "Criteria",
        "message": "This field is required"
      }
    ],
    "message": "Missing Required Information"
  },
  "result": {},
  "success": false,
  "traceId": "string",
  "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.