Retreaver

API

Introduction
Loading status… Contact Support

Calls API

The Calls API provides read access to your call log — every call that has been placed through a Retreaver Number in your account.

Our Calls API is versioned to provide backwards compatibility as new fields and response shapes are introduced. The version is included in the URL path, for example /api/v4/calls.json. We recommend building new integrations against v4, the latest version, for the richest data and best performance. Older versions (v3, v2, v1) remain available for existing integrations.

A quick overview of what each version adds:

Swipe horizontally to view full table
Version Key additions
v4 campaign is returned as a nested object ({id, name}) instead of the flat campaign_id / campaign_name fields.
v3 number is returned as a nested object ({number, name}) instead of a plain string.
v2 Adds affiliate/target/campaign names, connection status, profit and cost fields, timing metrics, and the fired_pixels array.
v1 Base set of fields describing the caller, call duration, routing, and recording URL.

Calls API v4

V4 is the current recommended version of the Calls API. It returns the full set of call attributes along with nested campaign and number objects.

Get recent Calls

curl "https://api.retreaver.com/api/v4/calls.json?api_key=[api_key]&company_id=1"
Swipe horizontally for full code

Note

You can find your API key in your “Account Settings” (top-right menu) > API Access

The above command returns JSON structured like this:

[
  {
    "call": {
      "uuid": "f1abfb78-ab8a-4146-9946-8169fbcc6d6c",
      "caller": "+13015236555",
      "caller_number_sent": null,
      "caller_zip": "28379",
      "caller_state": "NC",
      "caller_city": "Rockingham",
      "caller_country": "US",
      "dialed_call_duration": 2,
      "total_duration": 14,
      "ivr_duration": 7,
      "hold_duration": 5,
      "status": "finished",
      "start_time": "2024-11-04T16:52:18.034Z",
      "forwarded_time": "2024-11-04T16:52:25.423Z",
      "end_time": "2024-11-04T16:52:32.882Z",
      "cid": "1",
      "afid": null,
      "sid": null,
      "tid": null,
      "dialed_number": "+12263399112",
      "revenue": 5.0,
      "payout": 5.0,
      "postback_value": null,
      "network_sale_timer_fired": null,
      "affiliate_sale_timer_fired": null,
      "target_sale_timer_fired": null,
      "hung_up_by": "caller",
      "duplicate": false,
      "payable_duplicate": false,
      "receivable_duplicate": false,
      "callpixels_target_id": 27449,
      "system_target_id": 27449,
      "system_campaign_id": 9872,
      "system_affiliate_id": null,
      "fired_pixels_count": 4,
      "charge_total": "0.08",
      "keys_pressed": ["1"],
      "repeat": true,
      "affiliate_repeat": false,
      "target_repeat": true,
      "number_repeat": true,
      "visitor_url": "https://example.com",
      "company_id": 2,
      "conversions_determined_at": "2024-11-04T16:52:54.744Z",
      "updated_at": "2024-11-04T16:53:00.756Z",
      "created_at": "2024-11-04T16:52:18.177Z",
      "billable_minutes": 1,
      "upstream_call_uuid": null,
      "downstream_call_uuids": [],
      "target_group": { "id": 1639, "name": "Retreaver Team" },
      "recording_url": "https://example.com",
      "number": {
        "number": "+18886064349",
        "name": "Publisher Joe Number"
      },
      "campaign": {
        "id": 9872,
        "name": "Retreaver Main - Sales & Support"
      },
      "converted": true,
      "payable": true,
      "receivable": true,
      "conversion_seconds": null,
      "tags": {
        "attempt": "0192f817-6fdc-f8b3-eb07-526dd16e2ade",
        "geo": "301,us,us-28379,us-nc",
        "request_id": "0192f817-6fdc-f8b3-eb07-526dd16e2ade",
        "status": "success",
        "system_target_id": "27449"
      },
      "fired_pixels": [
        {
          "fired_pixel": {
            "url": "https://example.com",
            "fire_order": 0,
            "batch_uuid": "343ccf9b-b3a1-4cd3-b2de-a351dcf40661",
            "created_at": "2024-11-04T16:52:26.948Z",
            "fired_at": "2024-11-04T16:52:26.947Z",
            "status": "fired",
            "webhook_name": "Test Webhook"
          }
        }
      ],
      "via": "inbound-dial",
      "rescued": false,
      "number_id": 4906092,
      "target_id": 27449,
      "affiliate_name": null,
      "connected": true,
      "profit_gross": "-0.08",
      "profit_net": 0.0,
      "target_name": "Taylor Anderson - Sales - +12263399112",
      "time_to_call_in_seconds": 168096,
      "time_to_connect_in_seconds": 12,
      "total_cost": "0.08"
    }
  }
]
Swipe horizontally for full code

Returns a paginated list of Calls across all Numbers in your Account. Results are returned most-recent first by default. Use the query parameters below to filter and paginate through the log.

