Submission Notify Webhook

Description

While the In-bound Redirection in Redirection Page is used to notify us about survey completion (Client-to-Client). Submission Notify Webhook endpoint can be used to mark the final user survey submission status (Server-to-Server). This endpoint allows partners to update the status of a user’s submission to either APPROVED, REJECTED, or AUTO_DISQUALIFIED.

Finish Partner Submission

post

Authorizations

x-api-key

Body

application/json

submissionIdstringRequired

Submission ID given by SIR on signed query params in survey URL

statusstringRequired

Possible values:

• APPROVED
• REJECTED
• AUTO_DISQUALIFIED
• SCREEN_OUT

systemRemarksstringRequired

Possible values:

• APPROVED (we will save empty string in DB for remarks APPROVED, but still need to be sent)
• REJECTED
• SCREEN_OUT
• QUOTA_FULL
• DROP_OFF
• SPEEDSTER
• LAGGERS
• SURVEY_TAKEN

For mapping each of the case please follow this doc: https://docs.google.com/spreadsheets/d/1qj9xu3i0NFlVWPOEetOdUR_ymuuefLOyzYflmtZ3CRI/edit?pli=1&gid=0#gid=0

Responses

200

OK

application/json

400

Bad Request

application/json

404

Not Found

application/json

post

HTTPcURLJavaScriptPython

POST /submission/webhook/partner HTTP/1.1
Host: localhost:3000
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 2

{}

{
  "success": true,
  "trace_id": "string",
  "message": "Submission updated sucessfully.",
  "error": {},
  "result": {},
  "metadata": {}
}

Field Descriptions:

1. submissionId:

   • Type: String

   • Description: Submission ID given by us on signed query parameters in the survey URL. (required)

2. status:

   • Type: String

   • Description: The final status of the submission. (required)

   • Possible values:

     • APPROVED

     • REJECTED

     • AUTO_DISQUALIFIED

3. systemRemarks:

   • Type: String

   • Description: Remarks indicating additional information about the final status. (required)

   • Possible values:

     • APPROVED

     • REJECTED

     • SCREEN_OUT

     • QUOTA_FULL

     • DROP_OFF

     • SPEEDSTER

     • LAGGERS

     • SURVEY_TAKEN

Mapping User Status and Remarks

To provide clear information about the status of user submissions, we include detailed remarks for each submission. Partners can use the following mapping to understand the status in different scenarios:

No	Description	Status	Remarks
1	Survey submission is approved and user eligible to earn rewards (auto approved or manual QC)	APPROVED	APPROVED
2	Survey submission is rejected (auto rejection or manual QC or fail logic in main survey)	REJECTED	REJECTED
3	Survey submission is rejected due to screen out (fail pre-screening) and did not pass to main survey	SCREEN_OUT	SCREEN_OUT
4	Survey quota is full	AUTO_DISQUALIFIED	QUOTA_FULL
5	User join survey but not complete until 30 minutes since join (inactive)	AUTO_DISQUALIFIED	DROP_OFF
6	User fill survey too fast (above max LOI)	AUTO_DISQUALIFIED	SPEEDSTER
7	User fill survey too long (under min LOI)	AUTO_DISQUALIFIED	LAGGERS
8	User attempted to access a survey they have taken previously or duplicate submission with Populix App (edge case)	AUTO_DISQUALIFIED	SURVEY_TAKEN

Response Structure

The API will return a JSON object with details about the status update operation.

Successful Response Example:

{
  "error": {},
  "result": {},
  "message": "Submission updated successfully.",
  "success": true,
  "metadata": {},
  "trace_id": "string"
}

Error Response

If there is an issue with the request, the API will return a relevant error code and message.

Error 400 - Bad Request Example:

{
  "error": {
    "code": "INVALID_STATUS",
    "errors": [],
    "message": "Invalid submission status"
  },
  "result": {},
  "success": false,
  "traceId": "47871349-4147-4e6d-b4de-9397a625dc59"
}

Error 404 - Resource Not Found Example:

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested resource could not be found. Please verify the correctness of identifier."
  },
  "result": {},
  "success": false,
  "trace_id": "47871349-4147-4e6d-b4de-9397a625dc59"
}

Common Error Codes

• 400: Bad request – usually due to invalid parameters (e.g., invalid submission status or missing fields).

• 401: Unauthorized – token missing or invalid.

• 404: Not found – submission not found.

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