Understanding Zoom Phone call logs

Access and read Zoom Phone call logs using REST API.

List call logs

The Zoom Phone API offers two endpoints to get a list of call logs:

  • Get account's call logs
    • Administrator-level API that shows all call logs on the account
    • Available to JWT and account-level oAuth apps with phone:read:admin scope
    • Get account's call logs API
  • Get user's call logs
    • User-level API with a user-centric response
    • Available to account-level OAuth and JWT apps with phone:read:admin scope, and user-level OAuth apps with phone:read scope
    • Get user's call logs API

Both API return a list of call log records. The response to the Get user's call logs API is limited to the request user's perspective. As such, it does not always contain all information about a call for certain events that happened before the call was routed to that particular user. Therefore, for purposes of full call accounting and analytics, this discussion will focus on the use of the Get account's call logs API.

Interpret the API response of Get account's call logs

The API returns a JSON array that includes the top-level data for each call record. For outbound calls, the top-level data is generally the entire call. However, for inbound calls, the top-level data may show only a small fraction of how the call routed within the Zoom Phone platform.

There can be many different call flows within the Zoom Phone platform, some of the more common call flows being:

  1. User placed an outbound call.
  2. Inbound call placed to a user's direct phone number.
  3. Inbound call placed to an auto receptionist > callers dials a user's extension > user then answers the call.[1]
  4. Inbound call placed to a call queue then answered by a particular user.[1]
  5. Inbound call placed to an auto receptionist > caller makes a menu selection > the call is routed to a call queue > the call is routed to users > one of users answers the call.[1]
  6. Inbound call placed to a shared line and answered by a particular user.[1]

[1] In the above example, scenarios

