Skip to main content
Version: 2025-05-27

How to recontact respondents from participating in a target group

This guide explains how to create, configure, and launch a target group specifically designed for recontacting a pre-defined list of respondents.

Recontact surveys enable you to:

  • Conduct longitudinal studies by surveying the same individuals over time
  • Perform follow-up research based on previous survey participation
  • Target highly specific segments from your prior research
  • Ensure data consistency and track changes within your respondent pool

Prerequisites:

  • You have an existing project.
  • You have a respondent file. This must be a .txt or .csv file containing a list of comma-separated respondent RSIDs.

Steps to recontact respondents​

1. Create a draft target group​

Create a new target group in draft status following the standard Create a target group process, but with one key difference: set study_type_code to "recontact".

{
  "study_type_code": "recontact",
  // ... other standard target group fields
}
URL requirements

For recontact target groups, the live_url and test_url fields must contain the [%RECONTACT_RSID%] variable. This variable allows the system to identify recontacted respondents.

Example:

https://your-survey.com?RID=[%RID%]&RECONTACT_RSID=[%RECONTACT_RSID%]
note

In API version 2025-05-27, the profile field is required. To create a recontact target group without profiles, you must send the field with empty arrays:

{
  // ... other standard target group fields
  "profile": {
    "profile_adjustment_type": "percentage",
    "drafts": []
  }
}
Recontact with profiles

You can add profile data to target specific segments within your recontact list. This allows you to apply demographic, behavioral, or other profile-based filters to your recontact audience.

For more information on profiles, see Understanding profiles.

A successful request returns a 201 HTTP status code and a JSON response containing the target_group_id.

2. Upload recontact opportunities​

Call the upload recontact opportunities endpoint:

  • Path Parameters:
    • account_id
    • project_id
    • target_group_id
curl -L -X POST 'https://api.cint.com/v1/demand/accounts/{account_id}/projects/{project_id}/target-groups/{target_group_id}/recontacts/jobs/upload-rsids-by-file' \
-H 'Content-Type: multipart/form-data' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
-H 'Cint-API-Version: 2025-05-27'

A successful request returns a 201 HTTP status code and a JSON response that contains a job_id.

{
  "job_id": "01BTGNYV6HRNK8K8VKZASZCFP1"
}
note

While this endpoint responds synchronously the upload process is asynchronous, meaning the job will complete in the future. Only one job can run at a time for a target group. If another job is already running before the endpoint is called for the same target group, an error will be returned.

3. Check the status of your upload job​

Call the get upload file job status endpoint to check the status of the job using the job_id:

  • Path Parameters:
    • account_id
    • project_id
    • target_group_id
    • job_id
curl -L 'https://api.cint.com/v1/demand/accounts/{account_id}/projects/{project_id}/target-groups/{target_group_id}/recontacts/jobs/upload-rsids-by-file/{job_id}' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
-H 'Cint-API-Version: 2025-05-27'

A successful job will have the status of Success.

{
  "job_id": "01BTGNYV6HRNK8K8VKZASZCFP1",
  "created_at": "2025-01-01T23:00:00.000Z",
  "completed_at": "2025-01-01T23:00:00.000Z",
  "status": [
    "Completed"
  ],
  "created_by": "b551326b-ac9d-4d32-8823-4f025787dab9",
  "failure_reason": {
    "code": "JobExecutionStartMessageFailed",
    "description": "The job execution start message failed. Please contact Cint for further assistance."
  },
  "partial_success_reason": {
    "description": "Upload partially successful. 500 respondent IDs uploaded successfully, 10 failed (invalid or empty)."
  },
  "job_trace_id": "0af7651916cd43dd8448eb211c80319c"
}
important

Partial successes are possible, meaning one or more IDs supplied have been successfully processed and some have not been. If resubmitting, make sure to resubmit that only contain the IDs that failed to apply so you don't do unnecessary work.

4. Launch the target group​

Once your recontact opportunities are uploaded, launch the target group to make it live on the Exchange.

Follow the standard Launch a target group process to transition your target group from draft to live.

When the launch job status is succeeded, your target group is live on the Exchange and ready to collect responses from the respondents in your RSID list.

Removing recontact opportunities​

important

In order to remove a recontact opportunity, you have to remove all recontact opportunities for a given target group. You can add them back in step 2.

1. Remove all respondent IDs from the target group​

Call the remove all recontact opportunities endpoint:

  • Path Parameters:
    • account_id
    • project_id
    • target_group_id
curl -L -X POST 'https://api.cint.com/v1/demand/accounts/{account_id}/projects/{project_id}/target-groups/{target_group_id}/recontacts/jobs/remove-all-rsids' \
-H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
-H 'Cint-API-Version: 2025-05-27'

A successful request returns a 201 HTTP status code and a JSON response that contains a job_id.

{
  "job_id": "01BTGNYV6HRNK8K8VKZASZCFP1"
}
note

While this endpoint responds synchronously the file processing is asynchronous, meaning the job will complete in the future. Only one job can run at a time for a target group. If another job is already running before the endpoint is called for the same target group, an error will be returned.

2. Check the removal job status​

Call the remove all rsids job status endpoint to check the status of the removal job:

  • Path Parameters:
    • account_id
    • project_id
    • target_group_id
    • job_id
curl -L 'https://api.cint.com/v1/demand/accounts/{account_id}/projects/{project_id}/target-groups/{target_group_id}/recontacts/jobs/remove-all-rsids/{job_id}' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
-H 'Cint-API-Version: 2025-05-27'

A successful response will inform you of the status and if a failure happened, the reason:

{
  "job_id": "01BTGNYV6HRNK8K8VKZASZCFP1",
  "created_at": "2025-01-01T23:00:00.000Z",
  "completed_at": "2025-01-01T23:00:00.000Z",
  "status": "Completed",
  "created_by": "b551326b-ac9d-4d32-8823-4f025787dab9",
  "failure_reason": {
    "code": "JobExecutionStartMessageFailed",
    "description": "The job execution start message failed. Please contact Cint for further assistance."
  },
  "job_trace_id": "0af7651916cd43dd8448eb211c80319c"
}

Troubleshooting​

  • Job status isn't changing: Job processing time depends on the size of the exclusion file. For large files, this may take several minutes. For example, While execution time may vary, storing 10,000 new respondents typically takes between 3 and 5 minutes.
  • 404 Bad Request: Check that the IDs located in the path and body are correct.
  • 400 Bad Request: This may indicate that your request is malformed, your file is in the wrong format or too large.
  • 401 Unauthorized: Your token is either missing, invalid, or expired.
  • 403 Forbidden: You don't have the necessary permissions to perform this action.
  • 409 Conflict: Another job is already running for this target group.