Targets API

Targets are destination phone numbers or SIP endpoints that calls are routed to, typically buyer call centers or agent lines. Each Target carries its own routing priority, concurrency limits, business hours, caps, and tags.

Target object

Example Target:

{
  "target": {
    "id": 22592,
    "number": "+18668987878",
    "name": "Retreaver Support",
    "tid": null,
    "priority": 1,
    "weight": 1,
    "timeout_seconds": 30,
    "timer_offset": 0,
    "concurrency_cap": null,
    "calls_in_progress": 0,
    "send_digits": null,
    "inband_signals": false,
    "time_zone": "Eastern Time (US & Canada)",
    "alternative_id": null,
    "block_recording": null,
    "obfuscate_cid": false,
    "custom_cid": null,
    "cid_number_id": null,
    "sip_username": null,
    "sip_password": null,
    "paused": false,
    "paused_at": null,
    "created_at": "2016-06-28T23:13:51Z",
    "updated_at": "2016-06-28T23:13:51Z",
    "target_group_ids": [1, 2],
    "target_groups": [
      {
        "id": 1,
        "name": "West Coast",
        "target_ids": [22592],
        "concurrency_cap": null,
        "calls_in_progress": 0,
        "behavior": 1,
        "priority": null,
        "weight": null
      },
      {
        "id": 2,
        "name": "East Coast",
        "target_ids": [22592],
        "concurrency_cap": null,
        "calls_in_progress": 0,
        "behavior": 1,
        "priority": null,
        "weight": null
      }
    ],
    "caps": [
      { "id": 707898, "filled": 0, "cap": null, "type": "Hard" },
      { "id": 707899, "filled": 0, "cap": null, "type": "Hourly" },
      { "id": 707900, "filled": 0, "cap": null, "type": "Daily" },
      { "id": 707901, "filled": 0, "cap": null, "type": "Monthly" }
    ],
    "business_hours": [
      { "id": 156838, "day_of_week": 0, "work_day": true, "time_open": 0, "time_close": 2400, "invert": false }
    ],
    "tag_values": []
  }
}

Swipe horizontally for full code

Top-level fields

Swipe horizontally to view full table

Field	Type	Description
`id`	integer	Retreaver’s internal ID for the target.
`number`	string	E.164 phone number or `sip:user@domain.com` SIP endpoint.
`name`	string \| null	Descriptive label.
`tid`	string \| null	Your internal ID for this target (aka `client_tid`).
`priority`	integer	Lowest value is considered first when routing.
`weight`	integer	Randomizes order among targets with equal priority.
`timeout_seconds`	integer	Seconds to wait while ringing before moving on. Valid range `5`–`999`.
`timer_offset`	integer	Offsets timers on Tracking URLs or Conversion Criteria when routing to this target.
`concurrency_cap`	integer \| null	Maximum concurrent calls. `null` means unlimited.
`calls_in_progress`	integer	Number of calls currently in progress.
`send_digits`	string \| null	DTMF digits sent when the recipient picks up. Use `w` for a 0.5-second pause. Useful for bypassing IVRs.
`inband_signals`	boolean	Enables in-band ringing detection alongside `timer_offset`.
`time_zone`	string	ActiveSupport time zone used to evaluate business hours — see Valid time zones.
`alternative_id`	string \| null	Optional secondary identifier.
`block_recording`	boolean \| null	When `true`, call recording is suppressed when routing through this target.
`obfuscate_cid`	boolean	Masks the caller’s number presented to the target.
`custom_cid`	string \| null	Custom caller ID to present to the target.
`cid_number_id`	integer \| null	Retreaver-managed number to present as caller ID.
`sip_username`	string \| null	SIP auth username (SIP endpoints only).
`sip_password`	string \| null	SIP auth password (SIP endpoints only).
`paused`	boolean	Paused targets are skipped when routing calls.
`paused_at`	string \| null	Timestamp when the target was paused.
`created_at` / `updated_at`	string (ISO 8601)	Creation and last-modified timestamps.
`target_group_ids`	array of integers	IDs of the Target Groups this target belongs to.
`target_groups`	array	The Target Groups this target belongs to, expanded — see Target Groups.
`caps`	array	Hard, Hourly, Daily, and Monthly caps — see Cap.
`business_hours`	array	Business hours records — see Business Hour. Defaults to 24/7 open.
`tag_values`	array	Tags attached to the target.

