Skip to main content
Version: 2025-05-27

How to exclude respondents from participating in a target group

This guide explains how to exclude a custom list of specific respondents from participating in a target group by providing their unique IDs. You might need to exclude specific individuals from a survey due to internal company policies, prior participation in very similar studies, or for quality control reasons.

note

This exclusion can apply to respondents regardless of their prior status (e.g., whether they were marked as completed or terminated).

Prerequisites:

  • You have an existing target group.
  • You have a respondent exclusion file. This must be a .txt or .csv file containing a list of comma-separated respondent IDs (either RSID or access respondent ID format). The file size must be less than 5MB, and the number of IDs cannot exceed 100,000.

Steps to exclude respondents​

1. Upload respondent exclusions file​

Call the upload exclusion file endpoint:

  • Path Parameters:

    • account_id
    • project_id
    • target_group_id

  • Query Parameters:

    • entity_type (this can be either RSID, ACCESS_RESPONDENT_GUID)
curl -L -X POST 'https://api.cint.com/v1/demand/accounts/{account_id}/projects/{project_id}/target-groups/{target_group_id}/exclusions/jobs/upload-respondents-by-file' \
-H 'Content-Type: multipart/form-data' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <token>' \
-H 'Cint-API-Version: 2025-05-27'

A successful request returns a 202 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.

2. Check the status of your 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}/exclusions/jobs/upload-respondents-by-file/{job_id}' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <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": [
    "Success"
  ],
  "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 a file that only contain the IDs that failed to apply so you don't do unnecessary work.

There are endpoints based on the entity_type of the IDs from your request:

Removing excluded respondents from the exclusion list​

important

In order to remove a previously added exclusion, you have to remove all exclusions for a given target group. You can add them back in step 1.

1: Remove all exclusions from a target group​

Call the remove exclusion respondents from a target group endpoint:

  • Path Parameters:

    • account_id
    • project_id
    • target_group_id

  • Query Parameters:

    • entity_type (this can be either RSID, ACCESS_RESPONDENT_GUID)
curl -L -X POST 'https://api.cint.com/v1/demand/accounts/{account_id}/projects/{project_id}/target-groups/{target_group_id}/exclusions/jobs/exclusion-create-remove-all-respondents-job' \
-H 'Content-Type: multipart/form-data' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <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 status of your job​

Call the remove all exclusions job status endpoint to check the status of your previous request 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}/exclusions/jobs/remove-all-respondents/{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"
}

Retrieve the current number of excluded respondents​

At any time, call the get exclusions overview endpoint to get insight on the number of respondents that have been excluded.

note

The total number of IDs, both existing and new, must not exceed 100,000 IDs.

  • Path Parameters:
  • account_id
  • project_id
  • target_group_id
curl -L 'https://api.cint.com/v1/demand/accounts/:account_id/projects/:project_id/target-groups/:target_group_id/exclusions/overview' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <YOUR_JWT_TOKEN>'
-H 'Cint-API-Version: 2025-05-27'

A successful response contains the statistics for each entity type:

{
  "saved_respondent_ids_count": 1000,
  "saved_access_respondent_guids_count": 1000
}

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, Processing 10,000 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.