# Target Groups API Target Groups cluster Target objects together so they can be referenced as a single unit in Campaign or Number routing settings. Groups can dial their Targets one at a time or simultaneously, enforce concurrency limits, and apply call caps that span the entire group. ## Target Group object > Example Target Group: ```json { "target_group": { "id": 1, "name": "Sales Team", "target_ids": [1, 2, 3], "targets": [ { "id": 1, "number": "+18668987878", "name": "Jason Cell", "priority": 1, "weight": 1 }, { "id": 2, "number": "+18005551234", "name": "Office Line", "priority": 1, "weight": 1 }, { "id": 3, "number": "+18005555678", "name": "Support Line", "priority": 1, "weight": 1 } ], "concurrency_cap": null, "calls_in_progress": 0, "behavior": 1, "priority": null, "weight": null, "caps": [ { "id": 652978, "filled": 0, "cap": null, "type": "Hard" }, { "id": 652979, "filled": 0, "cap": null, "type": "Hourly" }, { "id": 652980, "filled": 0, "cap": null, "type": "Daily" }, { "id": 652981, "filled": 0, "cap": null, "type": "Monthly" } ] } } ``` ### Top-level fields | Field | Type | Description | | ------------------- | ----------------- | ---------------------------------------------------------------------------------------------------- | | `id` | integer | Retreaver's internal ID for the target group. | | `name` | string | Human-readable label. | | `target_ids` | array\ | IDs of Targets belonging to this group. | | `targets` | array | The Targets belonging to this group, expanded — see [Target](#target). | | `concurrency_cap` | integer \| null | Maximum concurrent calls across all targets in the group. `null` means unlimited. | | `calls_in_progress` | integer | Number of calls currently in progress across the group. | | `behavior` | integer | `1` = Dial separately. `2` = Simuldial (dial all targets simultaneously). | | `priority` | integer \| null | Priority used when the parent dialer is simuldialing groups. | | `weight` | integer \| null | Load-balancing weight used when the parent dialer is simuldialing groups. | | `caps` | array | Hard, Hourly, Daily, and Monthly caps — see [Cap](#cap). | ### Target Each entry in `targets` is the full Target object as documented on the [Targets API](/api/targets) page — all target fields, caps, business hours, tag values, and so on (everything except the target's own nested `target_groups`). The example above is abbreviated; the routing-relevant fields are: | Field | Type | Description | | ---------- | --------------- | ----------------------------------------------------------------- | | `id` | integer | Retreaver's internal ID for the target. | | `number` | string | E.164 phone number or SIP endpoint. | | `name` | string \| null | Descriptive label. | | `priority` | integer | Lowest value is considered first when routing. | | `weight` | integer | Randomizes order among targets with equal priority. | ### Cap Every Target Group exposes four caps — one of each type. They are created automatically when the group is created. | Field | Type | Description | | -------- | ----------------- | ---------------------------------------------------------------------------------------------------- | | `id` | integer | Internal ID of the cap. | | `type` | string | One of `Hard`, `Hourly`, `Daily`, `Monthly`. | | `cap` | integer \| null | Limit for this cap. `null` means no limit. | | `filled` | integer | Number of calls currently counted toward this cap. | **Cap behavior:** - `Hard` — permanent. Once reached, the group receives no more calls until manually reset (see [Reset hard cap](#reset-hard-cap)). - `Hourly` / `Daily` / `Monthly` — reset automatically on their respective schedules. ## List all Target Groups ```shell curl "https://api.retreaver.com/target_groups.json?api_key=[api_key]&company_id=1" ``` > The above command returns an array of Target Group objects. Returns all Target Groups for the authenticated Company. ### HTTP Request `GET https://api.retreaver.com/target_groups.json?api_key=[api_key]&company_id=1` ## Get a specific Target Group ```shell curl "https://api.retreaver.com/target_groups/1.json?api_key=[api_key]&company_id=1" ``` > The above command returns a single Target Group object. Returns a Target Group by its Retreaver internal ID. ### HTTP Request `GET https://api.retreaver.com/target_groups/{id}.json?api_key=[api_key]&company_id=1` ### Path Parameters | Parameter | Type | Description | | --------- | ------- | -------------------------------------------- | | `id` | integer | Retreaver's internal ID of the target group. | ## Create a Target Group ```shell curl -s \ -X POST \ "https://api.retreaver.com/target_groups.json?api_key=[api_key]&company_id=1" \ -H "Content-Type: application/json" \ -d '{ "target_group": { "name": "Sales Team", "target_ids": [1, 2, 3], "concurrency_cap": 5 } }' ``` > The above command returns the newly created Target Group object. Creates a new Target Group. Target Groups can be referenced from Campaign or Number routing and provide shared concurrency and cap enforcement across their member Targets. ### HTTP Request `POST https://api.retreaver.com/target_groups.json?api_key=[api_key]&company_id=1` `Content-Type: application/json` ### Body Parameters All parameters must be nested under a `target_group` key. | Parameter | Type | Default | Required | Description | | ------------------------- | --------------- | ------- | --------------- | ---------------------------------------------------------------------------------------------------------- | | `name` | string | | required | Descriptive label for the group. | | `target_ids` | array\ | `[]` | | Target IDs to include in the group. | | `concurrency_cap` | integer | `null` | | Maximum concurrent calls across the group. Omit or `null` for unlimited. | | `behavior` | integer | `1` | | `1` = Dial separately. `2` = Simuldial (dial all targets simultaneously). | | `priority` | integer | `null` | if `behavior=2` | Priority used when simuldialing. | | `weight` | integer | `null` | if `behavior=2` | Load-balancing weight used when simuldialing. | | `hard_cap_attributes` | object | | | Hard cap — see [Cap attributes](#cap-attributes). | | `hourly_cap_attributes` | object | | | Hourly cap — see [Cap attributes](#cap-attributes). | | `daily_cap_attributes` | object | | | Daily cap — see [Cap attributes](#cap-attributes). | | `monthly_cap_attributes` | object | | | Monthly cap — see [Cap attributes](#cap-attributes). | #### Cap attributes | Parameter | Type | Required | Description | | --------- | ------- | -------- | ------------------------------------------------------- | | `cap` | integer | required | The cap limit for this period. Set to `null` to remove. | > [!TIP] > Create a simuldial group: > ```json > { > "target_group": { > "name": "Priority Buyers", > "target_ids": [1, 2], > "behavior": 2, > "priority": 1, > "weight": 1 > } > } > ``` ## Update a Target Group ```shell curl -s \ -X PUT \ "https://api.retreaver.com/target_groups/1.json?api_key=[api_key]&company_id=1" \ -H "Content-Type: application/json" \ -d '{"target_group":{"name":"Renamed Group"}}' ``` > The above command returns the updated Target Group object. Updates any attributes on the Target Group. Only the fields you pass are changed. **Target membership — three ways to update:** - `target_ids` — full replacement list. Replaces all existing members. - `add_targets_by_id` — adds targets without affecting existing members. - `remove_targets_by_id` — removes specific targets from the group. The `add_targets_by_id` and `remove_targets_by_id` helpers avoid having to track the current membership client-side. ### HTTP Request `PUT https://api.retreaver.com/target_groups/{id}.json?api_key=[api_key]&company_id=1` `Content-Type: application/json` ### Path Parameters | Parameter | Type | Description | | --------- | ------- | -------------------------------------------- | | `id` | integer | Retreaver's internal ID of the target group. | ### Body Parameters Accepts the same parameters as [Create a Target Group](#create-a-target-group), plus: | Parameter | Type | Description | | ---------------------- | --------------- | ------------------------------------------------------------------------- | | `add_targets_by_id` | array\ | Target IDs to add to the group without replacing existing members. | | `remove_targets_by_id` | array\ | Target IDs to remove from the group. | All parameters are optional on update. > [!TIP] > Set a hard cap of 100 calls: > ```json > { "target_group": { "hard_cap_attributes": { "cap": 100 } } } > ``` ## Delete a Target Group ```shell curl -X DELETE "https://api.retreaver.com/target_groups/1.json?api_key=[api_key]&company_id=1" ``` Deletes a Target Group. Returns `204 No Content` on success. ### HTTP Request `DELETE https://api.retreaver.com/target_groups/{id}.json?api_key=[api_key]&company_id=1` ## Reset hard cap ```shell curl -s \ -X POST \ "https://api.retreaver.com/target_groups/1/reset_cap.json?api_key=[api_key]&company_id=1" \ -H "Content-Type: application/json" ``` Clears the calls currently counted toward the group's hard cap and resets the hard cap of every Target in the group to `0`. This endpoint requires a superuser account and responds with a `302` redirect (not a `200 OK` JSON response). Useful when reopening a group for a new insertion order period without waiting for the automatic schedule. ### HTTP Request `POST https://api.retreaver.com/target_groups/{id}/reset_cap.json?api_key=[api_key]&company_id=1`