Pagination

All list endpoints return their results in pages. The page is selected with the optional range query parameter, and the total number of records is returned in the response headers.

Syntax

The range parameter is a JSON array with two zero-based positions: the first and the last record to return. Both positions are inclusive.

range=[0,99]

The example above returns the first 100 records. The next page would be range=[100,199], and so on.

When range is omitted, the API returns the first 10 records, as if range=[0,9] had been sent.

A 400 Bad Request error is returned when the array doesn't contain exactly two elements, or when the first position is greater than the last one.

Response

The response body is a JSON array with the records of the requested page. It is not wrapped in any other object.

The total number of records matching the filter is returned in two response headers:

When no records match, the body is an empty array ([]) and the headers are X-Total-Count: 0 and Content-Range: campaigns 0-0/0. Requesting a page beyond the last record also returns an empty array.

Iterating over all pages

To read every record, request consecutive pages until you've read X-Total-Count records, or until a page returns fewer records than requested. Always use a sort order, so pages are consistent between requests. For example, in Python:

import requests

url = "https://api.sipcaller.com/v1/accounts/ACCOUNT_ID/campaigns/CAMPAIGN_ID/numbers"
headers = {"Authorization": "Bearer API_KEY_TOKEN"}
page_size = 100
start = 0
numbers = []

while True:
    params = {"sort": '["id","ASC"]', "range": f"[{start},{start + page_size - 1}]"}
    response = requests.get(url, headers=headers, params=params)
    response.raise_for_status()
    page = response.json()
    numbers.extend(page)
    total = int(response.headers["X-Total-Count"])
    start += page_size
    if len(page) < page_size or start >= total:
        break

print(f"Read {len(numbers)} of {total} numbers")

We recommend pages of up to a few hundred records. Larger pages take longer to generate and transfer, and are more likely to hit timeouts on slow networks. Keep the rate limits in mind when reading many pages in a loop.