calls

List terminated calls with advanced filters

Changed on Oct 1, 2026

Retrieve a paginated list of terminated calls with advanced filtering capabilities. This is the more powerful version of GET /calls — it supports filtering by tags, stars, users, groups, IVRs (with optional scenario IDs), and external/internal phone numbers.

Permission: Calls Read required.

Monitoring: This route always returns all team calls regardless of the Monitoring flag. The Monitoring setting has no effect on call listing — the underlying stats service does not filter by user. This applies identically whether Monitoring is ON or OFF.

Date range: Maximum allowed range is 15 days. Defaults to the last 15 days if not specified.

Advanced filtering: Set filter to ADVANCED in the request body to enable the advanced object. This allows precise filtering by specific user IDs, group IDs, IVR IDs (with optional scenario IDs), and phone numbers (internal or external).

Pagination: Use limit_count and limit_offset for offset-based pagination, or last_id_returned for cursor-based deep pagination.

Note: Multiple items may share the same call_id — this occurs when a call is transferred or routed through an IVR.

Expand: same query parameter as GET /calls. summary and transcription are omitted unless requested. contact is always present.

post/calls

Request

Base URL
https://public-api.ringover.com/v2
URL
https://public-api.ringover.com/v2/calls
Auth
API key in header Authorization

Query parameters

expandstring[]

Optional payload to embed on each call log. Repeat the parameter to request both: expand=summary&expand=transcription.

summary — Ringover summary text
transcription — call transcription

contact is not accepted. An unknown value returns 400. Each value downloads a file and adds latency.

Request body

filter'ALL' | 'DIRECT' | 'IVR' | 'ADVANCED' nullable

Scope of the call filter:

ALL: All calls (default).
DIRECT: Only direct calls (excludes IVR calls).
IVR: Only calls routed through IVRs.
ADVANCED: Enables the advanced object for fine-grained filtering by users, groups, IVRs, and numbers.

start_datestring date-time nullable

Start of the date range (inclusive). Must be used together with end_date. Defaults to 15 days ago. Format: ISO 8601.

end_datestring date-time nullable

End of the date range (inclusive). Must be used together with start_date. The difference between start_date and end_date must not exceed 15 days. Defaults to tomorrow at midnight.

ascending_orderboolean

[Deprecated] Sort order. Calls are returned in descending order (most recent first) by default.

call_typestring[] nullable

Filter by call types. Multiple values can be combined.

starsstring[] nullable

Filter by star ratings assigned to calls.

contactsinteger[] nullable

Filter by contact IDs to retrieve calls associated with specific contacts.

tagsinteger[] nullable

Filter by tag IDs to retrieve calls with specific tags.

out_planningboolean nullable

When true, include only calls received outside of working hours. When false, exclude those calls.

no_digitboolean nullable

When true, include only calls where no digit was pressed. When false, exclude those calls.

ringingboolean nullable

When true, include only inbound calls that did not ring to any user. When false, exclude those calls.

noteboolean nullable

When true, include only calls with notes. When false, exclude calls with notes.

tagboolean nullable

When true, include only calls with tags. When false, exclude calls with tags.

shortboolean nullable

When true, include only calls shorter than exclude_short_value seconds. When false, exclude those calls. Requires exclude_short_value > 0.

longboolean nullable

When true, include only calls longer than exclude_long_value seconds. When false, exclude those calls. Requires exclude_long_value > 0.

amdboolean nullable

When true, include only outbound calls detected as answered by a machine (AMD). When false, exclude those calls.

exclude_short_valueinteger nullable

Duration threshold in seconds for the short filter.

exclude_long_valueinteger nullable

Duration threshold in seconds for the long filter.

limit_countinteger nullable

Maximum number of calls to return. Default: 100.

limit_offsetinteger nullable

Number of calls to skip for pagination. Default: 0. Maximum: 9000.

last_id_returnedinteger nullable

Cursor-based pagination: returns call logs with a cdr_id lower than this value. Alternative to limit_offset for deep pagination.

Example request

{
  "filter": "ADVANCED",
  "start_date": "2025-01-01T00:00:00Z",
  "end_date": "2025-01-15T23:59:59Z",
  "call_type": [
    "OUT",
    "ANSWERED"
  ],
  "advanced": {
    "ivrs": [
      {
        "ivr_id": 19479175,
        "numbers": [
          331797500010
        ],
        "scenarios": [
          19479175,
          19479176
        ]
      }
    ],
    "groups": [
      123456
    ],
    "users": [
      123456
    ],
    "ext_numbers": [
      33122334455
    ],
    "int_numbers": [
      33122114455
    ]
  },
  "stars": [
    "STAR1"
  ],
  "contacts": [
    123456
  ],
  "tags": [
    123456
  ],
  "exclude_short_value": 10,
  "exclude_long_value": 500,
  "limit_count": 100,
  "last_id_returned": 19479170
}

