How to exclude respondents based on their past activity

This guide shows you how to configure a target group to exclude respondents based on their past interactions with previous surveys you've fielded. By default, exclusions apply to respondents who completed a related target group — including target groups in the projects you list — but you can also target other respondent statuses, such as screenouts and over-quota terminations.

info

To learn about respondent activity exclusions and respondent exclusions in general, see respondent exclusions in the deep dives section.

Prerequisites:

• You have an existing target group.
• You have a list of projects and target group IDs that have fielded respondents whom you'd like to exclude from your current survey.

Step 1: Provide the IDs of Projects and Target Groups you want to exclude

Call Set respondent activity exclusions endpoint with your IDs to exclude. The exclusion list in your request fully replaces the current list of IDs. Always include every project and target group you want to exclude in each request, not just additions:

tip

Think of each request as setting the complete list, not appending to it. If you omit an existing ID, it will be removed.

You can configure the exclusion duration at two levels:

• Request-level duration: Sets a default exclusion period for all items in the request that do not specify their own duration. If omitted, items without an explicit duration default to 90 days (P90D).
• Item-level duration: Overrides the request-level default for that specific item.

Both fields are optional and use the ISO-8601 period format (e.g. P30D for 30 days, P3M for 3 months). Allowed values are between 1 and 396 days.

note

Month-based periods (e.g., P1M, P3M) are calendar-aware and adjust to the last valid day of the resulting month. For example, looking back one month from March 31 results in February 28 (or February 29 in a leap year).

{
  "duration": "P60D",
  "respondent_activity_exclusions": [
    {
      "type": "project",
      "id": "01HF6ZBAYT1M9N8EJX2Z3K1P7V"
    },
    {
      "type": "project",
      "id": "01KPB67PGC09BRYFPRPK67N63G"
    },
    {
      "type": "target-group",
      "id": "01HF6ZDW9J3X7H5T4R9C6M1Q2A",
      "duration": "P120D"
    }
  ]
}

In this example, the request-level duration is set to P60D, so both project exclusions inherit the 60-day period. The target group exclusion specifies its own duration of P120D, which overrides the request-level default.

Choose which respondent statuses to exclude (optional)

By default, respondent activity exclusions apply to respondents who reached a Complete status in the projects and target groups you list. You can optionally target additional respondent statuses, such as screenouts or over-quota terminations, by adding a respondent_statuses array to any item.

Because each item carries its own respondent_statuses and duration, you can apply different exclusion windows to different statuses for the same source. To do this, list the same type and id more than once, giving each entry its own set of statuses and duration:

Example request body: block completes for 90 days, and screenouts and over-quota respondents for 14 days

{
  "respondent_activity_exclusions": [
    {
      "type": "project",
      "id": "01KGEYS73VB65016EYR76BWMTP",
      "duration": "P90D",
      "respondent_statuses": ["Complete"]
    },
    {
      "type": "project",
      "id": "01KGEYS73VB65016EYR76BWMTP",
      "duration": "P14D",
      "respondent_statuses": ["Terminate", "OverQuota"]
    }
  ]
}

Each entry is evaluated independently. A respondent is blocked if any matching entry finds one of its statuses in their history within that entry's duration. When you omit respondent_statuses, the item defaults to ["Complete"], which preserves the original behavior.

Supported respondent statuses

Respondent status	Meaning
Complete	The respondent reached and submitted the client survey.
Terminate	The respondent was screened out, or terminated, during the survey.
OverQuota	The respondent was turned away because a relevant quota was already full.
SecurityFailure	The respondent was blocked by fraud or security checks.
FinancialTerm	The respondent's session ended in a financial termination.
PreClientSurveyProcess	The respondent did not reach the client survey, ending during pre-survey processing.

important

Targeting any status other than Complete requires your account to have access to this feature. If your account doesn't have access, a request that includes other statuses is rejected with HTTP 400 Bad Request and the message Not allowed to use respondent_statuses other than 'Complete'. Contact your Cint account manager to have it enabled.

A few validation rules apply to respondent_statuses:

• If you include the field, it must contain at least one status, and each status must be unique.
• For a given type and id, each respondent status and each duration can appear in only one entry.
• An unrecognized status value is rejected with HTTP 400 Bad Request.

warning

If the target group is already live, updating its respondent activity exclusions will only affect future respondent traffic. Any respondents who have already entered or completed the target group under the previous exclusion settings cannot be retroactively changed. Please review your changes carefully before applying them to a live target group.

To remove all respondent exclusions from a target group, send an empty array:

{
  "respondent_activity_exclusions": []
}

Step 2: Review the response

Use the Retrieve respondent activity exclusions endpoint to get the full list of projects and target groups currently configured for your source target group.

The response will be similar to the request, including the duration and respondent_statuses fields per element in the list, reflecting the configured or default values. Items you saved without an explicit respondent_statuses are returned as ["Complete"], so the effective behavior is always explicit:

{
  "respondent_activity_exclusions": [
    {
      "type": "target-group",
      "id": "01KH2714RHRTGCGQV47FHHY8S8",
      "duration": "P60D",
      "respondent_statuses": ["Complete"]
    },
    {
      "type": "project",
      "id": "01KH287TE2W1GKTJJ91QCCHWP9",
      "duration": "P90D",
      "respondent_statuses": ["Terminate", "OverQuota"]
    }
  ]
}

After an ID's duration expires, respondents will no longer be excluded for that item.

Step 3: Update respondent exclusions (optional)

The process to update respondent activity exclusions is the same as setting the values shown in step one.

Troubleshooting

• HTTP 400 Bad Request: Double-check your list of IDs to ensure they are valid and your project and target group you are actively manipulating isn't in the list.
• Ensure all included target groups and projects are included in the array on every update call. Once saved the previous list of IDs are deleted.
• 401 Unauthorized: Your token is either missing, invalid, or expired.
• 403 Forbidden: You don't have the necessary permissions to perform this action.