Cap

Every Target exposes four caps — one of each type (hard cap, daily cap, etc), they are created automatically when a new Target is created, with an null (infinite) cap.

Swipe horizontally to view full table

Field	Type	Description
`id`	integer	Internal ID of the cap.
`type`	string	One of `Hard`, `Hourly`, `Daily`, `Monthly`.
`cap`	integer \| null	Limit. `null` means no limit.
`filled`	integer	Calls currently counted toward this cap.

Cap behavior: Hard is permanent since it measures the total calls over the lifetime of the Target and must be reset manually (see Reset hard cap). Hourly, Daily, and Monthly reset automatically on their respective schedules.

Business Hour

A target with no business hours is treated as available 24/7.

Swipe horizontally to view full table

Field	Type	Description
`id`	integer	Internal ID. Pass this when updating an existing record.
`target_id`	integer	ID of the target this record belongs to.
`day_of_week`	integer	`0` = Sunday, `6` = Saturday.
`work_day`	boolean	Whether the target is open on this day.
`time_open`	integer	Time the target opens, 24-hour `HHMM` format (e.g. `900` = 9:00 AM).
`time_close`	integer	Time the target closes, 24-hour `HHMM` format (e.g. `1700` = 5:00 PM).
`invert`	boolean	When `true`, the hours indicate when the target is closed — useful for overnight shifts (e.g. closed 0600–2200).
`created_at` / `updated_at`	string (ISO 8601)	Creation and last-modified timestamps.

List all Targets

curl "https://api.retreaver.com/targets.json?api_key=[api_key]&company_id=1"

Swipe horizontally for full code

The above command returns an array of Target objects.

Returns all Targets for the authenticated Company.

HTTP Request

curl "https://api.retreaver.com/targets.json?api_key=[api_key]&company_id=1"

Swipe horizontally for full code

Get a specific Target

curl "https://api.retreaver.com/targets/22592.json?api_key=[api_key]&company_id=1"

Swipe horizontally for full code

The above command returns a single Target object.

Returns a Target by its Retreaver internal ID.

HTTP Request

curl "https://api.retreaver.com/targets/{id}.json?api_key=[api_key]&company_id=1"

Swipe horizontally for full code

Path Parameters

Swipe horizontally to view full table

Parameter	Type	Description
`id`	integer	Retreaver’s internal ID of the target.

Create a Target

curl -s \
    -X POST \
    "https://api.retreaver.com/targets.json?api_key=[api_key]&company_id=1" \
    -H "Content-Type: application/json" \
    -d '{"target":{"number":"+18668987878","name":"Retreaver Support"}}'

Swipe horizontally for full code

The above command returns the newly created Target object.

Creates a new Target. Business hours default to 24/7 open unless you pass business_hours_attributes.

HTTP Request

curl -X POST "https://api.retreaver.com/targets.json?api_key=[api_key]&company_id=1" \
  -H "Content-Type: application/json"

Swipe horizontally for full code

Body Parameters

All parameters must be nested under a target key.

Swipe horizontally to view full table

