How to manage respondent status with server-to-server (S2S) API calls

The Server-to-Server (S2S) API provides a secure, API-driven workflow for managing respondent outcomes (complete, terminate, or overquota) between your survey platform and the Cint Exchange. While respondents still use redirects to move between systems, secure API calls handle all sensitive session data and final status reporting. This significantly limits the risk of issues such as ghost completes and data loss.

Prerequisites:

• An S2S API key provided by your integration consultant.
• security_client_id provided by your integration consultant.
• A target group ID using the security_client_id in the client_id field of your Create target group workflows.

info

• Your S2S API key is separate from your standard JWT/OAuth keys and is only for S2S requests.

• All S2S requests require authentication. You must include the Authorization: <YOUR_S2S_API_KEY> header in all requests.

---

How to validate a respondent upon entry

When a respondent is directed from the Cint Exchange to your survey, your platform must first validate their session using the validate respondent endpoint.

Step 1: Capture the respondent ID (RID)

When a supplier sends a respondent, the Cint Exchange assigns a unique RID (Respondent ID) and embeds it in the entry URL replacing the [%RID%] placeholder.

Example entry URL before and after the RID is populated:

Entry URL example: https://example.com/mysurvey?rid=[%RID%]

[%RID%] is dynamically replaced with a UUID: https://example.com/mysurvey?rid=E9FC9420-810D-4006-BB3F-4101A6D6C815

Once your survey platform receives a respondent, it should do the following:

1. Retrieve the RID from the rid query parameter.
2. Call the validate respondent endpoint.

info

Cint-API-Version: <VERSION> isn't required in the header for S2S calls.

Example cURL request to validate a respondent:

curl -L 'https://s2s.cint.com/fulfillment/respondents/{rid}' \
-H 'Accept: application/json' \
-H 'Authorization: <YOUR_S2S_API_KEY>'

Example successful JSON response, containing the status and the entry link with populated query parameter values:

{
    "id": "E9FC9420-810D-4006-BB3F-4101A6D6C815",
    "status": 1,
    "links": [
        {"href": "https://example.com/mysurvey?rid=12345"}
    ]
}

Step 2: Validate status and the entry link (href)

• Validate that the href URL value is the accurate entry link for the respondent.
• 1 indicates "In Survey/Drop." Allow the respondent to proceed to the survey.
• For all other status values or if the entry link is not accurate, mark for termination and immediately redirect them back to the Cint Exchange.

---

How to return a respondent with a final status

When a respondent completes the survey, your platform must use the update respondent status endpoint to securely transmit the final outcome to the Cint Exchange. This process applies to all statuses (complete, terminate, overquota, security terminate).

Step 1: Determine the S2S status code

Identify the correct S2S code that corresponds to the respondent's outcome.

Cint status definition	S2S code
Complete	5
Screenout	2
Quality Terminate	4
Quota Full	3

info

Note that the validate respondent endpoint has different status codes in the response that correspond to the update respondent status endpoint. You must use the S2S code for the update respondent status endpoint.

Step 2: Update the respondent's status

Call the update respondent status endpoint, including the respondent's RID and the correct S2S code in the request body.

info

status expects the S2S code (the integer value) provided in Step 1, not the Cint status definition.

Request template for updating a respondent's status:

curl -X POST 'https://s2s.cint.com/fulfillment/respondents/transition' \
-H 'Authorization: <YOUR_S2S_API_KEY>' \
-d '{
      "id": "<RID>",
      "status": <YOUR_S2S_CODE>
}'

Example cURL request to mark a respondent as complete:

curl -X POST 'https://s2s.cint.com/fulfillment/respondents/transition' \
-H 'Authorization: <YOUR_S2S_API_KEY>' \
-d '{
      "id": "E9FC9420-810D-4006-BB3F-4101A6D6C815",
      "status": 5
}'

Error responses

If the RID is already in the requested status, the API returns an error instead of HTTP 200 OK. The endpoint returns:

• 404 Not Found when the respondent can't be found.
• 422 Unprocessable Entity when the request can't be processed.

Build your integration to handle both, and don't redirect the respondent until you receive HTTP 200 OK.

Order of operations

You must wait for a success response before redirecting the respondent. The endpoint returns an HTTP 200 OK status once all respondent information updates.

Step 3: Redirect the respondent

Once the API call has successfully registered the respondent status update, redirect the respondent to the following URL, including the RID in the URL.

Redirect URL template and example:

Redirect URL: https://samplicio.us/s/ClientCallBack.aspx?RID=<RID>

Example: https://samplicio.us/s/ClientCallBack.aspx?RID=E9FC9420-810D-4006-BB3F-4101A6D6C815

Note that this URL does not include the respondent status since it was already updated via the API call, so the purpose of the redirect is only to return the respondent to the Cint Exchange.

Post-implementation testing

1. Create a draft target group with the S2S-enabled survey URL for all relevant statuses (e.g., Complete, Screenout, Quality Terminate, and Quota Full).
2. Test each status via the Cint Exchange UI or API and share IDs with the Cint team for verification.
3. Once verified, your integration is complete and active.

warning

Do not set the integration live until S2S testing is successful and respondent statuses are correctly registered in the Cint Exchange.

Using SHA-1

Cint offers SHA-1 HMAC hashing for redirects. You can find examples on implementation at https://hash.lucidhq.engineering/. If you're interested in using this approach, please contact your integration consultant.