calls_filter

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/ringover/json-schema/ringover-calls-filter-schema.json",
  "title": "calls_filter",
  "description": "Filter criteria for retrieving terminated calls. All fields are optional. The maximum date range is **15 days**.\nSet `filter` to `ADVANCED` to enable filtering by specific users, groups, IVRs, and phone numbers via the `advanced` object.\n",
  "x-generated": "2026-10-28",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/ringover-openapi.yml#/components/schemas/calls_filter",
  "type": "object",
  "properties": {
    "filter": {
      "type": [
        "string",
        "null"
      ],
      "description": "Scope of the call filter:\n- `ALL`: All calls (default).\n- `DIRECT`: Only direct calls (excludes IVR calls).\n- `IVR`: Only calls routed through IVRs.\n- `ADVANCED`: Enables the `advanced` object for fine-grained filtering by users, groups, IVRs, and numbers.\n",
      "enum": [
        "ALL",
        "DIRECT",
        "IVR",
        "ADVANCED"
      ],
      "default": "ALL"
    },
    "start_date": {
      "description": "Start of the date range (inclusive). Must be used together with `end_date`. Defaults to 15 days ago. Format: ISO 8601.",
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "end_date": {
      "description": "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.",
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "ascending_order": {
      "description": "[Deprecated] Sort order. Calls are returned in descending order (most recent first) by default.",
      "type": "boolean",
      "deprecated": true
    },
    "call_type": {
      "description": "Filter by call types. Multiple values can be combined.",
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string",
        "enum": [
          "ANSWERED",
          "MISSED",
          "OUT",
          "VOICEMAIL"
        ]
      }
    },
    "advanced": {
      "description": "Advanced filters. **Only used when `filter` is set to `ADVANCED`.** Allows filtering by specific IVRs (with optional scenario IDs), groups (resolved to member user IDs server-side), individual users, and phone numbers.\n",
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "ivrs": {
          "description": "Filter by specific IVR(s). Each entry can optionally include scenario IDs to further narrow results.",
          "type": [
            "array",
            "null"
          ],
          "items": {
            "$ref": "#/$defs/ivr_filter"
          }
        },
        "groups": {
          "description": "Filter by group IDs. The server resolves group IDs to their member user IDs automatically.",
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "integer",
            "format": "int64"
          }
        },
        "users": {
          "description": "Filter by specific user IDs.",
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "integer",
            "format": "int64"
          }
        },
        "ext_numbers": {
          "description": "Filter by external phone numbers (E.164 format without '+').",
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "integer",
            "format": "int64"
          }
        },
        "int_numbers": {
          "description": "Filter by internal Ringover numbers (E.164 format without '+').",
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "integer",
            "format": "int64"
          }
        }
      }
    },
    "stars": {
      "description": "Filter by star ratings assigned to calls.",
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string",
        "enum": [
          "STAR1",
          "STAR2",
          "STAR3",
          "CHECK",
          "WARNING"
        ]
      }
    },
    "contacts": {
      "description": "Filter by contact IDs to retrieve calls associated with specific contacts.",
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "integer",
        "format": "int64"
      }
    },
    "tags": {
      "description": "Filter by tag IDs to retrieve calls with specific tags.",
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "integer",
        "format": "int64"
      }
    },
    "out_planning": {
      "description": "When `true`, include only calls received outside of working hours. When `false`, exclude those calls.",
      "type": [
        "boolean",
        "null"
      ]
    },
    "no_digit": {
      "description": "When `true`, include only calls where no digit was pressed. When `false`, exclude those calls.",
      "type": [
        "boolean",
        "null"
      ]
    },
    "ringing": {
      "description": "When `true`, include only inbound calls that did not ring to any user. When `false`, exclude those calls.",
      "type": [
        "boolean",
        "null"
      ]
    },
    "note": {
      "description": "When `true`, include only calls with notes. When `false`, exclude calls with notes.",
      "type": [
        "boolean",
        "null"
      ]
    },
    "tag": {
      "description": "When `true`, include only calls with tags. When `false`, exclude calls with tags.",
      "type": [
        "boolean",
        "null"
      ]
    },
    "short": {
      "description": "When `true`, include only calls shorter than `exclude_short_value` seconds. When `false`, exclude those calls. Requires `exclude_short_value` > 0.",
      "type": [
        "boolean",
        "null"
      ]
    },
    "long": {
      "description": "When `true`, include only calls longer than `exclude_long_value` seconds. When `false`, exclude those calls. Requires `exclude_long_value` > 0.",
      "type": [
        "boolean",
        "null"
      ]
    },
    "amd": {
      "description": "When `true`, include only outbound calls detected as answered by a machine (AMD). When `false`, exclude those calls.",
      "type": [
        "boolean",
        "null"
      ]
    },
    "exclude_short_value": {
      "description": "Duration threshold in seconds for the `short` filter.",
      "type": [
        "integer",
        "null"
      ],
      "format": "int64"
    },
    "exclude_long_value": {
      "description": "Duration threshold in seconds for the `long` filter.",
      "type": [
        "integer",
        "null"
      ],
      "format": "int64"
    },
    "limit_count": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Maximum number of calls to return. Default: 100.",
      "format": "int64",
      "default": 100,
      "minimum": 1,
      "maximum": 1000
    },
    "limit_offset": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Number of calls to skip for pagination. Default: 0. Maximum: 9000.",
      "format": "int64",
      "default": 0,
      "minimum": 0,
      "maximum": 9000
    },
    "last_id_returned": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Cursor-based pagination: returns call logs with a `cdr_id` lower than this value. Alternative to `limit_offset` for deep pagination.",
      "format": "int64"
    }
  },
  "$defs": {
    "ivr_filter": {
      "type": "object",
      "properties": {
        "ivr_id": {
          "type": "integer",
          "format": "int64",
          "description": "The identifier of the ivr"
        },
        "numbers": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "integer",
            "format": "uint64"
          }
        },
        "scenarios": {
          "type": [
            "array",
            "null"
          ],
          "description": "The identifier of the scenario",
          "items": {
            "type": "integer",
            "format": "int64"
          }
        }
      }
    }
  }
}