Parameter	Type	Default	Required	Description
`number`	string		required	E.164-formatted phone number or `sip:user@domain.com` SIP endpoint.
`name`	string			Descriptive label for the target.
`client_tid`	string			Your own internal ID for this target.
`priority`	integer	`1`		Lowest value is considered first when routing calls.
`weight`	integer	`1`		Randomizes order among targets with equal priority.
`timeout_seconds`	integer	`30`		Seconds to wait while ringing before moving on. Valid range `5`–`999`.
`concurrency_cap`	integer	`null`		Maximum concurrent calls. Omit or `null` for unlimited.
`timer_offset`	integer	`0`		Offsets timers on Tracking URLs or Conversion Criteria.
`send_digits`	string			DTMF digits to send when the recipient picks up. Use `w` for a 0.5-second pause.
`inband_signals`	boolean	`false`		Enables in-band ringing detection alongside `timer_offset`.
`paused`	boolean	`false`		Paused targets are skipped when routing.
`time_zone`	string	`UTC`		ActiveSupport time zone for business hours — see Valid time zones.
`sip`	boolean	`false`		Marks the target as a SIP endpoint.
`sip_username`	string			SIP auth username (SIP endpoints only).
`sip_password`	string			SIP auth password (SIP endpoints only).
`block_recording`	boolean	`false`		Suppresses call recording when routing through this target.
`obfuscate_cid`	boolean	`false`		Masks the caller’s number presented to the target.
`alternative_id`	string			Optional secondary identifier.
`dba`	string			“Doing Business As” label.
`tag_list`	string			Comma-separated `<<<key:value>>>` tags — see Tagging a Target.
`business_hours_attributes`	array			Business hour overrides — see Business hour attributes. Defaults to 24/7 open.
`hard_cap_attributes`	object			Hard cap — see Cap attributes.
`hourly_cap_attributes`	object			Hourly cap — see Cap attributes.
`daily_cap_attributes`	object			Daily cap — see Cap attributes.
`monthly_cap_attributes`	object			Monthly cap — see Cap attributes.

Business hour attributes

Calls are only routed to the target during its business hours, evaluated in the target’s time_zone. When updating existing business hours, you must pass the existing record’s id; omitting id creates a new record.

Swipe horizontally to view full table

Parameter	Type	Default	Required	Description
`id`	integer			Required when updating an existing business hour record.
`day_of_week`	integer		required	`0` = Sunday, `6` = Saturday.
`work_day`	boolean	`true`		Whether the target is open on this day.
`time_open`	integer	`0`		Time the target opens, 24-hour `HHMM` format (e.g. `900` = 9:00 AM).
`time_close`	integer	`2400`		Time the target closes, 24-hour `HHMM` format (e.g. `1700` = 5:00 PM).
`invert`	boolean	`false`		When `true`, the hours indicate when the target is closed — useful for overnight shifts.

Cap attributes

Swipe horizontally to view full table

Parameter	Type	Required	Description
`cap`	integer	required	The cap limit for this period. Set to `null` to remove.

Update a Target

curl -s \
    -X PUT \
    "https://api.retreaver.com/targets/22592.json?api_key=[api_key]&company_id=1" \
    -H "Content-Type: application/json" \
    -d '{"target":{"paused":true}}'

Swipe horizontally for full code

The above command returns the updated Target object.

Updates any attributes on the Target. Only the fields you pass are changed.

HTTP Request

curl -X PUT "https://api.retreaver.com/targets/{id}.json?api_key=[api_key]&company_id=1" \
  -H "Content-Type: application/json"

Swipe horizontally for full code

Path Parameters

Swipe horizontally to view full table

Parameter	Type	Description
`id`	integer	Retreaver’s internal ID of the target.

Body Parameters

Accepts the same parameters as Create a Target. All parameters are optional on update.

Business hours: Pass the existing id of each record you want to change. Records without an id are created.

Tip

Pause a target, set a hard cap of 100 calls, and restrict to Mon 9–5:

{
  "target": {
    "paused": true,
    "hard_cap_attributes": { "cap": 100 },
    "business_hours_attributes": [
      { "day_of_week": 1, "work_day": true, "time_open": 900, "time_close": 1700 },
      { "day_of_week": 6, "work_day": false }
    ]
  }
}

Swipe horizontally for full code

Delete a Target

curl -X DELETE "https://api.retreaver.com/targets/22592.json?api_key=[api_key]&company_id=1"

Swipe horizontally for full code

Deletes a Target.

Note

Returns 302 if the Target is still referenced by a Campaign or Number. Remove it from those first, then retry.

HTTP Request

curl -X DELETE "https://api.retreaver.com/targets/{id}.json?api_key=[api_key]&company_id=1"

Swipe horizontally for full code

Tagging a Target

curl -s \
    -X PUT \
    "https://api.retreaver.com/targets/22592.json?api_key=[api_key]&company_id=1" \
    -H "Content-Type: application/json" \
    -d '{"target":{"tag_list":"<<<calling_about:support>>>,<<<calling_about:other>>>"}}'