HTTP Request

curl "https://api.retreaver.com/api/v4/calls.json?api_key=[api_key]&company_id=1"
Swipe horizontally for full code

Query Parameters

Swipe horizontally to view full table
Parameter Format Default Description
company_id 123456 Return Calls associated with the specified company (you must have access to that company).
created_at_start YYYY-MM-DDTHH:MM:SS+HH:MM Optional. When provided, return only Calls created on or after this timestamp. Format per RFC 3339.
created_at_end YYYY-MM-DDTHH:MM:SS+HH:MM Optional. When provided, return only Calls created on or before this timestamp. Values in the future are clamped to the current time.
sort_by created_at or updated_at created_at Sort the result set by this column. When sorting by updated_at, the order is always forced to desc regardless of the order param.
order asc or desc desc Sort ascending or descending by the sort_by column.
page 1 1 Page number of the result set to return.
per_page 25 25 Number of Calls to return per page (maximum 100).
caller %2B13015236555 Return only Calls from this caller number (URL-encode the +).
client_afid 123456 Return only Calls for the given affiliate (by client_afid).
client_cid 123456 Return only Calls for the given campaign (by client_cid).
client_tid 123456 Return only Calls for the given target (by client_tid).
sub_id 123456 Return only Calls matching the affiliate Sub ID.
call_flow_events true / false false When true, includes a call_flow_events array on each Call describing what happened during the call (IVR choices, routing decisions, timer fires, etc.).

Enumerate through all Calls

First page…

curl "https://api.retreaver.com/api/v4/calls.json?api_key=[api_key]&company_id=1&sort_by=created_at&order=asc&page=1"
Swipe horizontally for full code

Second page…

curl "https://api.retreaver.com/api/v4/calls.json?api_key=[api_key]&company_id=1&sort_by=created_at&order=asc&page=2"
Swipe horizontally for full code

To fetch every Call in your Account, set sort_by=created_at&order=asc and paginate using the page param until an empty array is returned. Sorting by created_at ascending ensures the result set is stable as new calls come in (new calls are appended to later pages rather than shifting existing pages).

If you’re only interested in recently-changed Calls (for example, calls where the conversion status was re-evaluated after the initial connect), sort by updated_at instead.

Enumerate through Calls in a specific date/time range

curl "https://api.retreaver.com/api/v4/calls.json?api_key=[api_key]&company_id=1&created_at_start=2024-01-01T00:00:00+00:00&created_at_end=2024-01-02T00:00:00+00:00&page=1"
Swipe horizontally for full code

Use created_at_start and created_at_end to restrict the result set to a specific window. Both values must be formatted per RFC 3339 and include a timezone offset.

HTTP Request

curl "https://api.retreaver.com/api/v4/calls.json?api_key=[api_key]&company_id=1&created_at_start=2024-01-01T00:00:00+00:00&created_at_end=2024-01-02T00:00:00+00:00&page=1"
Swipe horizontally for full code

Get a specific Call

curl "https://api.retreaver.com/api/v4/calls/f1abfb78-ab8a-4146-9946-8169fbcc6d6c.json?api_key=[api_key]"
Swipe horizontally for full code

The above command returns JSON structured like this:

{
  "call": {
    "uuid": "f1abfb78-ab8a-4146-9946-8169fbcc6d6c",
    "caller": "+13015236555",
    "dialed_number": "+12263399112",
    "status": "finished",
    "total_duration": 14,
    "start_time": "2024-11-04T16:52:18.034Z",
    "end_time": "2024-11-04T16:52:32.882Z",
    "number": {
      "number": "+18886064349",
      "name": "Publisher Joe Number"
    },
    "campaign": {
      "id": 9872,
      "name": "Retreaver Main - Sales & Support"
    },
    "target_group": { "id": 1639, "name": "Retreaver Team" },
    "connected": true,
    "converted": true,
    "revenue": 5.0,
    "payout": 5.0,
    "total_cost": "0.08"
  }
}
Swipe horizontally for full code

Retrieves a single Call by its UUID. The response contains the same fields as the list endpoint.

HTTP Request

curl "https://api.retreaver.com/api/v4/calls/:uuid.json?api_key=[api_key]"
Swipe horizontally for full code

Path Parameters

Swipe horizontally to view full table
Parameter Type Description
uuid string The UUID of the Call. Returned as uuid on any Call object.

Response Fields

The following fields appear on each Call object. Unless noted, fields are present in v4, v3, and v2 (the v1 field list is smaller — see v1).

Caller

Swipe horizontally to view full table
Field Type Description
uuid string Unique identifier for the call. Use this when fetching a single call.
caller string E.164-formatted caller phone number.
caller_number_sent string | null Alternate caller ID sent upstream to the target, when the caller ID was overridden.
caller_zip string | null Postal/ZIP code of the caller, when available.
caller_state string | null State or province of the caller.
caller_city string | null City of the caller.
caller_country string | null ISO country code of the caller.

