Skip to content

Collections

A request for a list of resources (for example, GET /api/v2/calls.json) returns a JSON object with the list under the resource name, a total attribute, and a next_url attribute:

{
    "calls": [ ... ],
    "total": null,
    "next_url": "/api/v2/calls.json?limit=20&start=20"
}

Paging

By default, MiaRec returns 20 records per page. The client application may request up to 1000 records per page with the limit parameter, and skip records with the start parameter:

/api/v2/users.json?limit=500
/api/v2/users.json?limit=500&start=500

next_url is the URL of the next page. It is null when there are no more pages. The client application should follow next_url rather than compute the next start value itself.

Total number of records

Counting all records that match a query can be an expensive operation. For performance reasons, MiaRec does not count them on every request. Instead:

  • The application queries limit + 1 records. The presence of the extra record signals that more data is available, and next_url is set. The extra record is not returned.
  • On the last page, next_url is null and total contains the total number of records.
  • On other pages, total is null.

To get an approximate total earlier, pass the max_total_calc parameter (up to 1000). The application then queries up to max_total_calc records even when limit is smaller. If fewer records than max_total_calc exist, total contains the exact number:

/api/v2/calls.json?limit=50&max_total_calc=1000

{
    "calls": [ ... 50 records ... ],
    "total": 813,
    "next_url": "/api/v2/calls.json?start=50&limit=50&max_total_calc=1000"
}

The MiaRec web portal uses this technique to show a pagination counter like "0-20 of 813", or "0-20 of many" when more than 1,000 records match.

Sort order

Lists are returned in a fixed order. The list of calls can be ordered with the order_by parameter: call_desc (newest first, the default) or call_asc (oldest first). See Basic search.

Access scope

The returned list contains only the records that are within the access scope of the API user's role.

For example, a client application requests a list of calls:

/api/v2/calls.json

With credentials of a system administrator, all calls are returned. With credentials of a group manager, only the calls of the managed groups are returned. With credentials of a tenant user, only the calls of that tenant are returned.

A list may be filtered to narrow the results by different attributes, like date range, user, group, or search term. Filtering parameters are passed as URI parameters, and several parameters may be combined:

/api/v2/calls.json?daterange=2024/11/01-2024/12/01&search_term=12345

Common filtering parameters:

Parameter Description
search_term Text search. Which attributes are searched depends on the resource, for example the phone number, phone name, and notes of a call, or the name of a user, group, or tenant. Partial match, case insensitive.
tenant_id Filter by tenant ID (multi-tenant deployments).
group_id Filter by group ID.
user_id Filter by user ID.
daterange Filter by date, in the format YYYY/MM/DD-YYYY/MM/DD or YYYY/MM/DD. The dates are interpreted in the time zone of the API user.

The parameters supported by each resource are listed on the List and search page of that resource. The list of calls additionally supports advanced search with comparison operators.