Skip to main content
Version: 2025-12-18

Understanding supply allocations

Allocations let you control how supply is distributed across the Cint Exchange for a given target group.

At a high level, allocations answer questions such as:

  • Which suppliers can participate in this target group?
  • How much of my total completes can come from each supplier or group of suppliers?
  • How to balance traffic between different suppliers?

Allocations live inside the target group definition and are respected:

  • When you check feasibility
  • When you launch a target group
  • When you update allocations for a non-draft target group

For your integration you can choose to:

  • Use simple defaults (e.g., 100% open exchange)
  • Apply fine-grained controls per supplier or group of suppliers.

All of this is configured via the allocations object when creating or updating a target group. Alternatively, you can point at a saved allocation template with the allocation_template object and let Cint load the setup for you — see Reusing an allocation setup.

What are allocations?​

The allocation is a structured object in the target group that tells Cint systems:

  1. How much of the target group is to be filled.
  2. How much (if any) can be filled by private exchange suppliers.
  3. Which suppliers are:
    • Allowed, and with what min/max percentage of the total completes.
    • Blocked from participating.

Conceptually, you can think of it as two layers:

  • open_exchange_allocations - controls the public Cint Exchange suppliers
  • private_exchange_allocations - controls any private / contracted suppliers you have access to.
info

private_exchange_allocations is an exclusive feature, please contact your account manager if you are interested in this functionality.

If you do not have access to private exchange allocations you can ignore private_exchange_allocations entirely.

The model is simple enough to be used as a default configuration for all your projects. And flexible enough for advanced configurations and post-launch tuning.

You send allocations when performing actions such as:

  • Creating or updating a draft target group.
  • Checking feasibility for a target group (by including allocations in the target group definition).
  • Updating allocations on a launched target group.

On every action except the last one you can send an allocation_template reference instead of a literal allocations object.

Types of allocations​

open_exchange_allocations​

open_exchange_allocations defines how the open Cint Exchange suppliers can participate in this target group.

Key concepts:

  • min_percentage / max_percentage - defines how much of the total completes can come from open exchange suppliers.
  • groups - defines groups of suppliers that can participate in this target group, along with their min/max percentage.
  • blocked_supplier_ids - defines suppliers that are not allowed to participate in this target group

Field overview:

  • open_exchange_allocations (object): Defines how open exchange suppliers can participate.
    • exchange_min_percentage (integer): Minimum percentage of total completes that must come from open exchange suppliers.
    • exchange_max_percentage (integer): Maximum percentage of total completes that can come from open exchange suppliers.
    • blocked_supplier_ids (array of strings): An array of supplier IDs that are blocked from participating in this target group.
    • groups (array of objects): An array of allocation group objects, each defining a specific group of suppliers and their allocation percentages.
      • group_name (string): A human-readable name for the allocation group.
      • min_percentage (integer): Minimum percentage of total completes that must come from this group.
      • max_percentage (integer): Maximum percentage of total completes that can come from this group.
      • suppliers (array of strings): An array of supplier IDs that are part of this allocation group.
note

You can leave groups empty and use only the top level exchange_min_percentage and exchange_max_percentage to control open exchange supply.

private_exchange_allocations​

private_exchange_allocations defines how private / contracted suppliers can participate in this target group.

Key concepts: Blocked private suppliers - fully blocked from this target group. Groups of private suppliers - allowed to participate with min/max percentage. Note: A group of private suppliers can only contain a single supplier.

Field overview:

  • private_exchange_allocations (object): Defines how private exchange suppliers can participate.
    • blocked_supplier_ids (array of strings): An array of supplier IDs that are blocked from participating in this target group.
    • groups (array of objects): An array of allocation group objects, but each object targets only one supplier_id.
      • group_name (string): A human-readable name for the allocation group.
      • min_percentage (integer): Minimum percentage of total completes that must come from this private supplier.
      • max_percentage (integer): Maximum percentage of total completes that can come from this private supplier.
      • supplier_id (string): The supplier ID of the private supplier in this allocation group.
note

A group of private suppliers can only contain a single supplier.

Common configurations​

Example JSON snippets for common allocation configurations.

"allocations": {
    "open_exchange_allocations": {
        "exchange_min_percentage": 0,
        "exchange_max_percentage": 100,
        "blocked_supplier_ids": [],
        "groups": []
    },
    "private_exchange_allocations": {
        "blocked_supplier_ids": [],
        "groups": []
    }
}

Advanced configurations​

Advanced configurations give you tighter control over distribution and supplier strategy. Typical scenarios include:

  • Combining Open Exchange with Private Exchange partners.
  • Guaranteeing minimum traffic for strategic suppliers.
  • Capping maximum exposure to any individual supplier or group.

Below are some practical advanced examples.

Example JSON snippets for advanced allocation configurations.

"allocations": {
    "open_exchange_allocations": {
        "exchange_min_percentage": 30,
        "exchange_max_percentage": 90,
        "blocked_supplier_ids": [
        "30001"
        ],
        "groups": [
            {
                "group_name": "Supplier group 1",
                "min_percentage": 0,
                "max_percentage": 60,
                "suppliers": [
                "8421",
                "9001"
                ]
            },
            {
                "group_name": "Supplier group 2",
                "min_percentage": 10,
                "max_percentage": 50,
                "suppliers": [
                "9100",
                "9200",
                "9300"
                ]
            }
        ]
    },
    "private_exchange_allocations": {
        "blocked_supplier_ids": [],
        "groups": []
    }
}

Reusing an allocation setup​

If you apply the same supplier rules again and again, you can save them as an allocation template instead of rebuilding the allocations object every time. Templates come in three types — global, account, and country — and country templates can also include suppliers your business unit has a private relationship with.

For the differences between the types, how defaults are resolved, and the endpoints for managing each type, see Understanding allocation templates.

Applying a template instead of an allocations object​

Rather than building the allocations object yourself, you can reference a saved template with the allocation_template object. Cint loads that template and applies it as the target group's allocation specification.

"allocation_template": {
    "id": "01JT5Z59MAKQ82J5K9Y3YGFNHN",
    "type": "account"
}
  • id (string, required): The ID of the template to load, in ULID format.
  • type (string, required): The scope of the template to load — global, account, or country.
caution

allocations and allocation_template are mutually exclusive — never send both in the same request.

When you create or update a draft target group, exactly one of the two is required. When you check feasibility, both are optional, but you still cannot send both at once.

Where to configure supply allocations​

You can specify supply allocations using the allocations object, on POST create a target group in draft status or POST update target group allocations when your target group is already launched or scheduled.

The endpoints that accept an allocation_template reference in place of allocations are:

POST update target group allocations takes an allocations object only. Once a target group is launched or scheduled, its allocations are updated directly, not by pointing at a template.