Calls In Progress API¶

Notice: Please contact your CSM or the support team to request access.

The Calls In Progress API is used for interacting with pre-call insights for live calls as part of PreSense. It can retrieve information during a call. Calls become available via the api as soon as they are transferred to the campaign’s destination. Once the call is complete, it is no longer available via the API.

For authentication, use an API token. See Manage API Credentials for details.

Find Calls in Progress¶

Perform a GET request to query calls currently in progress for the specified organization. Sending only the required parameters will return all current calls.

The custom_data field contains the Marketing Data Fields (aka Custom Data Fields) that have values when the call is received. Each custom data field will include the current value and the source of that value. These values can come from your Invoca Tag, values applied to Networks/Advertisers/Campaigns/Promo Numbers, or from data returned by a Real-Time Routing Webhook. If you have Enhanced Caller Profiles (ECP) enabled, the demographics_data field will contain any ECP data that is available for the caller.

Query Parameters¶

Param	Description	Format	Required
organization_type	The type of organization to be used in the request, either Network or Advertiser	String	True
id	The ID of the organization to be used in the request	Number	True
transaction_id	The transaction id for the desired call	String	Optional
external_unique_id	The unique id previously applied to the desired call	String	Optional
calling_phone_number	The caller’s caller ID	We support most phone number formats, for example: 800-555-1234, 8005551234, +18005551234, or 18005551234	Yes, if request includes destination_phone_number
destination_phone_number	The phone number the call was transferred to	We support most phone number formats, for example: 800-555-1234, 8005551234, +18005551234, or 18005551234	Yes, if request includes calling_phone_number

General Fields¶

Below is a general list of data points that are available via the API; some fields may not be available depending on their organization type and/or configuration.

Field	Name in Reports	Description
advertiser_campaign_country	Advertiser Campaign Country	Country of the campaign.
advertiser_campaign_id	Advertiser Campaign ID	Identifier of the advertiser campaign.
advertiser_campaign_id_from_network	Advertiser Campaign ID (Network)	The Campaign ID from the network as set on the advertiser campaign.
advertiser_campaign_name	Advertiser Campaign Name	Name of the campaign.
advertiser_id	Advertiser ID	Identifier of the advertiser.
advertiser_id_from_network	Advertiser ID (Network)	The ID of the advertiser as set by the network.
advertiser_name	Advertiser Name	Name of the advertiser.
affiliate_campaign_id_from_network	Affiliate Campaign ID (Network)	The Campaign ID from the network as set for the affiliate.
affiliate_commissions_ranking	Affiliate Commissions Ranking	Ranking based on affiliate commissions.
affiliate_conversion_rate_ranking	Affiliate Conversion Rate Ranking	Ranking based on affiliate conversion rate.
affiliate_id	Affiliate ID	Identifier of the affiliate.
affiliate_id_from_network	Affiliate ID (Network)	The ID of the affiliate as set by the network.
affiliate_name	Affiliate Name	Name of the affiliate.
affiliate_volume_ranking	Affiliate Volume Ranking	Ranking based on affiliate volume.
bridge_start_time	Bridge Start Time	Time when the call was bridged to the destination phone number. This is effectively the call start time.
call_record_id	Call Record ID	Identifier of the call record.
call_status	Call Status	Status of the call.
called_phone_number	Called Phone Number	Phone number that was called.
calling_phone_number	Calling Phone Number	Caller ID. Formatted as 12 characters like 866-555-1234.
city	City	City where call originated.
destination_phone_number	Destination Phone Number	The phone number where the call was transferred to (useful if an IVR transfers to multiple destinations). Up-to 20 character string, can contain numeric characters (i.e. 0-9) and the following additional characters: ‘-’, ‘#’, ‘*’, ‘x’, and ‘,’. ‘
external_unique_id	External Unique ID	Unique identifier from an external system.
keypress_1	Keypress 1	Name of the first key that pressed.
keypress_2	Keypress 2	Name the second key that was pressed.
keypress_3	Keypress 3	Name of the third key that was pressed.
keypress_4	Keypress 4	Name of the fourth key that was pressed.
keypresses	Keypresses	List of unique keynames that were pressed during the call.
media_type	Media Type	Media type of the call course.
phone_type	Phone Type	Type of phone used.
promo_number_description	Promo Number Description	Additional details about the transaction source.
promo_number_id	Promo Number ID	The Promo Number ID from the network.
qualified_regions	Qualified Regions	The list of regions that that the caller matched.
region	Region	Region (state, province or country) where transaction originated.
repeat_calling_phone_number	Repeat Caller	Whether the call was a repeat call. Repeat call detection is not applied to shared or unavailable caller IDs.
source	Source	Source of the call.
start_time	Start Time	Start of the call in the API user’s time zone, followed by offset from GMT.
transaction_id	Transaction ID	Globally unique identifier for this transaction. Up-to 32 character string, can contain alphanumeric characters (i.e. 0-9A-Z) and the -. This is the Primary Key of the results.
verified_zip_code	Verified ZIP Code	Zip Code entered by callers when prompted during call treatment.
zip_code	ZIP Code	Customer’s zip code as given to the call center.

