Skip to main content
Version: 2025-12-18

Understanding allocation templates

Allocation templates let you save a reusable allocation setup and apply it to your target groups, so you don't have to define the same supplier rules over and over.

Instead of building allocations from scratch for every target group, you define it once as a template and reuse it across many target groups.

Types of allocation templates​

There are three types of allocation templates, which differ by the scope they apply to:

  • Global templates - maintained by Cint, available to every account.
  • Account templates - managed by your account, not tied to any country.
  • Country templates - managed by your account, scoped to a specific combination of a country and a business unit.

Global templates​

Global templates are defined and maintained by Cint. They are always available to every account, and provide ready-made allocation configurations you can apply without any setup of your own.

They include consumer composite blends for different countries, as well as a template for suppliers that allow contacts, which is critical for running trackers.

Account templates​

Account templates belong to your account and are managed by your account's users, independently of Cint. You can create, modify, and delete them yourself.

Account templates are not tied to a particular business unit or country, so they capture supplier setups you want to reuse regardless of the market a target group runs in.

You can mark a single account template as the default. When a new target group is created on the Cint Exchange UI, the default account template is automatically loaded, as long as there's no competing default country template (see the Default templates and precedence section for more details).

Country templates​

Country templates are also managed by your account, but unlike account templates they are scoped to a single country within a single business unit of your account. Because target groups are executed against a selected country, country templates let you tailor how respondents are allocated between the suppliers available in that market.

Country templates can also include suppliers your business unit has a private relationship with, or that are part of your own supply — something account templates cannot do.

For convenience, you can define a supplier setup once and save it as a country template for several countries at the same time, which is useful when you want to reuse the same configuration across multiple markets.

note

Saving one supplier setup across several countries creates a separate template for each country, not a single shared one. Each must then be updated or deleted individually, so any future change has to be repeated for every country.

You can also mark one country template as the default for each combination of business unit and country, allowing you to set up specific default behavior for different markets. When a new target group is created on the Cint Exchange UI, the default country template is automatically loaded.

Default templates and precedence​

You can set a default template at both the account and country level. When a new target group is created on the Cint Exchange UI, Cint automatically applies the relevant default:

  • If the selected combination of business unit and country has a default country template, it is applied.
  • Otherwise, if your account has a default account template, it is applied.

When setting a new account template as default, it automatically removes the default setting from the previous default account template. When setting a new country template as default, it automatically removes the default setting from the previous default country template that shares the same combination of business unit and country.

When you clear the default status of a currently default country template, or you inactivate the template, no other country template is promoted in its place. In such a case, the default account template will apply, exactly as it would for a combination of country and business unit that never had a default country template.

info

If both a default account template and a default country template could apply, the country template takes precedence, as it represents a deeper level of granularity.

Managing allocation templates via the API​

You work with allocation templates through the demand API. The endpoints available to you depend on the template type.

Global templates​

Global templates are read-only — you can browse and fetch them, but only Cint can create or change them.

Account templates​

You have full control over account templates and can manage them throughout their lifecycle.

To control which account template is applied by default:

Country templates​

You manage country templates much like account templates, with additional endpoints for working with several countries at once.

To save the same supplier setup across multiple countries in one request, use the bulk endpoints:

Unlike account templates, country templates do not have a separate endpoint for assigning the default. Instead, you set the is_default field in the create or update request body:

  • true makes the template the default for its combination of business unit and country, replacing any previous default.
  • false on a template that is currently the default clears the default. No other template is promoted in its place, so the business unit and country are left with no default country template, and the default account template applies instead.
  • false on a template that is not the default changes nothing.
caution

is_default is required in the request body, and an update replaces the whole template. If you update a default template and only mean to change its supplier setup, send is_default: true again — otherwise the update removes its default status.

tip

To look up which default templates currently apply, use GET retrieve the IDs of relevant default allocation templates. It returns the ID of the default account template, and — when you supply the optional business unit ID and country code query parameters — the ID of the default country template as well, so you can see both defaults that could apply. If multiple can apply, the default country template takes precedence on the Cint Exchange UI.

Configuration examples​

The request body you send when creating or updating a template differs between the two template types you manage:

  • Account templates use a single, flat supply_allocations array. Account templates only support Open Exchange suppliers, therefore all of the entries in the array apply to the Open Exchange allocation. Each entry carries a type field — exchange, group, or blocked — that determines its shape.
  • Country templates use nested open_exchange and private_exchange objects, and add an is_default flag in the body.

