Retreaver

API

Introduction
Loading status… Contact Support

Targets API

View as Markdown

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.
conversion_groups array Conversion settings for calls to this target — see Conversion Group. Returned only to the company’s administrators and managers.

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.

Conversion Group

A group of Conversions that decides when a call to this Target counts as converted. See Add a Conversion to a Target to manage them.

{
  "id": 256490,
  "name": "50$ after 90s",
  "dedupe_seconds": 0,
  "eval_order": 0,
  "postback": false,
  "conversion_type": "timer",
  "postback_uuid": null,
  "tag_values": [],
  "conversions": [
    {
      "id": 263254,
      "type": null,
      "seconds": 90,
      "revenue": 50.0,
      "payout": 0.0,
      "payout_modifier": null,
      "postback_timeout": 600,
      "match_trigger": null
    }
  ]
}
Swipe horizontally for full code
Swipe horizontally to view full table
Field Type Description
id integer Internal ID. Pass this when updating or deleting the group.
name string Label for the group.
conversion_type string How calls convert, e.g. timer — the call converts once it lasts the Conversion’s seconds.
dedupe_seconds integer Window in which a repeat caller cannot convert through this group again. 0 disables it — see Allowed dedupe_seconds values.
eval_order integer Groups are evaluated in ascending order; the first whose tags match the call applies.
tag_values array Tags a call must match for this group to apply.
conversions array The group’s Conversions — see Conversion.

Conversion

Swipe horizontally to view full table
Field Type Description
id integer Internal ID. Pass this when updating the Conversion.
seconds integer Call duration in seconds a timer Conversion needs to convert.
revenue decimal Revenue attributed to the call when it converts.

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.
conversion_groups_attributes array Conversion settings — see Add a Conversion to a Target.

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.
  • A new key is created as a text tag unless you give it a type. Append the type to the value the first time you use a key: <<<bid:>=10#numeric>>>, or #date (yyyy/mm/dd), #date_time (yyyy-mm-dd hh:mm:ss), #boolean. We recommend typing any key you compare with <, <=, > or >=, since text tags compare as strings. The suffix is not stored, and keys that already exist as typed tags keep their type.

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

Add a Conversion to 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":{"conversion_groups_attributes":[{"name":"50$ after 90s","conversion_type":"timer","conversions_attributes":[{"seconds":90,"revenue":50.0}]}]}}'
Swipe horizontally for full code

The above command returns the updated Target, with the new group under conversion_groups — see Conversion Group.

Conversions on a Target are managed through nested Conversion Groups. Update the Target with a conversion_groups_attributes array, where each group holds its own conversions_attributes array.

The example creates a timer Conversion named 50$ after 90s: once a call to the Target lasts 90 seconds, it is marked as converted and $50.00 of revenue is attributed to it.

A group passed without an id always creates a new Conversion Group. To change an existing group or its Conversions, pass the id values returned when reading the Target — see Update a Conversion on a Target.

Warning

Adding more than one Conversion Group to a Target through the API is not recommended: it is hard to tell which group wins once evaluation order is taken into account. A call only ever converts through one group. Groups are evaluated in ascending eval_order, and the first group whose tags match the call applies.

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

Conversion Group Parameters

Nested under target.conversion_groups_attributes[].

Swipe horizontally to view full table
Parameter Type Default Required Description
id integer when updating Required to update an existing group. Omit to create a new one.
name string Default Conversion Settings A label for the group, e.g. 50$ after 90s.
conversion_type string required timer.
dedupe_seconds integer 0 (no de-dupe) Stops a repeat caller from triggering this group’s Conversions again within this many seconds of their previous call. Must be one of the allowed values.
conversions_attributes array required The group’s Conversions — see Conversion Parameters.

Conversion Parameters

Nested under conversions_attributes[].

Swipe horizontally to view full table
Parameter Type Default Required Description
id integer when updating Required to update an existing Conversion. Omit to create a new one.
seconds integer 90 Call duration in seconds a timer Conversion needs to convert.
revenue decimal 0 Revenue attributed to the call when it converts.

Allowed dedupe_seconds values

Swipe horizontally to view full table
Value Duration
0 No de-dupe
3600 1 hour
7200 2 hours
21600 6 hours
43200 12 hours
86400 24 hours
172800 2 days
259200 3 days
345600 4 days
604800 1 week
2592000 30 days
5184000 60 days
7776000 90 days
10368000 120 days
12960000 150 days
15552000 180 days
18144000 210 days
20736000 240 days
23328000 270 days
25920000 300 days
28512000 330 days
31556952 1 year
315569520 1 decade
-1 Forever

Update a Conversion on 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":{"conversion_groups_attributes":[{"id":256490,"name":"75$ after 90s","conversions_attributes":[{"id":263254,"revenue":75.0}]}]}}'
Swipe horizontally for full code

The above command returns the updated Target, with conversion_groups[0].name now 75$ after 90s and its Conversion’s revenue now 75.0.

Pass the id of the Conversion Group and of each Conversion you want to change, along with only the attributes to change; anything left out keeps its current value. The example renames the group to 75$ after 90s and raises the Conversion’s revenue to $75.00.

Warning

Pass both the Conversion Group id and the Conversion id. Without them nothing is updated — a new Conversion, or a whole new Conversion Group with its own Conversion, is created alongside the existing ones.

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

Accepts the same Conversion Group Parameters and Conversion Parameters.

Delete a Conversion from 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":{"conversion_groups_attributes":[{"id":256490,"_destroy":true}]}}'
Swipe horizontally for full code

The above command returns the updated Target with an empty conversion_groups array.

To remove conversion settings from a Target, delete the whole Conversion Group: pass the group’s id with "_destroy": true inside conversion_groups_attributes.

Important

Always delete the entire Conversion Group. Do not delete individual Conversions out of a group.

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

Parameters

Nested under target.conversion_groups_attributes[].

Swipe horizontally to view full table
Parameter Type Default Required Description
id integer required The id of the Conversion Group to delete.
_destroy boolean false required Set to true to delete the group.

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

Help us improve this article or request new support guides.

Next

Real-Time Bidding (RTB) API
On this page
Target object
Top-level fields
Cap
Business Hour
Conversion Group
Conversion
List all Targets
HTTP Request
Get a specific Target
HTTP Request
Path Parameters
Create a Target
HTTP Request
Body Parameters
Update a Target
HTTP Request
Path Parameters
Body Parameters
Delete a Target
HTTP Request
Tagging a Target
HTTP Request
Reset hard cap
HTTP Request
Add a Conversion to a Target
HTTP Request
Conversion Group Parameters
Conversion Parameters
Allowed dedupe_seconds values
Update a Conversion on a Target
HTTP Request
Delete a Conversion from a Target
HTTP Request
Parameters
Valid Time Zones