Examples¶

GET

/calls_in_progress/current_calls

Get all available calls in progress for the specified organization

Example

Get all available calls in progress for the specified organization. Be sure to use your own organization_type and id.

Endpoint:

https://invoca.net/api/2022-08-01/calls_in_progress/current_calls.json?id=<organization_id>&organization_type=<organization_type>

Response Code: 200

Response Body:

{
  "current_calls": [
    {
      "transaction_id": "ABCD1234-ABCD1234",
      "call_status": "bridged",
      "external_unique_id": null,
      "calling_phone_number": "+15559999999",
      "destination_phone_number": "+18555595599",
      "called_phone_number": "+18557174046",
      "bridge_start_time": "2023-04-03T16:02:36-07:00",
      "call_record_id": "Z6E5-C7397356976E",
      "phone_type": "Mobile",
      "advertiser_campaign_country": "USA",
      "advertiser_campaign_id": "SampleCampaignID-123",
      "advertiser_campaign_id_from_network": "NetworkCampaignID-456",
      "advertiser_campaign_name": "Sample Campaign Name",
      "advertiser_id": "AdvertiserID-789",
      "advertiser_id_from_network": "NetworkAdvertiserID-012",
      "advertiser_name": "Sample Advertiser Name",
      "affiliate_campaign_id_from_network": "NetworkAffiliateCampaignID-345",
      "affiliate_commissions_ranking": "Top 10%",
      "affiliate_conversion_rate_ranking": "Top 20%",
      "affiliate_id": "AffiliateID-678",
      "affiliate_id_from_network": "NetworkAffiliateID-901",
      "affiliate_name": "Sample Affiliate Name",
      "affiliate_volume_ranking": "Top 5%",
      "city": "New York",
      "destination_phone_number": "+18555555555",
      "external_unique_id": "ExternalID-234",
      "keypress_1": "1",
      "keypress_2": "2",
      "keypress_3": "3",
      "keypress_4": "4",
      "key presses": "1,2,3,4",
      "media_type": "Online",
      "phone_type": "Mobile",
      "promo_number_description": "Sample Promo Description",
      "promo_number_id": "PromoID-567",
      "qualified_regions": "East Coast",
      "region": "North East",
      "source": "Web",
      "start_time": "2023-04-03T16:00:00-07:00",
      "transaction_id": "TransactionID-890",
      "verified_zip_code": "10001",
      "zip_code": "10001"
      "custom_data": {
            "utm_source": {
                "value": "google.com",
                "source": "VirtualLine"
            },
            "calling_page": {
                "value": "https://www.doggydaycare.com/boarding",
                "source": "DynamicAttribution"
            },
            "g_cid": {
                "value": "asdf-1234-zxcv-5678",
                "source": "DynamicAttribution"
            },
            "channel": {
                "value": "SEM",
                "source": "DynamicAttribution"
            },
            "lead_type": {
                "value": "StoreCall",
                "source": "VirtualLine"
            },
            "demographics_data": {}
        }
    },
    {
      "transaction_id": "ABCD5678-ABCD5678",
      "call_status": "bridged",
      "external_unique_id": null,
      "calling_phone_number": "+15559998888",
      "destination_phone_number": "+18555595599",
      "called_phone_number": "+18557174046",
      "bridge_start_time": "2023-04-03T16:05:42-07:00",
      "call_record_id": "Z6E5-C7397356576G",
      "phone_type": "Mobile",
      "advertiser_campaign_country": "USA",
      "advertiser_campaign_id": "SampleCampaignID-123",
      "advertiser_campaign_id_from_network": "NetworkCampaignID-456",
      "advertiser_campaign_name": "Sample Campaign Name",
      "advertiser_id": "AdvertiserID-789",
      "advertiser_id_from_network": "NetworkAdvertiserID-012",
      "advertiser_name": "Sample Advertiser Name",
      "affiliate_campaign_id_from_network": "NetworkAffiliateCampaignID-345",
      "affiliate_commissions_ranking": "Top 10%",
      "affiliate_conversion_rate_ranking": "Top 20%",
      "affiliate_id": "AffiliateID-678",
      "affiliate_id_from_network": "NetworkAffiliateID-901",
      "affiliate_name": "Sample Affiliate Name",
      "affiliate_volume_ranking": "Top 5%",
      "city": "New York",
      "destination_phone_number": "+18555555555",
      "external_unique_id": "ExternalID-234",
      "keypress_1": "1",
      "keypress_2": "2",
      "keypress_3": "3",
      "keypress_4": "4",
      "key presses": "1,2,3,4",
      "media_type": "Online",
      "phone_type": "Mobile",
      "promo_number_description": "Sample Promo Description",
      "promo_number_id": "PromoID-567",
      "qualified_regions": "East Coast",
      "region": "North East",
      "source": "Web",
      "start_time": "2023-04-03T16:00:00-07:00",
      "transaction_id": "TransactionID-890",
      "verified_zip_code": "10001",
      "zip_code": "10001"
      "custom_data": {
            "utm_source": {
                "value": "google.com",
                "source": "VirtualLine"
            },
            "demographics_data": {}
        }
    }
  ]
}