Timing & Duration

Swipe horizontally to view full table
Field Type Description
status string Lifecycle state of the call (e.g. finished).
start_time datetime When the call first connected to Retreaver.
forwarded_time datetime | null When the call was forwarded to a target. null if the caller was never connected.
end_time datetime | null When the call ended.
total_duration integer Total call duration in seconds (IVR + hold + talk time).
ivr_duration integer Seconds spent in IVR / pre-routing.
hold_duration integer Seconds the caller spent on hold while being connected to a target.
dialed_call_duration integer Seconds of talk time with the target.
billable_minutes integer Minutes the call is billed for (rounded up).
time_to_call_in_seconds integer Seconds between the caller being given the number (e.g. via a tracking page) and dialing it. (v2+)
time_to_connect_in_seconds integer ivr_duration + hold_duration. (v2+)
conversion_seconds integer | null The duration threshold at which this call converted, if applicable.
conversions_determined_at datetime | null When the final conversion state was determined.

Routing

Swipe horizontally to view full table
Field Type Description
dialed_number string The Retreaver Number the caller dialed.
number object (v3+) / string (v1–v2) In v3 and v4, { "number": "+1...", "name": "..." }. In v1/v2 this is a plain E.164 string.
number_id integer Internal ID of the Number. (v2+)
cid string client_cid of the campaign that handled the call.
campaign object (v4 only) { "id": 123, "name": "..." }. Replaces campaign_id and campaign_name from v2/v3.
campaign_id integer (v2–v3 only) Internal campaign ID. Removed in v4 — use campaign.id instead.
campaign_name string (v2–v3 only) Campaign name. Removed in v4 — use campaign.name instead.
system_campaign_id integer Internal campaign ID (kept alongside campaign in v4 for backwards compatibility).
target_id integer | null Internal ID of the target the caller was connected to. (v2+)
system_target_id integer | null System-level target ID.
callpixels_target_id integer | null Legacy alias of system_target_id.
target_name string | null Full name of the target. (v2+)
target_group object { "id": 123, "name": "..." } of the target group. {} if the call was not routed through a group.
tid string | null client_tid of the target.
afid string | null client_afid of the affiliate that sent the call.
system_affiliate_id integer | null Internal affiliate ID.
affiliate_name string | null Full name of the affiliate. (v2+)
sid string | null Affiliate Sub ID.
via string How the call arrived (e.g. inbound-dial).
rescued boolean Whether the call was rescued (routed to a fallback target after the primary target failed).
connected boolean Whether the caller reached a target. (v2+)
hung_up_by string Who ended the call (caller, target, etc.).
keys_pressed array<string> DTMF digits the caller pressed, in order.
upstream_call_uuid string | null UUID of the parent call, if this call was forwarded from another Retreaver call.
downstream_call_uuids array<string> UUIDs of any child calls forwarded out of this one.

Revenue, Payout & Cost

Swipe horizontally to view full table
Field Type Description
revenue number | null Revenue attributed to this call.
payout number | null Payout to the affiliate for this call.
postback_value string | null Value received from a target’s conversion postback, when applicable.
charge_total string Telephony charges for the call.
total_cost string Total cost of the call. (v2+)
profit_gross string revenue − payout − total_cost. (v2+)
profit_net number revenue − payout. (v2+)
converted boolean Whether the call counted as a conversion.
payable boolean Whether the call is payable to the affiliate.
receivable boolean Whether the call is receivable (billable to the buyer).
duplicate boolean Whether this call was deduplicated against a prior call from the same caller.
payable_duplicate boolean Whether payable status was suppressed due to deduplication.
receivable_duplicate boolean Whether receivable status was suppressed due to deduplication.
repeat boolean True if this caller has called any of your Numbers before.
affiliate_repeat boolean True if this caller has called for the same affiliate before.
target_repeat boolean | null True if this caller has previously connected to the same target.
number_repeat boolean True if this caller has called this specific Number before.
network_sale_timer_fired integer | null The seconds value of the network-level sale timer that fired, if any.
affiliate_sale_timer_fired integer | null The seconds value of the affiliate-level sale timer that fired, if any.
target_sale_timer_fired integer | null The seconds value of the target-level sale timer that fired, if any.

Recording, Pixels & Tags

Swipe horizontally to view full table
Field Type Description
recording_url string | null URL of the MP3 recording, when recording is enabled on the campaign.
fired_pixels_count integer How many pixels (webhooks) were fired for this call.
fired_pixels array<object> Individual pixel fire attempts. Each has url, fire_order, batch_uuid, created_at, fired_at, status, webhook_name. (v2+)
tags object Key-value pairs of tags applied to the call (by the caller, by the system, or via Call Data Writing).
visitor_url string | null URL of the visitor that generated the call (when available via a tracking pixel).

Timestamps & Company

Swipe horizontally to view full table
Field Type Description
company_id integer ID of the company that owns the call.
created_at datetime When the call record was created.
updated_at datetime When the call record was last updated.