Response

Successful operation

user_idinteger

The identifier of the user

team_idinteger

The identifier of the team

limit_count_settedinteger

Used to create a pagination cursor

limit_offset_settedinteger

Used to create a pagination cursor

last_id_offset_settedinteger

The request will return <b>cdr_id</b> (call logs) prior to this one

filterstring

The used filter

call_list_countinteger

The size of the array <em>list</em>, corresponds to the number of logs retrieved

total_call_countinteger

The total number of calls

total_missed_call_countinteger

The total number of missed calls

Example response

{
  "user_id": 123456,
  "team_id": 654321,
  "limit_count_setted": 100,
  "limit_offset_setted": 100,
  "last_id_offset_setted": 19479170,
  "call_list_count": 1,
  "call_list": [
    {
      "cdr_id": 19479175,
      "call_id": "9058220947198957713",
      "channel_id": "9058220947198957713",
      "type": "PHONE",
      "direction": "in",
      "last_state": "VOICEMAIL",
      "start_time": "2017-04-13T15:27:36+02:00",
      "answered_time": "2017-04-13T15:27:46+02:00",
      "end_time": "2017-04-13T15:27:56+02:00",
      "incall_duration": 10,
      "total_duration": 20,
      "from_number": "33600000000",
      "to_number": "33184800000",
      "note": "Potential client",
      "star": "STAR1",
      "tags": [
        {
          "tag_id": 123,
          "name": "mytag",
          "color": "ff6b6b",
          "description": "my tag description",
          "creation_date": "2018-08-12T12:12:40.53Z"
        }
      ],
      "record": "https://cdn.ringover.com/records/0-0/35537d8679f3e2-13-04-19-15h27-33600000000-33180800000.mp3",
      "user": {
        "user_id": 123456,
        "team_id": 123456,
        "initial": "PM",
        "color": "3CC8C8",
        "firstname": "Pauline",
        "lastname": "Martin",
        "company": "Ringover",
        "email": "pauline.martin@ringover.com",
        "picture": "https://cdn77.ringover.com/img/users/default.jpg",
        "concat_name": "Pauline Martin"
      },
      "conference": {
        "conference_id": 60908,
        "name": "SoConference",
        "numbers": [
          {
            "number": 33184800000,
            "label": "myfavoritenumber",
            "type": "PHONE",
            "user_id": 60907,
            "ivr_id": 60908,
            "conference_id": 60908,
            "format": {
              "raw": 184800000,
              "country_code": "33",
              "country": "FR",
              "e164": "+33184800000",
              "international": "+33 1 84 80 00 00",
              "international_alt": "33184800000",
              "national": "01 84 80 00 00",
              "national_alt": "0184800000",
              "rfc3966": "tel:+33-1-84-80-00-00"
            }
          }
        ]
      },
      "ivr": {
        "ivr_id": 123456,
        "name": "StandardFacile",
        "color": "ff6b6b"
      },
      "contact": {
        "contact_id": 654321,
        "is_shared": true,
        "social_service_id": "00P7U000015Ei75YBX",
        "firstname": "John",
        "lastname": "Do",
        "company": "DoeCompany",
        "concat_name": "John Doe",
        "color": "3CC8C8",
        "initial": "JD",
        "creation_date": "2018-08-12T12:12:40.53Z",
        "numbers": [
          331797500010
        ]
      }
    }
  ],
  "total_call_count": 1337,
  "total_missed_call_count": 4
}

Changes

Oct 1, 20265b3e0427c522 Revision changes
- breaking
  added subschema #2 to the // response property oneOf list for the response status
- breaking
  the // response's property type changed from object to no type for status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- info
  added the new optional query request parameter expand
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
Aug 10, 2026dac34ebedef3 Revision changes
- warning
  the request property's max was set to 9000.00
- warning
  the request property's min was set to 1.00
- warning
  the request property's min was set to 0.00
- info
  the request property default value ALL was added
- info
  the request property default value 100 was added
- info
  the request property default value 0 was added
- info
  request property deprecated

Operation history (3 revisions)