GET

/calls_in_progress/current_calls

Get calls in progress by transaction id

Example

Get calls in progress for transaction id ABCD1234-ABCD1234. Be sure to use your own organization_type and id.

current_calls will be ordered by bridge_start_time, most recent first.

Endpoint:

https://invoca.net/api/2022-08-01/calls_in_progress/current_calls.json?id=<organization_id>&organization_type=<organization_type>&transaction_id=ABCD1234-ABCD1234

Parameters: transaction_id is required for this request

Response Code: 200

Response Body:

{
  "current_calls": [
    {
      "transaction_id": "ABCD1234-ABCD1234",
      "call_status": "bridged",
      "external_unique_id": null,
      "calling_phone_number": "+15559999999",
      "destination_phone_number": "+18555595599",
      "called_phone_number": "+18557174046",
      "bridge_start_time": "2023-04-03T16:02:36-07:00",
      "call_record_id": "Z6E5-C7397356976E",
      "phone_type": "Mobile",
      "advertiser_campaign_country": "USA",
      "advertiser_campaign_id": "SampleCampaignID-123",
      "advertiser_campaign_id_from_network": "NetworkCampaignID-456",
      "advertiser_campaign_name": "Sample Campaign Name",
      "advertiser_id": "AdvertiserID-789",
      "advertiser_id_from_network": "NetworkAdvertiserID-012",
      "advertiser_name": "Sample Advertiser Name",
      "affiliate_campaign_id_from_network": "NetworkAffiliateCampaignID-345",
      "affiliate_commissions_ranking": "Top 10%",
      "affiliate_conversion_rate_ranking": "Top 20%",
      "affiliate_id": "AffiliateID-678",
      "affiliate_id_from_network": "NetworkAffiliateID-901",
      "affiliate_name": "Sample Affiliate Name",
      "affiliate_volume_ranking": "Top 5%",
      "city": "New York",
      "destination_phone_number": "+18555555555",
      "external_unique_id": "ExternalID-234",
      "keypress_1": "1",
      "keypress_2": "2",
      "keypress_3": "3",
      "keypress_4": "4",
      "key presses": "1,2,3,4",
      "media_type": "Online",
      "phone_type": "Mobile",
      "promo_number_description": "Sample Promo Description",
      "promo_number_id": "PromoID-567",
      "qualified_regions": "East Coast",
      "region": "North East",
      "source": "Web",
      "start_time": "2023-04-03T16:00:00-07:00",
      "transaction_id": "TransactionID-890",
      "verified_zip_code": "10001",
      "zip_code": "10001"
      "custom_data": {
            "utm_source": {
                "value": "google.com",
                "source": "VirtualLine"
            },
            "calling_page": {
                "value": "https://www.doggydaycare.com/boarding",
                "source": "DynamicAttribution"
            },
            "g_cid": {
                "value": "asdf-1234-zxcv-5678",
                "source": "DynamicAttribution"
            },
            "channel": {
                "value": "SEM",
                "source": "DynamicAttribution"
            },
            "lead_type": {
                "value": "StoreCall",
                "source": "VirtualLine"
            },
            "demographics_data": {}
        }
    }
  ]
}

GET

/calls_in_progress/current_calls

Get calls in progress by calling and destination phone numbers

Example