Calls API v3

V3 accepts the same parameters and returns the same fields as v4, with one difference: campaign is not returned as a nested object — the flat campaign_id and campaign_name fields are returned instead.

What’s new in V3?

Compared to v2, the number property is returned as an object rather than a plain string.

V2

{
  "call": {
    "number": "+18886064349"
  }
}
Swipe horizontally for full code

V3

{
  "call": {
    "number": {
      "number": "+18886064349",
      "name": "Publisher Joe Number"
    }
  }
}
Swipe horizontally for full code

HTTP Request

curl "https://api.retreaver.com/api/v3/calls.json?api_key=[api_key]&company_id=1"
Swipe horizontally for full code
curl "https://api.retreaver.com/api/v3/calls/:uuid.json?api_key=[api_key]"
Swipe horizontally for full code

Calls API v2

V2 introduces a significantly expanded set of fields on top of v1 — affiliate, target, and campaign names; connection status; profit and cost metrics; timing breakdowns; and the fired_pixels array. The number field is still returned as a plain string in v2; see v3 for the nested-object shape.

What’s new in V2?

In addition to all of the attributes returned by V1, this version adds the fields listed in the table below.

Get recent Calls

curl "https://api.retreaver.com/api/v2/calls.json?api_key=[api_key]&company_id=1"
Swipe horizontally for full code

The above command returns JSON structured like this:

[
  {
    "call": {
      "uuid": "f1abfb78-ab8a-4146-9946-8169fbcc6d6c",
      "caller": "+13015236555",
      "caller_number_sent": null,
      "caller_zip": "28379",
      "caller_state": "NC",
      "caller_city": "Rockingham",
      "caller_country": "US",
      "dialed_call_duration": 2,
      "total_duration": 14,
      "ivr_duration": 7,
      "hold_duration": 5,
      "status": "finished",
      "start_time": "2024-11-04T16:52:18.034Z",
      "forwarded_time": "2024-11-04T16:52:25.423Z",
      "end_time": "2024-11-04T16:52:32.882Z",
      "cid": "1",
      "afid": null,
      "sid": null,
      "dialed_number": "+12263399112",
      "revenue": 5.0,
      "payout": 5.0,
      "postback_value": null,
      "network_sale_timer_fired": null,
      "affiliate_sale_timer_fired": null,
      "target_sale_timer_fired": null,
      "hung_up_by": "caller",
      "duplicate": false,
      "payable_duplicate": false,
      "receivable_duplicate": false,
      "callpixels_target_id": 27449,
      "system_target_id": 27449,
      "system_campaign_id": 9872,
      "system_affiliate_id": null,
      "fired_pixels_count": 4,
      "charge_total": "0.08",
      "keys_pressed": ["1"],
      "repeat": true,
      "affiliate_repeat": false,
      "target_repeat": true,
      "number_repeat": true,
      "visitor_url": "https://example.com",
      "company_id": 2,
      "conversions_determined_at": "2024-11-04T16:52:54.744Z",
      "updated_at": "2024-11-04T16:53:00.756Z",
      "created_at": "2024-11-04T16:52:18.177Z",
      "billable_minutes": 1,
      "upstream_call_uuid": null,
      "downstream_call_uuids": [],
      "target_group": { "id": 1639, "name": "Retreaver Team" },
      "recording_url": "https://example.com",
      "number": "+18886064349",
      "converted": true,
      "payable": true,
      "receivable": true,
      "conversion_seconds": null,
      "tid": null,
      "tags": {
        "attempt": "0192f817-6fdc-f8b3-eb07-526dd16e2ade,0192f817-9147-eee3-25ea-e189df86dc6e",
        "geo": "301,us,us-28379,us-nc",
        "id": "0192f817-6fdc-f8b3-eb07-526dd16e2ade,0192f817-9147-eee3-25ea-e189df86dc6e",
        "request_id": "0192f817-6fdc-f8b3-eb07-526dd16e2ade,0192f817-9147-eee3-25ea-e189df86dc6e",
        "status": "success",
        "system_target_id": "27449"
      },
      "fired_pixels": [
        {
          "fired_pixel": {
            "url": "https://example.com",
            "fire_order": 1,
            "batch_uuid": "39d94d6b-639a-486b-bb21-dbba5949dd2e",
            "created_at": "2024-11-04T16:52:55.182Z",
            "fired_at": null,
            "status": "new",
            "webhook_name": null
          }
        },
        {
          "fired_pixel": {
            "url": "https://example.com",
            "fire_order": 0,
            "batch_uuid": "343ccf9b-b3a1-4cd3-b2de-a351dcf40661",
            "created_at": "2024-11-04T16:52:26.948Z",
            "fired_at": "2024-11-04T16:52:26.947Z",
            "status": "fired",
            "webhook_name": "Test Webhook"
          }
        }
      ],
      "via": "inbound-dial",
      "rescued": false,
      "campaign_id": 9872,
      "campaign_name": "Retreaver Main - Sales & Support",
      "number_id": 4906092,
      "target_id": 27449,
      "affiliate_name": null,
      "connected": true,
      "profit_gross": "-0.08",
      "profit_net": 0.0,
      "target_name": "Taylor Anderson - Sales - +12263399112",
      "time_to_call_in_seconds": 168096,
      "time_to_connect_in_seconds": 12,
      "total_cost": "0.08"
    }
  }
]
Swipe horizontally for full code

