RingCentral Call Performance API Quick Start

In this quick start guide, we are going to access call performance data via command line using CURL utility in just a few minutes. Let's get started.

Create an App if you don't have one already

The first thing we need to do is create an app in the RingCentral Developer Portal. This can be done quickly by clicking the "Create Call Performance Analytics App" button below. Just click the button, enter a name and description if you choose, and click the "Create" button. If you do not yet have a RingCentral account, you will be prompted to create one.

Call Performance Analytics App

  1. Login or create an account if you have not done so already.
  2. Go to Console/Apps and click 'Create App' button.
  3. Select "API App for RingCentral Office" under "What type of app are you creating?"
  4. Select "Other Non-UI" under "Where will you be calling the API from?"
  5. Select "Only members of my organization/company" under "Who will be authorized to access your app?"
  6. On the second page of the create app wizard, enter your app's name and description.
  7. We are using Password Flow authentication, so leave "OAuth Redirect URI" blank for this test app.

Get Production Application Credentials (not Sandbox Credentials)

In the RingCentral Developer Dashboard, navigate to your App -> Dashboard -> Credential and note down the following:

  • App Server URL which should be https://platform.ringcentral.com . This is the URL for RingCentral Production Environment and we will be doing our development in Production Environment for this API. Please contact us to get your application graduated to production so you can access production credentials if you don't have them already.
  • Client ID
  • Client Secret

These will be used when making API calls either via Command Line (CURL), POSTMAN or in your application codebase.

Add Authentication if you don't have RingCentral authentication in place

There are multiple ways to provide authentication support for your application for RingCentral users. This will depend on the type of authentication mechanism you chose when you created your application. For more information about how to use OAuth 2.0 with your application please refer to this guide

Make API Call using CURL

Obtain Access Token using RingCentral supported Authentication

In this example, we are making an API request to the RingCentral platform using Password Flow Authentication. Once the command is executed, copy the 'access_token' string from the response body.

curl --location -g --request POST 'https://platform.ringcentral.com/restapi/oauth/token' \
     --header 'Authorization: {{basic_auth_header}}' \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' \
     --data-urlencode 'grant_type=password' \
     --data-urlencode 'username={{RC_USERNAME}}' \
     --data-urlencode 'password={{RC_PASSWORD}}' \
     --data-urlencode 'extension={{RC_EXTENSION}}'

Make a HTTP POST Request to get 'call performance data'

In this example, we are making the API request and sending the JSON describing our requirements. To understand what the various JSON properties please refer to the API Reference documentation. In this step, please make sure to update the "header" information with your 'access_token' string obtained in the previous step.

   curl --location --request POST 'https://platform.ringcentral.com/analytics/phone/performance/v1/accounts/{accountId}/calls/aggregate/' \
        --header 'Content-Type: application/json' \
        --header 'Accept: application/json' \
        --header '{Your Access Token goes here}' \
        --data-raw '{
                      "grouping": {
                        "groupBy": "CompanyNumbers",
                        "ids": [
                          "string"
                        ]
                      },
                      "timeRange": {
                        "timeFrom": "2021-10-25T05:55:30.444Z",
                        "timeTo": "2021-10-25T05:55:30.444Z"
                      },
                      "additionalFilters": {
                        "direction": "Inbound",
                        "origin": "Internal",
                        "callResponse": "Answered",
                        "callResponseType": [
                          "InboundDirect"
                        ],
                        "callResult": [
                          "Completed"
                        ],
                        "callSegments": [
                          {
                            "callSegment": "Ringing",
                            "callSegmentLength": {
                              "minValueSeconds": 0,
                              "maxValueSeconds": 0
                            }
                          }
                        ],
                        "callActions": [
                          {
                            "callAction": "HoldOff"
                          }
                        ],
                        "companyHours": "BusinessHours",
                        "callDuration": {
                          "minValueSeconds": 0,
                          "maxValueSeconds": 0
                        },
                        "timeSpent": {
                          "minValueSeconds": 0,
                          "maxValueSeconds": 0
                        },
                        "callerExtensionIds": [
                          "string"
                        ],
                        "calledExtensionIds": [
                          "string"
                        ],
                        "calledNumbers": [
                          "string"
                        ],
                        "queueSla": "InSla"
                      },
                      "responseOptions": {
                        "counters": {
                          "allCalls": {
                            "aggregationType": "Sum"
                          },
                          "callsByDirection": {
                            "aggregationType": "Sum"
                          },
                          "callsByOrigin": {
                            "aggregationType": "Sum"
                          },
                          "callsByResponse": {
                            "aggregationType": "Sum"
                          },
                          "callsByResponseType": {
                            "aggregationType": "Sum"
                          },
                          "callsSegments": {
                            "aggregationType": "Sum"
                          },
                          "callsByResult": {
                            "aggregationType": "Sum"
                          },
                          "callsByCompanyHours": {
                            "aggregationType": "Sum"
                          },
                          "callsByQueueSla": {
                            "aggregationType": "Sum"
                          },
                          "callsByActions": {
                            "aggregationType": "Sum"
                          }
                        },
                        "timers": {
                          "allCallsDuration": {
                            "aggregationType": "Sum"
                          },
                          "callsDurationByDirection": {
                            "aggregationType": "Sum"
                          },
                          "callsDurationByOrigin": {
                            "aggregationType": "Sum"
                          },
                          "callsDurationByResponse": {
                            "aggregationType": "Sum"
                          },
                          "callsDurationByResponseType": {
                            "aggregationType": "Sum"
                          },
                          "callsSegmentsDuration": {
                            "aggregationType": "Sum"
                          },
                          "callsDurationByResult": {
                            "aggregationType": "Sum"
                          },
                          "callsDurationByCompanyHours": {
                            "aggregationType": "Sum"
                          },
                          "callsDurationByQueueSla": {
                            "aggregationType": "Sum"
                          }
                        }
                      }
                    }'

Using Postman Tool

If you prefer to see the API request and response in GUI, we recommend using the Postman Tool (free version). Click the button below to automagically import the settings for Postman and run it there.

Run in Postman

What's Next?

When you have successfully made your first API call, it is time to take your next step towards building a more robust RingCentral application. You can reference our Sample C# Application or build an application from scratch.

Take your next step »