Get calls in progress for the calling phone number 530-999-9999 and destination phone number 855-559-5599. Be sure to use your own organization_type and id.

This example is for an organization with Enhanced Caller Profiles enabled, so the demographics data is included in the response.

Endpoint:

https://invoca.net/api/2022-08-01/calls_in_progress/current_calls.json?id=<organization_id>&organization_type=<organization_type>&calling_phone_number=5309999999&destination_phone_number=8555595599

Parameters: calling_phone_number and destination_phone_number are required for this request

Response Code: 200

Response Body:

{
  "current_calls": [
    {
      "transaction_id": "ABCD1234-ABCD1234",
      "call_status": "bridged",
      "external_unique_id": null,
      "calling_phone_number": "+15309999999",
      "destination_phone_number": "+18555595599",
      "called_phone_number": "+18557174046",
      "bridge_start_time": "2023-04-03T16:02:36-07:00",
      "call_record_id": "Z6E5-C7397356976E",
      "phone_type": "Mobile",
      "advertiser_campaign_country": "USA",
      "advertiser_campaign_id": "SampleCampaignID-123",
      "advertiser_campaign_id_from_network": "NetworkCampaignID-456",
      "advertiser_campaign_name": "Sample Campaign Name",
      "advertiser_id": "AdvertiserID-789",
      "advertiser_id_from_network": "NetworkAdvertiserID-012",
      "advertiser_name": "Sample Advertiser Name",
      "affiliate_campaign_id_from_network": "NetworkAffiliateCampaignID-345",
      "affiliate_commissions_ranking": "Top 10%",
      "affiliate_conversion_rate_ranking": "Top 20%",
      "affiliate_id": "AffiliateID-678",
      "affiliate_id_from_network": "NetworkAffiliateID-901",
      "affiliate_name": "Sample Affiliate Name",
      "affiliate_volume_ranking": "Top 5%",
      "city": "New York",
      "destination_phone_number": "+18555555555",
      "external_unique_id": "ExternalID-234",
      "keypress_1": "1",
      "keypress_2": "2",
      "keypress_3": "3",
      "keypress_4": "4",
      "key presses": "1,2,3,4",
      "media_type": "Online",
      "phone_type": "Mobile",
      "promo_number_description": "Sample Promo Description",
      "promo_number_id": "PromoID-567",
      "qualified_regions": "East Coast",
      "region": "North East",
      "source": "Web",
      "start_time": "2023-04-03T16:00:00-07:00",
      "transaction_id": "TransactionID-890",
      "verified_zip_code": "10001",
      "zip_code": "10001"
      "custom_data": {
            "utm_source": {
                "value": "google.com",
                "source": "VirtualLine"
            },
            "calling_page": {
                "value": "https://www.doggydaycare.com/boarding",
                "source": "DynamicAttribution"
            },
            "g_cid": {
                "value": "asdf-1234-zxcv-5678",
                "source": "DynamicAttribution"
            },
            "channel": {
                "value": "SEM",
                "source": "DynamicAttribution"
            },
            "lead_type": {
                "value": "StoreCall",
                "source": "VirtualLine"
            },
            "demographics_data": {
                "display_name_data_append": "John Doe",
                "first_name_data_append": "John",
                "last_name_data_append": "Doe",
                "age_range_data_append": "",
                "gender_data_append": "Male",
                "address_type_data_append": "Street or Residential Address",
                "address_full_street_data_append": "1234 N Main St",
                "address_city_data_append": "Fresno",
                "address_state_data_append": "CA",
                "address_zip_data_append": "93703",
                "address_country_data_append": "",
                "carrier_data_append": "New Cingular Wireless Pcs, Llc",
                "line_type_data_append": "Mobile",
                "is_prepaid_data_append": false,
                "primary_email_address_data_append": "",
                "linked_email_addresses_data_append": "",
                "household_income_data_append": "30k-40k",
                "marital_status_data_append": "",
                "home_owner_status_data_append": "",
                "home_market_value_data_append": "",
                "length_of_residence_years_data_append": "6 years",
                "occupation_data_append": "",
                "education_data_append": "",
                "has_children_data_append": true,
                "high_net_worth_data_append": null
            }
        }
    }
  ]
}

GET

/calls_in_progress/current_calls

Get calls in progress by external unique id

Example

Get calls in progress for the External Unique ID mycalls00001. Be sure to use your own organization_type and id.

Endpoint:

https://invoca.net/api/2022-08-01/calls_in_progress/current_calls.json?id=<organization_id>&organization_type=<organization_type>&external_unique_id=mycalls00001

Parameters: external_unique_id is required for this request