Provides access to the call log. The call log contains all the Calls which have been made through Numbers under your control.

V2-only fields

Swipe horizontally to view full table
Attribute Format Description
affiliate_name "abcdef" The full name of the affiliate that sent the call.
campaign_id 123456 The ID of the campaign the call was sent to.
campaign_name "abcdef" The name of the campaign the call was sent to.
connected true or false Whether the caller was successfully connected to a target.
number_id 123456 The ID of the number that the call was received on.
profit_gross 0.00 The gross profit on the call. Formula: (revenue) - (payout) - (total cost)
profit_net 0.00 The net profit on the call. Formula: (revenue) - (payout)
target_id 123456 The target that the caller was connected to.
target_name "John Doe" The full name of the target that the caller was connected to.
time_to_call_in_seconds 10 The time it took for the caller to actually make the call.
time_to_connect_in_seconds 10 The time it took for the caller to get connected to a buyer. Formula: (IVR duration) + (hold duration)
total_cost 0.00 The total cost of the call.

HTTP Request

curl "https://api.retreaver.com/api/v2/calls.json?api_key=[api_key]"
Swipe horizontally for full code

Query Parameters

Swipe horizontally to view full table
Parameter Format Default Description
company_id 123456 Return any Calls associated to the specific company IF you have access to that company.
created_at_start YYYY-MM-DDTHH:MM:SS+HH:MM Optional. When provided, return any Calls that were created after this date.
created_at_end YYYY-MM-DDTHH:MM:SS+HH:MM Optional. When provided, return any Calls that were created before this date. Values in the future are clamped to the current time.
sort_by created_at or updated_at created_at Calls will be sorted by this value. If you only want recently updated Calls, sort by updated_at. Note that calls sorted by updated_at will forcefully be returned in desc order even if order parameter is asc.
order asc or desc desc Calls will be sorted in ascending or descending order of their sort_by column.
page 1 1 Page number of the result set to return.
per_page 25 25 Number of Calls to return per page (maximum 100).
caller %2B13015236555 Return only calls from the specified caller number.
client_afid 123456 Return calls for an affiliate.
client_cid 123456 Return calls for a specific campaign.
client_tid 123456 Return calls for a specific target.
sub_id 123456 Return calls for a affiliate Sub ID.
call_flow_events true/false false Returns the call flow events of what happened during the call.

Enumerate through all calls

First page…

curl "https://api.retreaver.com/api/v2/calls.json?api_key=[api_key]&page=1"
Swipe horizontally for full code

Second page…

curl "https://api.retreaver.com/api/v2/calls.json?api_key=[api_key]&page=2"
Swipe horizontally for full code

etc…

To fetch all Calls on your Account, use the sort_by and order params to return your Calls in the order they were created, and then paginate through all your calls.

HTTP Request

curl "https://api.retreaver.com/api/v2/calls.json?api_key=[api_key]&company_id=1&sort_by=created_at&order=asc&page=1"
Swipe horizontally for full code
curl "https://api.retreaver.com/api/v2/calls.json?api_key=[api_key]&company_id=1&sort_by=created_at&order=asc&page=2"
Swipe horizontally for full code

Enumerate through Calls in a specific date/time range

curl "https://api.retreaver.com/api/v2/calls.json?api_key=[api_key]&company_id=1&created_at_start=2016-01-01T00:00:00+00:00&created_at_end=2016-01-02T00:00:00+00:00&page=1"
Swipe horizontally for full code

By passing in created_at_start and created_at_end parameters, you can control the start and end time of Calls returned.

The timestamp should be formatted according to rfc3339.

HTTP Request

curl "https://api.retreaver.com/api/v2/calls.json?api_key=[api_key]&company_id=1&created_at_start=2016-01-01T00:00:00+00:00&created_at_end=2016-01-02T00:00:00+00:00&page=1"
Swipe horizontally for full code

Get a specific Call

curl "https://api.retreaver.com/api/v2/calls/94079290-93f3-4527-9e78-88653aaf3c49.json?api_key=[api_key]"
Swipe horizontally for full code

The above command returns JSON structured like this:

{
  "call": {
    "uuid": "94079290-93f3-4527-9e78-88653aaf3c49",
    "caller": "+13015236555",
    "caller_number_sent": null,
    "caller_zip": "28379",
    "caller_state": "NC",
    "caller_city": "Rockingham",
    "caller_country": "US",
    "dialed_call_duration": 0,
    "total_duration": 43,
    "ivr_duration": 26,
    "hold_duration": 17,
    "status": "finished",
    "start_time": "2024-11-04T16:46:10.400Z",
    "forwarded_time": null,
    "end_time": "2024-11-04T16:46:54.037Z",
    "cid": "1",
    "afid": null,
    "sid": null,
    "dialed_number": "+16477159443",
    "revenue": null,
    "payout": null,
    "postback_value": null,
    "network_sale_timer_fired": null,
    "affiliate_sale_timer_fired": null,
    "target_sale_timer_fired": null,
    "hung_up_by": "caller",
    "duplicate": false,
    "payable_duplicate": false,
    "receivable_duplicate": false,
    "callpixels_target_id": null,
    "system_target_id": null,
    "system_campaign_id": 9872,
    "system_affiliate_id": null,
    "fired_pixels_count": 5,
    "charge_total": "0.07",
    "keys_pressed": ["1"],
    "repeat": true,
    "affiliate_repeat": false,
    "target_repeat": null,
    "number_repeat": true,
    "visitor_url": "https://example.com",
    "company_id": 2,
    "conversions_determined_at": "2024-11-04T16:47:14.698Z",
    "updated_at": "2024-11-04T16:47:14.944Z",
    "created_at": "2024-11-04T16:46:10.547Z",
    "billable_minutes": 1,
    "upstream_call_uuid": null,
    "downstream_call_uuids": [],
    "target_group": {},
    "number": "+18886064349",
    "converted": false,
    "payable": false,
    "receivable": false,
    "conversion_seconds": null,
    "tid": null,
    "tags": {
      "geo": "301,us,us-28379,us-nc",
      "request_id": "0192f811-d35d-85a4-7722-b3e39a2b3b6e,0192f812-0a4b-ab38-b471-e8332fac7ceb",
      "robodial_blacklist": "0",
      "status": "success"
    },
    "fired_pixels": [
      {
        "fired_pixel": {
          "url": "https://example.com",
          "fire_order": 1,
          "batch_uuid": "8530a03a-a661-4247-b80c-d4f3e4a52802",
          "created_at": "2024-11-04T16:47:15.071Z",
          "fired_at": null,
          "status": "new",
          "webhook_name": null
        }
      },
      {
        "fired_pixel": {
          "url": "https://example.com",
          "fire_order": 0,
          "batch_uuid": "dce85836-8b98-4b03-91f6-b29ca9494aa9",
          "created_at": "2024-11-04T16:46:10.937Z",
          "fired_at": "2024-11-04T16:46:10.793Z",
          "status": "fired",
          "webhook_name": "Webhook 1"
        }
      },
      {
        "fired_pixel": {
          "url": "https://example.com",
          "fire_order": 0,
          "batch_uuid": "c1b0c797-00bc-43ae-a5c4-4f58b2aa9278",
          "created_at": "2024-11-04T16:46:24.788Z",
          "fired_at": "2024-11-04T16:46:24.787Z",
          "status": "fired",
          "webhook_name": "Webhook 2"
        }
      },
      {
        "fired_pixel": {
          "url": "https://example.com",
          "fire_order": 0,
          "batch_uuid": "3c117e83-6d94-43fa-971b-25e3599e59f9",
          "created_at": "2024-11-04T16:46:24.920Z",
          "fired_at": "2024-11-04T16:46:24.849Z",
          "status": "fired",
          "webhook_name": "Webhook 3"
        }
      },
      {
        "fired_pixel": {
          "url": "https://example.com",
          "fire_order": 0,
          "batch_uuid": "7023c382-a52c-42f1-9339-a69e03942d5d",
          "created_at": "2024-11-04T16:46:25.874Z",
          "fired_at": "2024-11-04T16:46:25.873Z",
          "status": "fired",
          "webhook_name": "Webhook 4"
        }
      }
    ],
    "via": "inbound-dial",
    "rescued": false,
    "campaign_id": 9872,
    "campaign_name": "Retreaver Main - Sales & Support",
    "number_id": 4906092,
    "target_id": null,
    "affiliate_name": null,
    "connected": false,
    "profit_gross": "-0.07",
    "profit_net": 0,
    "target_name": null,
    "time_to_call_in_seconds": 168463,
    "time_to_connect_in_seconds": 43,
    "total_cost": "0.07"
  }
}
Swipe horizontally for full code

Calls can be accessed by their UUID.

HTTP Request

curl "https://api.retreaver.com/api/v2/calls/addcf985-017e-4962-be34-cf5d55e74afc.json?api_key=[api_key]&company_id=1"
Swipe horizontally for full code

Calls API v1

V1 is the original version of the Calls API. It returns the base set of call fields — caller info, duration, routing, and the recording URL — while v2 and later add computed/additional attributes such as campaign and target names, connection status, profit and timing fields. New integrations should use v4.

