Version: 2025-05-27

How to update target group allocations

This guide explains how to configure a target group to receive respondents exclusively from specific suppliers.

Steps to configure supplier allocation

Define your target group's allocations

You will need to define an allocations object that configures:

Which suppliers will be blocked from sending respondents to your survey.
Which specific suppliers you would like to field respondents from, along with the percentage of the total quota you are interested in allocating to that supplier.
The percentage of respondents you are willing to receive from any non-blocked supplier on the open exchange.

Open exchange example
Open and private exchange example

{
    "open_exchange_allocations": {
    "blocked_supplier_ids": [
    "123",
    "456"
    ],
    "exchange_min_percentage": 0,
    "exchange_max_percentage": 100,
    "groups": [
{
    "group_id": "1",
    "group_name": "Test group",
    "min_percentage": 0,
    "max_percentage": 100,
    "supplier_ids": [
    "123",
    "456"
    ]
}
    ]
}
}

{
    "open_exchange_allocations": {
    "blocked_supplier_ids": [
    "123",
    "456"
    ],
    "exchange_min_percentage": 0,
    "exchange_max_percentage": 100,
    "groups": [
{
    "group_id": "1",
    "group_name": "Test group",
    "min_percentage": 0,
    "max_percentage": 100,
    "supplier_ids": [
    "123",
    "456"
    ]
}
    ]
},
    "private_exchange_allocations": {
    "blocked_supplier_ids": [
    "123",
    "456"
    ],
    "groups": [
{
    "group_id": "234",
    "group_name": "Test group",
    "min_percentage": 0,
    "max_percentage": 100,
    "supplier_id": "43"
}
    ]
}
}

You can apply an allocations configuration when creating a new draft target group or by updating an existing one.

Creating a new draft target group

Include the allocations object in the request body to create a target group in draft status

Path parameters:
account_id
project_id

Example request to create a new draft target group:

curl -L 'https://api.cint.com/v1/demand/accounts/{account_id}/projects/{project_id}/target-groups' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
-d '{
  "name": "Test target group",
  "business_unit_id": "<YOUR_BUSINESS_UNIT_ID>",
  "locale": "eng_us",
  "collects_pii": true,
  "study_type_code": "diary",
  "industry_code": "politics",
  "cost_per_interview": {
    "value": "2.7352",
    "currency_code": "USD"
  },
  "client_cost_per_interview_note": {
    "value": "2.7352",
    "currency_code": "USD"
  },
  "project_manager_id": "<YOUR_PROJECT_MANAGER_ID>",
  "client_id": 1234,
  "fielding_specification": {
    "start_at": "2023-01-01T23:00:00.000Z",
    "end_at": "2023-01-01T23:00:00.000Z"
  },
  "filling_goal": 750,
  "expected_length_of_interview_minutes": 1,
  "expected_incidence_rate": 0.05,
  "exclusion": {
    "enabled": true
  },
  "industry_lockout_code": "past_30_days",
  "live_url": "https://example.com/live",
  "test_url": "https://example.com/test",
  "fielding_assistant_assignment": {
    "pricing": {
      "type": "dynamic",
      "total_budget": {
        "value": "2.7352",
        "currency_code": "USD"
      },
      "maximum_cpi": {
        "value": "2.7352",
        "currency_code": "USD"
      },
      "minimum_cpi": {
        "value": "2.7352",
        "currency_code": "USD"
      }
    },
    "quota_overlay": {
      "prevent_overfill": true,
      "balance_fill": true
    },
    "pacing": {
      "type": "linear",
      "increment_interval": "string"
    },
    "soft_launch": {
      "end_at": "2023-01-01T23:00:00.000Z",
      "filling_goal_percentage": 0,
      "demographics_strictness_percentage": 0
    }
  },
  "profile": {
    "drafts": [
      {
        "question_id": 42,
        "quotas_enabled": true,
        "conditions": {
          "object": "range_conditions_details_template",
          "data": [
            {
              "min": 18,
              "max": 24
            },
            {
              "min": 25,
              "max": 35
            },
            {
              "min": 36,
              "max": 45
            }
          ]
        },
        "quotas": {
          "ungrouped": [
            {
              "index": 0,
              "quota_percentage": 40,
              "quota_nominal": 550
            }
          ],
          "grouped": [
            {
              "indexes": [
                1,
                2
              ],
              "name": "Group 1",
              "quota_percentage": 40,
              "quota_nominal": 550
            }
          ]
        }
      }
    ]
  },
  "allocations": {
    "open_exchange_allocations": {
      "blocked_supplier_ids": [
        "123",
        "456"
      ],
      "exchange_min_percentage": 0,
      "exchange_max_percentage": 100,
      "groups": [
        {
          "group_name": "Open group 1",
          "min_percentage": 0,
          "max_percentage": 100,
          "suppliers": [
            "123",
            "456"
          ]
        }
      ]
    },
    "private_exchange_allocations": {
      "blocked_supplier_ids": [
        "123",
        "456"
      ],
      "groups": [
        {
          "group_name": "Private group 1",
          "min_percentage": 0,
          "max_percentage": 100,
          "supplier_id": "123"
        }
      ]
    }
  },
  "re_entry_configuration": {
    "completes": {
      "client_side": {
        "allow_for_current_target_group": true,
        "allow_for_other_target_groups": true
      }
    },
    "pre_client_survey_processes": {
      "screener_side": {
        "allow_for_current_target_group": true,
        "allow_for_other_target_groups": true
      }
    },
    "financial_terms": {
      "screener_side": {
        "allow_for_current_target_group": true,
        "allow_for_other_target_groups": true
      }
    },
    "terminates": {
      "client_side": {
        "allow_for_current_target_group": true,
        "allow_for_other_target_groups": true
      },
      "screener_side": {
        "allow_for_current_target_group": true,
        "allow_for_other_target_groups": true
      }
    },
    "security_failures": {
      "client_side": {
        "allow_for_current_target_group": true,
        "allow_for_other_target_groups": true
      },
      "screener_side": {
        "allow_for_current_target_group": true,
        "allow_for_other_target_groups": true
      }
    },
    "overquota": {
      "client_side": {
        "allow_for_current_target_group": true,
        "allow_for_other_target_groups": true
      },
      "screener_side": {
        "allow_for_current_target_group": true,
        "allow_for_other_target_groups": true
      }
    },
    "in_screener": {
      "client_side": {
        "allow_for_current_target_group": true,
        "allow_for_other_target_groups": true
      },
      "screener_side": {
        "allow_for_current_target_group": true,
        "allow_for_other_target_groups": true
      }
    }
  },
  "target_group_customer_reference_number": "AB-00246246"
}'

