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:

{
  "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

Target

Each entry in targets is the full Target object as documented on the Targets API 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:

Cap

Every Target Group exposes four caps — one of each type. They are created automatically when the group is created.

Cap behavior:

• Hard — permanent. Once reached, the group receives no more calls until manually reset (see Reset hard cap).
• Hourly / Daily / Monthly — reset automatically on their respective schedules.

List all Target Groups

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

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

Create a Target Group

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.

Cap attributes

{
  "target_group": {
    "name": "Priority Buyers",
    "target_ids": [1, 2],
    "behavior": 2,
    "priority": 1,
    "weight": 1
  }
}

Update a Target Group

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

Body Parameters

Accepts the same parameters as Create a Target Group, plus:

All parameters are optional on update.

{ "target_group": { "hard_cap_attributes": { "cap": 100 } } }

Delete a Target Group

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

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