Get recent Calls

curl "https://api.retreaver.com/api/v1/calls.json?api_key=[api_key]&company_id=1"
Swipe horizontally for full code

The above command returns JSON structured like this:

[
  {
    "call": {
      "uuid": "addcf985-017e-4962-be34-cf5d55e74afc",
      "caller": "+17195220377",
      "caller_zip": "80920",
      "caller_state": "CO",
      "caller_city": "COLORADO SPRINGS",
      "caller_country": "US",
      "dialed_call_duration": 193,
      "total_duration": 204,
      "status": "finished",
      "start_time": "2012-04-29T12:29:40Z",
      "forwarded_time": "2012-04-29T12:29:51Z",
      "end_time": "2012-04-29T12:32:46Z",
      "cid": "0003",
      "afid": "03994",
      "sid": null,
      "dialed_number": "+18668987878",
      "updated_at": "2012-04-29T12:29:46Z",
      "created_at": "2012-04-29T12:29:40Z",
      "recording_url": "http://callpixels.com/recordings/87d43a5f5c88041687f9fd1bb6a58d6f/call_17192096019_1342303189.mp3"
    }
  },
  {
    "call": {
      "uuid": "8ae0aa38-0173-4e62-5342-cf5d55e74afe",
      "caller": "+14166686981",
      "caller_zip": null,
      "caller_state": "ON",
      "caller_city": "TORONTO",
      "caller_country": "CA",
      "dialed_call_duration": 33,
      "total_duration": 40,
      "status": "finished",
      "start_time": "2012-04-29T12:29:40Z",
      "forwarded_time": "2012-04-29T12:29:51Z",
      "end_time": "2012-04-29T12:32:46Z",
      "cid": "0003",
      "afid": "03994",
      "sid": null,
      "dialed_number": "+18668987878",
      "updated_at": "2012-04-29T12:29:46Z",
      "created_at": "2012-04-29T12:29:40Z",
      "recording_url": "http://callpixels.com/recordings/87d43a5f5c88041687f9fd1bb6a58d6f/call_17192096019_1342303189.mp3"
    }
  }
]
Swipe horizontally for full code

Provides access to the call log. The call log contains all the Calls which have been made through Numbers under your control.

HTTP Request

curl "https://api.retreaver.com/api/v1/calls.json?api_key=[api_key]&company_id=1"
Swipe horizontally for full code

Query Parameters

Swipe horizontally to view full table
Parameter Format Default Description
company_id 123456 Return any Calls associated to the specific company IF you have access to that company.
created_at_start YYYY-MM-DDTHH:MM:SS+HH:MM Optional. When provided, return any Calls that were created after this date.
created_at_end YYYY-MM-DDTHH:MM:SS+HH:MM Optional. When provided, return any Calls that were created before this date. Values in the future are clamped to the current time.
sort_by created_at or updated_at created_at Calls will be sorted by this value. If you only want recently updated Calls, sort by updated_at. Note that calls sorted by updated_at will forcefully be returned in desc order even if order parameter is asc.
order asc or desc desc Calls will be sorted in ascending or descending order of their sort_by column.
page 1 1 Page number of the result set to return.
per_page 25 25 Number of Calls to return per page (maximum 100).
caller %2B13015236555 Return only calls from the specified caller number.
client_afid 123456 Return calls for an affiliate.
client_cid 123456 Return calls for a specific campaign.
client_tid 123456 Return calls for a specific target.
sub_id 123456 Return calls for a affiliate Sub ID.

Enumerate through all calls

First page…

curl "https://api.retreaver.com/api/v1/calls.json?api_key=[api_key]&company_id=1&sort_by=created_at&order=asc&page=1"
Swipe horizontally for full code

Second page…

curl "https://api.retreaver.com/api/v1/calls.json?api_key=[api_key]&company_id=1&sort_by=created_at&order=asc&page=2"
Swipe horizontally for full code

etc…

To fetch all Calls on your Account, use the sort_by and order params to return your Calls in the order they were created, and then paginate through all your calls.

HTTP Request

curl "https://api.retreaver.com/api/v1/calls.json?api_key=[api_key]&company_id=1&sort_by=created_at&order=asc&page=1"
Swipe horizontally for full code
curl "https://api.retreaver.com/api/v1/calls.json?api_key=[api_key]&company_id=1&sort_by=created_at&order=asc&page=2"
Swipe horizontally for full code

Enumerate through Calls in a specific date/time range

curl "https://api.retreaver.com/api/v1/calls.json?api_key=[api_key]&company_id=1&created_at_start=2016-01-01T00:00:00+00:00&created_at_end=2016-01-02T00:00:00+00:00&page=1"
Swipe horizontally for full code

By passing in created_at_start and created_at_end parameters, you can control the start and end time of Calls returned.

The timestamp should be formatted according to rfc3339.

HTTP Request