The snippets below show request bodies you can send to the create and update endpoints for each type. They follow the same allocation concepts described in Understanding supply allocations — bounding the open exchange, grouping suppliers with min/max percentages, and blocking specific suppliers.

Percentage rules​

Both template types validate percentages across every allocation in the body, not just within each one. For account templates the allocations are the exchange entry plus each group entry; for country templates they are the open_exchange object plus each of its groups plus each private_exchange supplier. Three rules apply:

  • The sum of all minimums must not exceed 100.
  • The sum of all maximums must be at least 100.
  • Each allocation's maximum must not exceed 100 minus the sum of every other allocation's minimum. In other words, guaranteeing a minimum somewhere lowers the ceiling everywhere else.

The third rule is easy to miss. If you guarantee a group a minimum of 40%, then no other allocation — including the open exchange itself — can have a maximum above 60%.

Beyond percentages, account templates require exactly one exchange entry and allow at most one blocked entry, each group entry needs at least one supplier, and a supplier ID must not appear in more than one entry. Country templates apply the same duplicate-supplier rule across groups, blocked suppliers, and private exchange suppliers.

Account allocation templates​

These bodies work for both POST create an account allocation template and PUT update an account allocation template.

note

Updating an account template requires an If-Match header carrying the template's current ETag.

Example request bodies for common account template configurations.

{
    "name": "Account default – open exchange",
    "supply_allocations": [
        {
            "type": "exchange",
            "percentage_min": 0,
            "percentage_max": 100
        }
    ]
}

Example request bodies for advanced account template configurations.

{
    "name": "Q1 campaign – premium & standard split",
    "supply_allocations": [
        {
            "type": "exchange",
            "percentage_min": 30,
            "percentage_max": 90
        },
        {
            "type": "group",
            "name": "Premium",
            "percentage_min": 0,
            "percentage_max": 50,
            "suppliers": [
                { "supplier_id": 301 },
                { "supplier_id": 405 }
            ]
        },
        {
            "type": "group",
            "name": "Standard",
            "percentage_min": 0,
            "percentage_max": 30,
            "suppliers": [
                { "supplier_id": 510 },
                { "supplier_id": 620 }
            ]
        },
        {
            "type": "blocked",
            "suppliers": [
                { "supplier_id": 101 }
            ]
        }
    ]
}

Country allocation templates​

These bodies work for both POST create a country allocation template and PUT update a country allocation template. Set is_default to true to make the template the default for its country, replacing any previous default. Sending false for a template that is currently the default clears the default — see Managing allocation templates via the API.

Example request bodies for common country template configurations.

{
    "name": "US default – open exchange",
    "is_default": true,
    "open_exchange": {
        "percentage_min": 0,
        "percentage_max": 100
    }
}

Example request bodies for advanced country template configurations.

{
    "name": "UK – premium & standard groups",
    "is_default": false,
    "open_exchange": {
        "percentage_min": 20,
        "percentage_max": 70,
        "groups": [
            {
                "name": "Premium Suppliers",
                "percentage_min": 30,
                "percentage_max": 60,
                "supplier_ids": [301, 405]
            },
            {
                "name": "Standard Suppliers",
                "percentage_min": 0,
                "percentage_max": 40,
                "supplier_ids": [510, 620]
            }
        ],
        "blocked_supplier_ids": [101]
    }
}
info

private_exchange lets country templates include suppliers your business unit has a private relationship with — something account templates cannot do. If you do not have private relationships set up, you can omit private_exchange entirely.

Creating templates for several countries at once​

To save the same supplier setup across several markets in one request, send a POST bulk create country allocation templates. The body uses the same open_exchange and private_exchange shapes as above, plus a required country_codes array. The setup is saved as a separate template for each listed country.

Example request bodies for bulk-creating country templates across several markets.

{
    "country_codes": ["US", "GB", "DE"],
    "name": "EMEA default – open exchange",
    "is_default": true,
    "open_exchange": {
        "percentage_min": 0,
        "percentage_max": 100
    }
}
note

A bulk create can partially succeed. The response lists the templates that were created and a failed_country_codes array for any that could not be. Setting is_default to true makes the new template the default in every country you list, replacing each country's previous default.