Response Code: 200

Response Body:

{
  "current_calls": [
    {
      "transaction_id": "ABCD1234-ABCD1234",
      "call_status": "bridged",
      "external_unique_id": "mycalls00001",
      "calling_phone_number": "+15559999999",
      "destination_phone_number": "+18555595599",
      "called_phone_number": "+18557174046",
      "bridge_start_time": "2023-04-03T16:02:36-07:00",
      "call_record_id": "Z6E5-C7397356976E",
      "phone_type": "Mobile",
      "advertiser_campaign_country": "USA",
      "advertiser_campaign_id": "SampleCampaignID-123",
      "advertiser_campaign_id_from_network": "NetworkCampaignID-456",
      "advertiser_campaign_name": "Sample Campaign Name",
      "advertiser_id": "AdvertiserID-789",
      "advertiser_id_from_network": "NetworkAdvertiserID-012",
      "advertiser_name": "Sample Advertiser Name",
      "affiliate_campaign_id_from_network": "NetworkAffiliateCampaignID-345",
      "affiliate_commissions_ranking": "Top 10%",
      "affiliate_conversion_rate_ranking": "Top 20%",
      "affiliate_id": "AffiliateID-678",
      "affiliate_id_from_network": "NetworkAffiliateID-901",
      "affiliate_name": "Sample Affiliate Name",
      "affiliate_volume_ranking": "Top 5%",
      "city": "New York",
      "destination_phone_number": "+18555555555",
      "external_unique_id": "ExternalID-234",
      "keypress_1": "1",
      "keypress_2": "2",
      "keypress_3": "3",
      "keypress_4": "4",
      "key presses": "1,2,3,4",
      "media_type": "Online",
      "phone_type": "Mobile",
      "promo_number_description": "Sample Promo Description",
      "promo_number_id": "PromoID-567",
      "qualified_regions": "East Coast",
      "region": "North East",
      "source": "Web",
      "start_time": "2023-04-03T16:00:00-07:00",
      "transaction_id": "TransactionID-890",
      "verified_zip_code": "10001",
      "zip_code": "10001"
      "custom_data": {
            "utm_source": {
                "value": "google.com",
                "source": "VirtualLine"
            },
            "calling_page": {
                "value": "https://www.doggydaycare.com/boarding",
                "source": "DynamicAttribution"
            },
            "g_cid": {
                "value": "asdf-1234-zxcv-5678",
                "source": "DynamicAttribution"
            },
            "channel": {
                "value": "SEM",
                "source": "DynamicAttribution"
            },
            "lead_type": {
                "value": "StoreCall",
                "source": "VirtualLine"
            },
            "demographics_data": {}
        }
    }
  ]
}

Using the API for Attribution¶

For customers looking to enhance attribution accuracy, the API offers a streamlined payload with Invoca call identifiers, including the Transaction Id and Call Record Id for Exact Match Attribution. By utilizing these identifiers, customers can avoid the need for fuzzy matching of calls when attributing data via Invoca APIs. This is particularly advantageous for those who often deal with repeat callers.

Notice: When leveraging the API for this attribution-focused use case, customers will not receive any pre-call data and will not be obligated to purchase PreSense. Both use cases utilize the same endpoint, and the API accepts the same query parameters, irrespective of whether pre-call data is present.

Examples¶

GET

/calls_in_progress

Retrieve a specific call by Transaction ID

Example

Get calls in progress for transaction id ABCD1234-ABCD1234. Be sure to use your own organization_type and id.

current_calls will be ordered by bridge_start_time, most recent first.

Endpoint:

https://invoca.net/api/2022-08-01/calls_in_progress/current_calls.json?id=<organization_id>&organization_type=<organization_type>&transaction_id=ABCD1234-ABCD1234

Parameters: transaction_id is required for this request

Response Code: 200

Response Body:

{
  "current_calls": [
    {
      "transaction_id": "ABCD1234-ABCD1234",
      "call_status": "bridged",
      "external_unique_id": null,
      "calling_phone_number": "+15559999999",
      "destination_phone_number": "+18555595599",
      "called_phone_number": "+18557174046",
      "bridge_start_time": "2023-04-03T16:02:36-07:00",
      "call_record_id": "Z6E5-C7397356976E",
      "phone_type": "Mobile",
    }
  ]
}

Response Codes¶

Remember to check the HTTP status code returned. This helps greatly when debugging.

Status Code	Meaning
200 OK	Query was successful. Results, if any, will be returned.
401 Unauthorized	Invalid or missing oauth token.