Skip to main content
Version: 2025-12-18

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_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"
    ]
}
    ]
}
}

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
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 <token>' \
-d '{
  "name": "Test target group",
  "business_unit_id": "<BUSINESS_UNIT",
  "locale": "<LOCALE>",
  "collects_pii": false,
  "study_type_code": "adhoc",
  "industry_code": "other",
  "cost_per_interview": {
    "value": "2.7352",
    "currency_code": "USD"
  },
  "client_cost_per_interview_note": {
    "value": "2.7352",
    "currency_code": "USD"
  },
  "project_manager_id": "b551326b-ac9d-4d32-8823-4f025787dab9",
  "fielding_specification": {
    "start_at": "2025-06-20T15:11:35.699Z",
    "end_at": "2025-06-30T15:11:35.699Z"
  },
  "completes_goal": 1500,
  "expected_length_of_interview_minutes": 2,
  "expected_incidence_rate": 0.9,
  "exclusion": {
    "enabled": true
  },
  "industry_lockout_code": "no_lock_out",
  "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": 1,
      "demographics_strictness_percentage": 100
    }
  },
  "profiling": {
    "profile_adjustment_type": "percentage",
    "profiles": [
      {
        "object": "regular",
        "quotas_enabled": true,
        "targets": [
          {
            "conditions": [
              {
                "object": "open_ended",
                "question_id": 45,
                "allow_all_values": false,
                "open_ended_values": [
                  "98001",
                  "98007",
                  "98125",
                  "98258"
                ]
              }
            ],
            "quota": {
              "completes_goal_percentage": 50
            }
          },
          {
            "conditions": [
              {
                "object": "open_ended",
                "question_id": 45,
                "allow_all_values": false,
                "open_ended_values": [
                  "78001",
                  "78007",
                  "78125",
                  "78258"
                ]
              }
            ],
            "quota": {
              "completes_goal_percentage": 50
            }
          }
        ]
      }
    ]
  },
  "allocations": {
    "open_exchange_allocations": {
      "blocked_supplier_ids": null,
      "exchange_min_percentage": 0,
      "exchange_max_percentage": 100,
      "groups": null
    },
    "private_exchange_allocations": {
      "blocked_supplier_ids": [
        "980"
      ],
      "groups": [
        {
          "group_name": "Private group 1",
          "min_percentage": 0,
          "max_percentage": 100,
          "supplier_id": "1966"
        }
      ]
    }
  }
}'

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

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

  • Path Parameters:
  • account_id
  • project_id
  • target_group_id
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 <token>' \
-H 'Cint-API-Version: 2025-12-18' \
-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

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

  • 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}/allocation-specification' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <token>' \
-H 'Cint-API-Version: 2025-12-18'

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"
      }
    ]
  }
}