Swipe horizontally for full code

The tags appear as tag_values on the reloaded Target:

{
  "target": {
    "id": 22592,
    "tag_values": [
      { "key": "calling_about", "value": "support", "operator": "==", "id": 67589 },
      { "key": "calling_about", "value": "other",   "operator": "==", "id": 67591 }
    ]
  }
}

Swipe horizontally for full code

Set tags on a Target by passing tag_list — a comma-separated string of triple-angle-bracket-enclosed <<<key:value>>> tags. Retreaver will create or reuse tags based on this input so you don’t need to track tag IDs.

The list replaces all existing tags — always send the full desired set.
Pass an empty string to clear all tags.
Maximum 100 tags per request. US zip geo tags are automatically consolidated.

HTTP Request

curl -X PUT "https://api.retreaver.com/targets/{id}.json?api_key=[api_key]&company_id=1" \
  -H "Content-Type: application/json"

Swipe horizontally for full code

Reset hard cap

curl -s \
    -X POST \
    "https://api.retreaver.com/targets/22592/reset_cap.json?api_key=[api_key]&company_id=1" \
    -H "Content-Type: application/json"

Swipe horizontally for full code

Clears the calls currently counted toward the Target’s hard cap, resetting filled to 0. Returns 200 OK on success.

Useful for reopening a target for a new insertion order period without waiting for the automatic schedule.

HTTP Request

curl -X POST "https://api.retreaver.com/targets/{id}/reset_cap.json?api_key=[api_key]&company_id=1"

Swipe horizontally for full code

Valid Time Zones

Retreaver uses ActiveSupport time zone names. Need to map IANA time zones to this format?

Swipe horizontally to view full table


International Date Line West	Midway Island	American Samoa	Hawaii	Alaska
Pacific Time (US & Canada)	Tijuana	Mountain Time (US & Canada)	Arizona	Chihuahua
Mazatlan	Central Time (US & Canada)	Saskatchewan	Guadalajara	Mexico City
Monterrey	Central America	Eastern Time (US & Canada)	Indiana (East)	Bogota
Lima	Quito	Atlantic Time (Canada)	Caracas	La Paz
Santiago	Newfoundland	Brasilia	Buenos Aires	Montevideo
Georgetown	Greenland	Mid-Atlantic	Azores	Cape Verde Is.
Dublin	Edinburgh	Lisbon	London	Casablanca
Monrovia	UTC	Belgrade	Bratislava	Budapest
Ljubljana	Prague	Sarajevo	Skopje	Warsaw
Zagreb	Brussels	Copenhagen	Madrid	Paris
Amsterdam	Berlin	Bern	Rome	Stockholm
Vienna	West Central Africa	Bucharest	Cairo	Helsinki
Kyiv	Riga	Sofia	Tallinn	Vilnius
Athens	Istanbul	Minsk	Jerusalem	Harare
Pretoria	Moscow	St. Petersburg	Volgograd	Kuwait
Riyadh	Nairobi	Baghdad	Tehran	Abu Dhabi
Muscat	Baku	Tbilisi	Yerevan	Kabul
Ekaterinburg	Islamabad	Karachi	Tashkent	Chennai
Kolkata	Mumbai	New Delhi	Kathmandu	Astana
Dhaka	Sri Jayawardenepura	Almaty	Novosibirsk	Rangoon
Bangkok	Hanoi	Jakarta	Krasnoyarsk	Beijing
Chongqing	Hong Kong	Urumqi	Kuala Lumpur	Singapore
Taipei	Perth	Irkutsk	Ulaanbaatar	Seoul
Osaka	Sapporo	Tokyo	Yakutsk	Darwin
Adelaide	Canberra	Melbourne	Sydney	Brisbane
Hobart	Vladivostok	Guam	Port Moresby	Magadan
Solomon Is.	New Caledonia	Fiji	Kamchatka	Marshall Is.
Auckland	Wellington	Nuku’alofa	Tokelau Is.	Chatham Is.
Samoa