A successful response returns an HTTP 201 Created status code and a response body containing the ID of the new target group.

Updating an existing target group

You can utilize the update target group allocations endpoint to update a target group that has been launched.

note

The update target group allocations endpoint can only be used for launched target groups.

Path parameters:
account_id
project_id
target_group_id

Example request to update an existing target group:

curl -L -X PUT 'https://api.cint.com/v1/demand/accounts/{account_id}/projects/{project_id}/target-groups/{target_group_id}/allocation-specification' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
-H 'Cint-API-Version: 2025-05-27' \
-d '{
  "open_exchange_allocations": {
    "blocked_supplier_ids": [
      "123",
      "456"
    ],
    "exchange_min_percentage": 0,
    "exchange_max_percentage": 100,
    "groups": [
      {
        "group_id": "1",
        "group_name": "Test group",
        "min_percentage": 0,
        "max_percentage": 100,
        "supplier_ids": [
          "123",
          "456"
        ]
      }
    ]
  },
  "private_exchange_allocations": {
    "blocked_supplier_ids": [
      "123",
      "456"
    ],
    "groups": [
      {
        "group_id": "234",
        "group_name": "Test group",
        "min_percentage": 0,
        "max_percentage": 100,
        "supplier_id": "43"
      }
    ]
  }
}'

A success response includes an HTTP status 204.

Optional: Verify supply allocation settings

Confirm your allocations settings are correct by calling retrieve target group allocations endpoint:

note

The retrieve target group allocations endpoint can only be used for launched target groups.

Path parameters:
account_id
project_id
target_group_id

Example request to verify supply allocation settings:

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

The response should reflect the latest allocation(s):

{
  "open_exchange_allocations": {
    "blocked_supplier_ids": [
      "123",
      "456"
    ],
    "exchange_min_percentage": 0,
    "exchange_max_percentage": 100,
    "groups": [
      {
        "group_id": "1",
        "group_name": "Test group",
        "min_percentage": 0,
        "max_percentage": 100,
        "supplier_ids": [
          "123",
          "456"
        ]
      }
    ]
  },
  "private_exchange_allocations": {
    "blocked_supplier_ids": [
      "123",
      "456"
    ],
    "groups": [
      {
        "group_id": "234",
        "group_name": "Test group",
        "min_percentage": 0,
        "max_percentage": 100,
        "supplier_id": "43"
      }
    ]
  }
}

Steps to configure supplier allocation​

Define your target group's allocations​

Creating a new draft target group​

Updating an existing target group​

Optional: Verify supply allocation settings​

Steps to configure supplier allocation

Define your target group's allocations

Creating a new draft target group

Updating an existing target group

Optional: Verify supply allocation settings