curl "https://api.retreaver.com/api/v1/calls.json?api_key=[api_key]&company_id=1&created_at_start=2016-01-01T00:00:00+00:00&created_at_end=2016-01-02T00:00:00+00:00&page=1"
Swipe horizontally for full code

Get a specific Call

curl "https://api.retreaver.com/api/v1/calls/addcf985-017e-4962-be34-cf5d55e74afc.json?api_key=[api_key]&company_id=1"
Swipe horizontally for full code

The above command returns JSON structured like this:

{
  "call": {
    "uuid": "addcf985-017e-4962-be34-cf5d55e74afc",
    "caller": "+17195220377",
    "caller_zip": "80920",
    "caller_state": "CO",
    "caller_city": "COLORADO SPRINGS",
    "caller_country": "US",
    "dialed_call_duration": 193,
    "total_duration": 204,
    "status": "finished",
    "start_time": "2012-04-29T12:29:40Z",
    "forwarded_time": "2012-04-29T12:29:51Z",
    "end_time": "2012-04-29T12:32:46Z",
    "cid": "0003",
    "afid": "03994",
    "sid": null,
    "dialed_number": "+18668987878",
    "updated_at": "2012-04-29T12:29:46Z",
    "created_at": "2012-04-29T12:29:40Z",
    "recording_url": "http://callpixels.com/recordings/87d43a5f5c88041687f9fd1bb6a58d6f/call_17192096019_1342303189.mp3"
  }
}
Swipe horizontally for full code

Calls can be accessed by their UUID.

HTTP Request

curl "https://api.retreaver.com/api/v1/calls/addcf985-017e-4962-be34-cf5d55e74afc.json?api_key=[api_key]"
Swipe horizontally for full code

Call Data Writing

Retreaver users can create data posting links that give publishers the ability to apply tags to an inbound caller using call data writing. These tags can be applied at any time, either before or after a call has been processed within a Retreaver campaign.

Call data writing is typically used when you need to apply tags to calls before connecting the caller to a campaign, or before transferring the call to another agent.

Check our guide: Applying Tags to Calls using Call Data Writing

Note

All requests must be made to retreaverdata.com.

Methods

Requests can be made through POST and GET. When using GET, place the params in the URL.

GET

curl "https://retreaverdata.com/data_writing?key=:postback_key_uuid&caller_number=:caller_number&age=39&utm_campaign=auto"
Swipe horizontally for full code

POST

curl -X POST "https://retreaverdata.com/data_writing" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "postback_key_uuid",
    "caller_number": ":caller_number",
    "age": "39",
    "utm_campaign": "auto"
  }'
Swipe horizontally for full code

Example Response with call_uuid

{
  "tag_values": {
    "age": "39",
    "utm_campaign": "auto"
  },
  "call_uuid": "9b653cf0-4835-493b-860c-aed9b7af2a4a",
  "status": "completed call found, tags applied"
}
Swipe horizontally for full code

Example Response with caller_number

{
  "tag_values": {
    "age": "39",
    "utm_campaign": "auto"
  },
  "caller_number": "+3569878933094",
  "status": "call not found, tags stored"
}
Swipe horizontally for full code

HTTP Request

POST/GET https://retreaverdata.com/data_writing

Parameters

Swipe horizontally to view full table
Parameter Type Required Description
key string Yes The UUID of the Postback Key used to authorize this change.
caller_number string Optional The caller number of the Call for which the tags should be applied. This or a call_uuid should be provided.
call_uuid string Optional The UUID of the Call for which the tags should be applied. This or a caller_number should be provided.
:tag_key string Optional Dynamic key:value pairs in the form of ?key1=value1&key2=value2.

Call not found

The DataWriting API allows for tags to be sent before a call comes in. When the call is not found the tags are stored and will be applied when a call from the caller number is received.

Completed call found

When a call is found and is completed the tags are applied.

In progress call found

When a call is in progress, tags can be stored but may not be applied to the call immediately. Instead, they are typically applied the next time they are needed — usually when a routing decision must be made. If no further routing decisions occur while the call remains in progress, the tags are applied at the end of the call.

As a result, it’s possible to use the Data Writing API to set tags on an in-progress call, but not see them immediately reflected in the UI or API. They may only become visible once the call has ended.

Note

If the call has already been routed, the tags will still be applied eventually — but since routing is complete, they will not influence the routing outcome.

Help us improve this article or request new support guides.

Previous

Companies API

Next

Caller Lists API
On this page
Calls API v4
Get recent Calls
Enumerate through all Calls
Enumerate through Calls in a specific date/time range
Get a specific Call
Response Fields
Calls API v3
Calls API v2
Get recent Calls
Enumerate through all calls
Enumerate through Calls in a specific date/time range
Get a specific Call
Calls API v1
Get recent Calls
Enumerate through all calls
Enumerate through Calls in a specific date/time range
Get a specific Call
Call Data Writing
Methods
HTTP Request
Parameters
Call not found
Completed call found
In progress call found