Version: 2025-12-18

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 one identifier per line (no header row). Supported identifier types are Respondent IDs (RSIDs) or Response IDs (RIDs).

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%]

Recontact with profiles

The profiling field is optional. If you want to target specific segments within your recontact list, you can add it to apply demographic, behavioral, or other profile-based filters. Otherwise, simply omit the field.

For more information on profiles, see Profiles overview.

Global allocations template

Recontact target groups must use the Recontact global allocations template. When creating or updating the target group, set allocations.template_id to the recontact template ID:

{
  "allocations": {
    "template_id": "01JH0PEGPC4Z8RDD304E2SF0EW"
  }
}

Completes validation

The completes_goal (number of requested completes) must be equal to or fewer than the number of uploaded Respondent IDs. For example, if you upload 500 IDs, you cannot set completes_goal higher than 500.

Exclusions for same-project recontacts

If you are recontacting respondents within the same project, you should explicitly disable exclusions for your Recontact target group by setting exclusion.enabled to false. Otherwise, project-level exclusions may prevent your recontacted respondents from entering the survey.

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

2. Upload recontact opportunities

Upload a file containing respondent identifiers to create recontact opportunities for the target group. You can upload a file with Respondent IDs (RSIDs) or Response IDs (RIDs).

Call the upload recontact opportunities by file endpoint:

Path Parameters:
- account_id
- project_id
- target_group_id
Query Parameters:
- entity_type (required) — The type of identifiers in your file:
  - RSID or RESPONDENT_ID for Respondent IDs
  - RID or RESPONSE_ID for Response IDs

curl -L -X POST 'https://api.cint.com/v1/demand/accounts/{account_id}/projects/{project_id}/target-groups/{target_group_id}/recontacts/jobs/upload-respondents-by-file?entity_type=RSID' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
-H 'Cint-API-Version: 2025-12-18' \
-F 'file=@respondents.csv'

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, a 409 Conflict error will be returned.

File requirements

The file must be in .csv or .txt format.
The file must not contain a header row.
Each line must contain a single identifier.
Only one file can be uploaded per job.
The file size must be less than 5 MB.
The total number of IDs (existing plus new) cannot exceed 100,000.
If Response IDs are uploaded, they are internally mapped and saved as Respondent IDs.

3. Check the status of your upload job

Call the get upload-by-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-respondents-by-file/{job_id}' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
-H 'Cint-API-Version: 2025-12-18'

Poll this endpoint periodically until the status field changes from Processing to either Completed or Failed.

Example response (completed with partial success):

{
  "job_id": "01BTGNYV6HRNK8K8VKZASZCFP1",
  "created_at": "2025-01-01T14:05:05Z",
  "completed_at": "2025-01-01T14:15:10Z",
  "status": "Completed",
  "created_by": "b551326b-ac9d-4d32-8823-4f025787dab9",
  "failure_reason": null,
  "partial_success_reason": {
    "description": "Upload partially successful. 500 respondent IDs uploaded successfully, 10 failed (invalid or empty)."
  },
  "job_trace_id": null
}

important

Partial successes are possible, meaning some IDs were processed successfully and others were not. If resubmitting, make sure to resubmit a file that only contains the IDs that failed 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-12-18'

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-12-18'

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": null,
  "job_trace_id": null
}

Managing upload jobs

List all upload jobs

You can retrieve a paginated list of all upload-by-file jobs for a target group.

Call the list upload jobs endpoint:

Path Parameters:
- account_id
- project_id
- target_group_id
Query Parameters (optional):
- page_size — Number of results per page (1–1000, default: 1000)
- start_after — Pagination cursor from a previous response's next_cursor value

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

Example response:

{
  "data": [
    {
      "job_id": "01BTGNYV6HRNK8K8VKZASZCFP1",
      "file_name": "respondents.csv",
      "status": "Completed",
      "created_at": "2025-01-02T10:30:00Z",
      "created_by": "b551326b-ac9d-4d32-8823-4f025787dab9"
    },
    {
      "job_id": "01BTGNYV6HRNK8K8VKZASZCFP2",
      "file_name": "recontacts-batch2.txt",
      "status": "Processing",
      "created_at": "2025-01-01T14:05:05Z",
      "created_by": "b551326b-ac9d-4d32-8823-4f025787dab9"
    }
  ],
  "next_cursor": "MDFKUkc0UFdISDRKMEpWRVRTTTNKTlZKWlc"
}

Results are sorted by creation date in descending order (most recent first). To fetch the next page, pass the next_cursor value as the start_after query parameter.

note

A page may contain fewer than page_size items even when more pages exist. Always check the next_cursor field to determine whether additional pages are available.

Download an uploaded file

You can download the original file that was uploaded for a specific recontact job. This is useful for auditing or resubmitting a corrected version of a previous upload.

Call the download upload job file endpoint:

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-respondents-by-file/{job_id}/download' \
-H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
-H 'Cint-API-Version: 2025-12-18' \
--output downloaded-respondents.csv

The response is returned as a binary file attachment. The Content-Disposition header contains the filename, which is derived from the original file name provided at upload time.

Troubleshooting

Job status isn't changing: Job processing time depends on the number of identifiers. While execution time may vary, storing 10,000 new respondents typically takes between 10 and 15 minutes, and removing 10,000 respondents typically takes between 3 and 5 minutes.
404 Not Found: Check that the IDs in the path parameters are correct and that the resource exists.
400 Bad Request: This may indicate that your request is malformed or your file is in the wrong format. For file size limit violations, see 413 Content 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. Wait for the current job to complete before starting a new one.
413 Content Too Large: The uploaded file exceeds the 5 MB size limit.
415 Unsupported Media Type: The request is not a valid multipart upload. Use curl -F 'file=@yourfile.csv' to let curl set the Content-Type: multipart/form-data header with the required boundary parameter automatically. Manually setting the header without a correct boundary will also trigger this error.

Steps to recontact respondents​

1. Create a draft target group​

2. Upload recontact opportunities​

3. Check the status of your upload job​

4. Launch the target group​

Removing recontact opportunities​

1: Remove all respondent IDs from the target group​

2. Check the removal job status​

Managing upload jobs​

List all upload jobs​

Download an uploaded file​

Troubleshooting​

Steps to recontact respondents

1. Create a draft target group

2. Upload recontact opportunities

3. Check the status of your upload job

4. Launch the target group

Removing recontact opportunities

1: Remove all respondent IDs from the target group

2. Check the removal job status

Managing upload jobs

List all upload jobs

Download an uploaded file

Troubleshooting