# 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](#calls-api-v4)**, the latest version, for the richest data and best performance. Older versions ([v3](#calls-api-v3), [v2](#calls-api-v2), [v1](#calls-api-v1)) remain available for existing integrations. A quick overview of what each version adds: | 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 ```shell curl "https://api.retreaver.com/api/v4/calls.json?api_key=[api_key]&company_id=1" ``` > [!NOTE] > You can find your API key in your "Account Settings" (top-right menu) > API Access The above command returns JSON structured like this: ```json [ { "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" } } ] ``` 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 ```shell curl "https://api.retreaver.com/api/v4/calls.json?api_key=[api_key]&company_id=1" ``` #### Query Parameters | 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](https://validator.w3.org/feed/docs/error/InvalidRFC3339Date.html). | | 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... ```shell curl "https://api.retreaver.com/api/v4/calls.json?api_key=[api_key]&company_id=1&sort_by=created_at&order=asc&page=1" ``` > Second page... ```shell curl "https://api.retreaver.com/api/v4/calls.json?api_key=[api_key]&company_id=1&sort_by=created_at&order=asc&page=2" ``` 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 ```shell 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" ``` 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](https://validator.w3.org/feed/docs/error/InvalidRFC3339Date.html) and include a timezone offset. #### HTTP Request ```shell 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" ``` ### Get a specific Call ```shell curl "https://api.retreaver.com/api/v4/calls/f1abfb78-ab8a-4146-9946-8169fbcc6d6c.json?api_key=[api_key]" ``` > The above command returns JSON structured like this: ```json { "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" } } ``` Retrieves a single Call by its UUID. The response contains the same fields as the list endpoint. #### HTTP Request ```shell curl "https://api.retreaver.com/api/v4/calls/:uuid.json?api_key=[api_key]" ``` #### Path Parameters | 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](#calls-api-v1)). #### Caller | 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 | 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 | 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` | 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` | UUIDs of any child calls forwarded out of this one. | #### Revenue, Payout & Cost | 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 | 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` | 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](#call-data-writing)). | | visitor_url | `string` \| `null` | URL of the visitor that generated the call (when available via a tracking pixel). | #### Timestamps & Company | 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](#calls-api-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 ```json { "call": { "number": "+18886064349" } } ``` > V3 ```json { "call": { "number": { "number": "+18886064349", "name": "Publisher Joe Number" } } } ``` #### HTTP Request ```shell curl "https://api.retreaver.com/api/v3/calls.json?api_key=[api_key]&company_id=1" ``` ```shell curl "https://api.retreaver.com/api/v3/calls/:uuid.json?api_key=[api_key]" ``` ## 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](#calls-api-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 ```shell curl "https://api.retreaver.com/api/v2/calls.json?api_key=[api_key]&company_id=1" ``` > The above command returns JSON structured like this: ```json [ { "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" } } ] ``` 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 | 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 ```shell curl "https://api.retreaver.com/api/v2/calls.json?api_key=[api_key]" ``` #### Query Parameters | 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... ```shell curl "https://api.retreaver.com/api/v2/calls.json?api_key=[api_key]&page=1" ``` > Second page... ```shell curl "https://api.retreaver.com/api/v2/calls.json?api_key=[api_key]&page=2" ``` > 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 ```shell curl "https://api.retreaver.com/api/v2/calls.json?api_key=[api_key]&company_id=1&sort_by=created_at&order=asc&page=1" ``` ```shell curl "https://api.retreaver.com/api/v2/calls.json?api_key=[api_key]&company_id=1&sort_by=created_at&order=asc&page=2" ``` ### Enumerate through Calls in a specific date/time range ```shell 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" ``` 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](https://validator.w3.org/feed/docs/error/InvalidRFC3339Date.html). #### HTTP Request ```shell 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" ``` ### Get a specific Call ```shell curl "https://api.retreaver.com/api/v2/calls/94079290-93f3-4527-9e78-88653aaf3c49.json?api_key=[api_key]" ``` > The above command returns JSON structured like this: ```json { "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" } } ``` Calls can be accessed by their UUID. #### HTTP Request ```shell curl "https://api.retreaver.com/api/v2/calls/addcf985-017e-4962-be34-cf5d55e74afc.json?api_key=[api_key]&company_id=1" ``` ## 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](#calls-api-v4). ### Get recent Calls ```shell curl "https://api.retreaver.com/api/v1/calls.json?api_key=[api_key]&company_id=1" ``` > The above command returns JSON structured like this: ```json [ { "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" } } ] ``` Provides access to the call log. The call log contains all the Calls which have been made through Numbers under your control. #### HTTP Request ```shell curl "https://api.retreaver.com/api/v1/calls.json?api_key=[api_key]&company_id=1" ``` #### Query Parameters | 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... ```shell curl "https://api.retreaver.com/api/v1/calls.json?api_key=[api_key]&company_id=1&sort_by=created_at&order=asc&page=1" ``` > Second page... ```shell curl "https://api.retreaver.com/api/v1/calls.json?api_key=[api_key]&company_id=1&sort_by=created_at&order=asc&page=2" ``` > 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 ```shell curl "https://api.retreaver.com/api/v1/calls.json?api_key=[api_key]&company_id=1&sort_by=created_at&order=asc&page=1" ``` ```shell curl "https://api.retreaver.com/api/v1/calls.json?api_key=[api_key]&company_id=1&sort_by=created_at&order=asc&page=2" ``` ### Enumerate through Calls in a specific date/time range ```shell 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" ``` 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](https://validator.w3.org/feed/docs/error/InvalidRFC3339Date.html). #### HTTP Request ```shell 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" ``` ### Get a specific Call ```shell curl "https://api.retreaver.com/api/v1/calls/addcf985-017e-4962-be34-cf5d55e74afc.json?api_key=[api_key]&company_id=1" ``` > The above command returns JSON structured like this: ```json { "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" } } ``` Calls can be accessed by their UUID. #### HTTP Request ```shell curl "https://api.retreaver.com/api/v1/calls/addcf985-017e-4962-be34-cf5d55e74afc.json?api_key=[api_key]" ``` ## 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](https://help.retreaver.com/hc/en-us/articles/360034356152-Publisher-Data-Posting-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 ```shell curl "https://retreaverdata.com/data_writing?key=:postback_key_uuid&caller_number=:caller_number&age=39&utm_campaign=auto" ``` > POST ```shell 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" }' ``` > Example Response with call_uuid ```json { "tag_values": { "age": "39", "utm_campaign": "auto" }, "call_uuid": "9b653cf0-4835-493b-860c-aed9b7af2a4a", "status": "completed call found, tags applied" } ``` > Example Response with caller_number ```json { "tag_values": { "age": "39", "utm_campaign": "auto" }, "caller_number": "+3569878933094", "status": "call not found, tags stored" } ``` ### HTTP Request `POST/GET https://retreaverdata.com/data_writing` ### Parameters | 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.