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 accessible using the API credentials generated on the platform.

Find Calls in Progress¶

Query current calls in progress for a given organization.

Supported types of requests: GET

Query Parameters¶

Param	Description	Format	Required
id	The ID of the organization to be used in the request	Number	True
organization_type	The type of organization to be used in the request. Available types: [Network, Advertiser]. Capitalization is required for this param.	String	True
transaction_id	Unique transaction ID	String	Optional
external_unique_id	Unique ID for call from external system	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¶

GET

/calls_in_progress/current_calls

Get all available calls in progress for an organization

Example

Get all available calls in progress for a given organization

Endpoint:

https://mynetwork.invoca.net/api/2022-08-01/calls_in_progress/current_calls.json?oauth_token=wXB4Dpwtyvduy1HRKn-WfD5FSUh9P1hx&id=25&organization_type=network

Format: application/json

Response Code: 200

Response Body:

{
  "current_calls": [
    {
      "transaction_id": "01FMTK644Z9D-3FPEY1REX8JSZB",
      "call_status": "bridged",
      "external_unique_id": null,
      "calling_phone_number": "+15309999999",
      "destination_phone_number": "+18555595599",
      "call_start_time_utc": "2022-12-10T13:45:00.000Z",
      "transfer_start_time_utc": "2022-12-10T13:49:00.000Z",
      "custom_data": {}
    }
  ]
}

GET

/calls_in_progress/current_calls

Get calls in progress by transaction id

Example

Get calls in progress for the given transaction id 01FMTK644Z9D-3FPEY1REX8JSZB.

current_calls will be ordered by transfer_start_time_utc, most recent first.

Endpoint:

https://mynetwork.invoca.net/api/2022-08-01/calls_in_progress/current_calls.json?oauth_token=wXB4Dpwtyvduy1HRKn-WfD5FSUh9P1hx&id=25&organization_type=network&transaction_id=01FMTK644Z9D-3FPEY1REX8JSZB

Format: application/json

Response Code: 200

Response Body:

{
  "current_calls": [
    {
      "transaction_id": "01FMTK644Z9D-3FPEY1REX8JSZB",
      "call_status": "bridged",
      "external_unique_id": null,
      "calling_phone_number": "+15309999999",
      "destination_phone_number": "+18555595599",
      "call_start_time_utc": "2022-12-10T13:45:00.000Z",
      "transfer_start_time_utc": "2022-12-10T13:49:00.000Z",
      "custom_data": {}
    }
  ]
}

Response Code: 401

Response Body:

{"error": "NotAuthorized"}

GET

/calls_in_progress/current_calls

Get calls in progress by phone numbers of a call

Example

Get calls in progress for the calling_phone_number and destination_phone_number.

Endpoint:

https://mynetwork.invoca.net/api/2022-08-01/calls_in_progress/current_calls.json?oauth_token=wXB4Dpwtyvduy1HRKn-WfD5FSUh9P1hx&id=25&organization_type=network&calling_phone_number=15309999999&destination_phone_number=18555595599

Format: application/json

Response Code: 200

Response Body:

{
  "current_calls": [
    {
      "transaction_id": "01FMTK644Z9D-3FPEY1REX8JSZB",
      "call_status": "bridged",
      "external_unique_id": null,
      "calling_phone_number": "+15309999999",
      "destination_phone_number": "+18555595599",
      "call_start_time_utc": "2022-12-10T13:45:00.000Z",
      "transfer_start_time_utc": "2022-12-10T13:49:00.000Z",
      "custom_data": {}
    }
  ]
}

Response Code: 404

Response Body:

{"error": "RecordNotFound"}

GET

/calls_in_progress/current_calls

Get calls in progress by external unique id of a call

Example

Get calls in progress for the given External Unique ID of a Call 0ea32dd2-fed2-43fb-be8e-e56674c33900.

Endpoint:

https://mynetwork.invoca.net/api/2022-08-01/calls_in_progress/current_calls.json?oauth_token=wXB4Dpwtyvduy1HRKn-WfD5FSUh9P1hx&id=25&organization_type=network&external_unique_id=0ea32dd2-fed2-43fb-be8e-e56674c33900

Format: application/json

Response Code: 200

Response Body:

{
  "current_calls": [
    {
      "transaction_id": "01FMTK644Z9D-3FPEY1REX8JSZB",
      "call_status": "bridged",
      "external_unique_id": "0ea32dd2-fed2-43fb-be8e-e56674c33900",
      "calling_phone_number": "+15309999999",
      "destination_phone_number": "+18555595599",
      "call_start_time_utc": "2022-12-10T13:45:00.000Z",
      "transfer_start_time_utc": "2022-12-10T13:49:00.000Z",
      "custom_data": {
        "GCLID": { "value": "123-456", "source": "DynamicAttribution" },
        "SKU": { "value": "CM101-R", "source": "DynamicAttribution" }
      }
    }
  ]
}

Update a Call in Progress¶

Update certain aspects of a Call that is currently in progress

Supported types of requests: PUT and POST

Query Parameters¶

Param	Description	Format	Required
id	The ID of the organization to be used in the request	Number	True
organization_type	The type of organization to be used in the request. Available types: [Network, Advertiser]. Capitalization is required for this param.	String	True
transaction_id	Unique transaction ID	String	Optional, if using external_unique_id
external_unique_id	Unique ID for call from external system	String	Optional, if using transaction_id

Fields Available for Updates¶

external_unique_id

custom_data (additions/updates only, no removal)

Examples¶

PUT

/calls_in_progress

Update a call's external unique id

Example

This example uses PUT requests, but we will also accept POST requests with the same request format (JSON).

Example of updating a call’s external unique id:

Endpoint:

https://mynetwork.invoca.net/api/2022-08-01/calls_in_progress.json?oauth_token=wXB4Dpwtyvduy1HRKn-WfD5FSUh9P1hx&id=25&organization_type=network&transaction_id=01FMTK644Z9D-3FPEY1REX8JSZB

Parameters: transaction_id is required for this request

Request Body:

{
  "call_in_progress": {
    "external_unique_id": "0ea32dd2-fed2-43fb-be8e-e56674c33900"
  }
}

Response Code: 200

Response Body:

{
  "current_call": {
    "transaction_id": "01FMTK644Z9D-3FPEY1REX8JSZB",
    "external_unique_id": "0ea32dd2-fed2-43fb-be8e-e56674c33900",
    "calling_phone_number": "+15309999999",
    "destination_phone_number": "+18555595599",
    "call_start_time_utc": "2022-12-10T13:45:00.000Z",
    "transfer_start_time_utc": "2022-12-10T13:49:00.000Z",
    "call_status": "bridged"
  }
}

PUT

/calls_in_progress

Update a call's custom data

Example

This example uses PUT requests, but we will also accept POST requests with the same request format (JSON).

Example of updating a call’s Custom Data:

Endpoint:

https://mynetwork.invoca.net/api/2022-08-01/calls_in_progress.json?oauth_token=wXB4Dpwtyvduy1HRKn-WfD5FSUh9P1hx&id=25&organization_type=network&transaction_id=01FMTK644Z9D-3FPEY1REX8JSZB

Parameters: transaction_id OR external_unique_id is required for this request

Request Body:

{
  "call_in_progress": {
    "custom_data": [
        {"name": "Call Disposition", "value": "CUSTOMER_HANGUP"}
    ]
  }
}

Response Code: 200

Response Body:

{
  "current_call": {
    "transaction_id": "01FMTK644Z9D-3FPEY1REX8JSZB",
    "external_unique_id": "0ea32dd2-fed2-43fb-be8e-e56674c33900",
    "calling_phone_number": "+15309999999",
    "destination_phone_number": "+18555595599",
    "call_start_time_utc": "2022-12-10T13:45:00.000Z",
    "transfer_start_time_utc": "2022-12-10T13:49:00.000Z",
    "call_status": "bridged"
  }
}