3,4,5, and6 involve the call routing through multiple components within Zoom Phone. In order to see all of the call details for call scenarios such as these, you must query the [Get call log details](/docs/api-reference/phone/methods/#operation/getCallLogDetails) API for each call. This API will return a detailed response that includes the subsequent components that routed the call.

Get call log details

Use the Get call log details API to query the Zoom Phone platform for detailed information about a particular call. The response includes data such as the call queue that routed the call, the users that were offered the call, and the user that ultimately answered the call.

To query the Get call log details API, you need to provide a CallID or callLogId that you obtained from either a webhook event or the response from Get account's call logs API.

Putting it all together

Let's say we have a call flow shown below:

  1. An external caller dials into a phone number assigned to an auto receptionist named Marketing Hotline.
  2. The external caller makes a menu selection on the auto receptionist which then routes the call to a particular call queue named Marketing Queue.
  3. The call queue is configured with rotating distribution and routes the call to a group that contains 5 users.
  4. The call first rings to user Sally Smith, but Sally isn't able to answer the call.
  5. The call then rings to user Julie Jones, Julie answers the call.

Let's take a look at the APIs that we can use to gather the data associated with the above call flow.

Find this call in the Get account's call logs API

Example Request

GET

https://api.zoom.us/v2/phone/call_logs

Response

{
  "next_page_token": "565fdfgs4645",
  "page_size": 30,
  "total_records": 120,
  "from": "2021-05-10",
  "to": "2021-05-11",
  "call_logs": [
      {
          "id": "dcasgfdd-gfb0-4ea7-8dc0-c96rer34d7",
          "call_type": "voip",
          "caller_number": "+16695551234",
          "caller_number_type": 2,
          "caller_location": "San Jose, CA",
          "callee_number": "150002",
          "callee_number_type": 1,
          "callee_name": "Marketing Hotline",
          "direction": "inbound",
          "duration": 12,
          "result": "Call connected",
          "date_time": "2021-05-11T23:11:44Z",
          "path": "autoReceptionist",
          "site": {
              "id": "W454_mIgsdia4-Yn53334Hw",
              "name": "Headquarters"
          },
          "call_id": "696165649876346057",
          "owner": {
              "type": "autoReceptionist",
              "id": "4KL1uortyet5644boSbtEw",
              "name": "Marketing Hotline",
              "extension_number": 150002
          },
          "answer_start_time": "2021-05-11T23:11:44Z"
      },
      ],
}

From the above response we can see the information about the caller, and we can see that they dialed into the Marketing Hotline auto receptionist.

Since we know this is an auto receptionist call, we know there is usually more information than we can see from Get account's call logs API. Let's query the Get call log details API for this particular call with call_id 696165649876346057 to get more information.

Query the Get call log details API

Taking the call_id from the above example, we can query the Get call log details API.

Example Request

GET

https://api.zoom.us/v2/phone/call_logs/696165649876346057

Response

{
  "id": "dcasgfdd-gfb0-4ea7-8dc0-c96rer34d7",
  "call_type": "voip",
  "caller_number": "+16695551234",
  "caller_number_type": 2,
  "caller_location": "San Jose, CA",
  "callee_number": "150002",
  "callee_number_type": 1,
  "callee_name": "Marketing Hotline",
  "direction": "inbound",
  "duration": 12,
  "result": "Call connected",
  "date_time": "2021-05-11T23:11:44Z",
  "path": "autoReceptionist",
  "log_details": [
      {
          "id": "4c6eree7-5b1e-4833-a672-b9234534b868",
          "caller_location": "San Jose, CA",
          "duration": 12,
          "result": "Auto Recorded",
          "date_time": "2021-05-11T23:11:56Z",
          "path": "callQueue",
          "site": {
              "id": "W454_mIgsdia4-Yn53334Hw",
              "name": "Headquarters"
          },
          "recording_id": "79b4147ad442354234239abd3633a5",
          "recording_type": "Automatic",
          "forward_to": {
              "type": "callQueue",
              "name": "Marketing Queue",
              "id": "EzYX42345pQgfMA_U6UQ",
              "extension_number": "151006"
          },
          "answer_start_time": "2021-05-11T23:11:44Z"
      },
      {
          "id": "9456434-6656f-4645-b912-cc3b5356a1",
          "call_type": "voip",
          "caller_location": "San Jose, CA",
          "duration": 0,
          "result": "Answered by Other Member",
          "date_time": "2021-05-11T23:11:58Z",
          "path": "extension",
          "site": {
              "id": "W454_mIgsdia4-Yn53334Hw",
              "name": "Headquarters"
          },
          "forward_to": {
              "type": "user",
              "name": "Sally Smith",
              "id": "XnK5466456xPIzSg",
              "extension_number": "150001"
          }
      },
      {
          "id": "7453147a-d60c-4211-ab01-6b4545633a5",
          "call_type": "voip",
          "caller_location": "San Jose, CA",
          "duration": 12,
          "result": "Call connected",
          "date_time": "2021-05-11T23:12:09Z",
          "path": "extension",
          "site": {
              "id": "W454_mIgsdia4-Yn53334Hw",
              "name": "Headquarters"
          },
          "forward_to": {
              "type": "user",
              "name": "Julie Jones",
              "id": "uK9clxm34534543lGCAOdA",
              "extension_number": "151011"
          },
          "answer_start_time": "2021-05-11T23:12:11Z"
      }
  ],
  "call_id": "696165649876346057",
  "answer_start_time": "2021-05-11T23:11:44Z"
}

Based on this response, we can now see that the caller went into a call queue named Marketing Queue and that the call rang on both Sally Smith's Zoom Phone devices and also Julie Jones Zoom Phone devices. Because the date_time for Sally was before Julie, we know that Sally rang first and didn't answer the call. We know that Julie ultimately answered this call because Julie's result is “Call connected.”

Summary

When you need to see the entire picture for inbound calls, use both the Get account's call logs API and the Get call log details API to retrieve information about the call. Together these two APIs will provide the detail needed to properly analyze and report on your Zoom Phone call data.

Need help?

If you're looking for help, try Developer Support or our Developer Forum. Priority support is also available with Premier Developer Support plans.