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

tip

If the supplier rules you want are already saved as an allocation template, you can send an allocation_template reference instead of building the allocations object by hand:

"allocation_template": {
    "id": "01JT5Z59MAKQ82J5K9Y3YGFNHN",
    "type": "account"
}

Supply id (the template's ULID) and type (global, account, or country). Exactly one of allocations or allocation_template is required — sending both is rejected.

The create and update draft target group endpoints accept this reference. The update target group allocations endpoint used below applies after launch or scheduling, takes an allocations object, and does not accept a template reference.

  • 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's allocations​

You can utilize the update target group allocations endpoint:

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