Calls In Progress API

Notice: The CallsInProgress API is in beta. 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 and set custom data values 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.

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 - can only be set via the Calls In Progress API 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

Examples

Example

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

Endpoint:

https://invoca.net/api/2022-08-01/calls_in_progress/current_calls.json?oauth_token=<oauth_token>&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",
      "phone_type": "Mobile",
      "custom_data": {
            "utm_source": {
                "value": "google.com",
                "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",
      "phone_type": "Mobile",
      "custom_data": {
            "utm_source": {
                "value": "google.com",
                "source": "VirtualLine"
            },
            "demographics_data": {}
        }
    }
  ]
}

Example

Get calls in progress for transaction id ABCD1234-ABCD1234. Be sure to use your own oauth_token, 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?oauth_token=<oauth_token>&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",
      "phone_type": "Mobile",
      "custom_data": {
            "utm_source": {
                "value": "google.com",
                "source": "VirtualLine"
            },
            "demographics_data": {}
        }
    }
  ]
}

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 oauth_token, 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?oauth_token=<oauth_token>&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",
      "phone_type": "Mobile",
      "custom_data": {
            "utm_source": {
                "value": "google.com",
                "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
            }
        }
    }
  ]
}

Example

Get calls in progress for the External Unique ID mycalls00001. Note: External Unique ID must be set by using the Update function of this API before you can use it to look up a call. Be sure to use your own oauth_token, organization_type and id.

Endpoint:

https://invoca.net/api/2022-08-01/calls_in_progress/current_calls.json?oauth_token=<oauth_token>&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",
      "phone_type": "Mobile",
      "custom_data": {
            "utm_source": {
                "value": "google.com",
                "source": "VirtualLine"
            },
            "demographics_data": {}
        }
    }
  ]
}

Update a Call in Progress

Update custom data values and set an external identifier to be used for subsequent API requests for a Call that is currently in progress.

Supported types of requests: PUT and POST

Request body should be JSON formatted.

Fields Available for Update

external_unique_id - add a unique ID to the call, usually from another system

custom_data - populate Marketing Data Fields (aka Custom Data Fields) in the Invoca platform

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 if using external_unique_id
external_unique_id The unique id previously applied to the desired call - can only be set via the Calls In Progress API String Optional if using transaction_id

Examples

Example

Update the call currently in progress whose transaction ID is ABCD1234-ABCD1234. Set the external unique ID to mycalls00001.

This example uses PUT requests, but we will also accept POST requests with the same request format (JSON). Be sure to use your own oauth_token, organization_type and id.

Endpoint:

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

Parameters: transaction_id is required for this request

Request Body:

{
  "call_in_progress": {
    "external_unique_id": "mycalls00001"
  }
}

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",
      "phone_type": "Mobile",
      "custom_data": {
            "utm_source": {
                "value": "google.com",
                "source": "VirtualLine"
            },
            "demographics_data": {}
        }
    }
  ]
}

Example

Update the value of a custom data field for the call whose transaction ID is ABCD1234-ABCD1234.

Note: You will not see the new custom data field value in the response or in subsequent queries using this API.

This example uses PUT requests, but we will also accept POST requests with the same request format (JSON). Be sure to use your own oauth_token, organization_type and id.

Endpoint:

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

Parameters: transaction_id is required for this request

Request Body:

{
  "call_in_progress": {
    "custom_data": [
        {"name": "<custom_data_field_name>", "value": "<desired_value>"}
    ]
  }
}

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",
      "phone_type": "Mobile",
      "custom_data": {
            "utm_source": {
                "value": "google.com",
                "source": "VirtualLine"
            },
            "demographics_data": {}
        }
    }
  ]
}

Example

Update the value of a custom data field for the call whose external unique ID is mycalls00001.

Note: You will not see the new custom data field value in the response or in subsequent queries using this API.

This example uses PUT requests, but we will also accept POST requests with the same request format (JSON). Be sure to use your own oauth_token, organization_type and id.

Endpoint:

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

Parameters: external_unique_id is required for this request

Request Body:

{
  "call_in_progress": {
    "custom_data": [
        {"name": "<custom_data_field_name>", "value": "<desired_value>"}
    ]
  }
}

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",
      "phone_type": "Mobile",
      "custom_data": {
            "utm_source": {
                "value": "google.com",
                "source": "VirtualLine"
            },
            "demographics_data": {}
        }
    }
  ]
}

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.
202 Accepted Only applicable for update requests. The update was successful.
401 Unauthorized Invalid or missing oauth token.
404 Not Found Only applicable for update requests. The call specified via transaction_id or external_unique_id was not found.