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, Overquota) between your survey platform and the Cint Exchange. While respondents still use redirects to move between systems, all sensitive session data and final status reporting are handled through secure API calls. This significantly limits the risk of issues such as ghost completes and data loss.

Prerequisites

• An S2S API key provided by your Integration Consultant.

info

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

• Client ID, provided by your integration consultant.
• Target group ID.

info

All S2S requests require authentication. You must include Authorization: <YOUR_API_KEY> header parameter 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 (e.g., replacing a [%RID%] placeholder).

// [%RID%] has veen 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. Make an API call to the validate respondent endpoint:

info

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

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

A successful JSON response body contains the status and entry link with populated query parameter values:

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

validate status and the entry link (href)

• Validate that 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	10
Terminate	20
Security Terminate	30
Overquota	40

Legacy Cint status codes can be used as well.

Step 2: Update the respondent's status

Call to 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), not the Cint status definition.

curl -X POST 'https://s2s.cint.com/fulfillment/respondents/transition' \
-H 'Content-Type: application/json' \
-H 'Authorization: YOUR_API_KEY' \
-d '{
      "id": "<RID>",
      "status": <YOUR_S2S_Code>
}

Step 3: Redirect the respondent

A successful response confirms the respondent's status has been successfully updated on the Cint Exchange. After receiving the successful response, redirect the respondent.

---

Redirect respondents

Use the following generic URL to redirect respondent's back to the Cint Exchange:

curl 'https://samplicio.us/s/ClientCallBack.aspx?RID={rid}' \
-H 'Content-Type: application/json' \
-H 'Authorization: YOUR_API_KEY'

Legacy Cint Status Codes

For legacy Cint customers, the legacy Cint status definitions and their corresponding codes will as the status for.

Legacy Cint Status Definition	S2S Code
Complete	5
Terminate	2
Security Terminate	4
Overquota	3