Pagination

Different APIs use different pagination strategies:

Contracting, Hierarchies & Producer Profile APIs — Page-Based Pagination

All collection endpoints in the Contracting, Hierarchies, and Producer Profile APIs return results using page-based pagination. Results are in _embedded, navigation links are in _links, and metadata is in page.

Empty collections: When a collection endpoint returns no results, _embedded is absent from the response entirely — it is not an empty object.

Example response:

{
  "_embedded": {
    "carriers": [ { ... }, { ... } ]
  },
  "_links": {
    "self":  { "href": "/v1/customers/carriers?page=0&size=250" },
    "next":  { "href": "/v1/customers/carriers?page=1&size=250" },
    "last":  { "href": "/v1/customers/carriers?page=7&size=250" }
  },
  "page": {
    "size": 250,
    "totalElements": 150,
    "totalPages": 1,
    "number": 0
  }
}

Query parameters:

Iterating all pages (Python):

def paginate(access_token, base_url, path):
    """Generic HAL+JSON paginator for Contracting, Hierarchies, and Producer Profile API collections."""
    results = []
    url = f"{base_url}{path}"

    while url:
        response = requests.get(url, headers={"Authorization": f"Bearer {access_token}"})
        response.raise_for_status()
        data = response.json()

        for items in data.get("_embedded", {}).values():
            results.extend(items)

        next_href = data.get("_links", {}).get("next", {}).get("href")
        if next_href:
            # Contracting API endpoints are inconsistent: some return absolute URLs,
            # others return relative paths. Handle both.
            url = next_href if next_href.startswith("http") else f"{base_url}{next_href}"
        else:
            url = None

    return results

Use page.totalElements to validate you received all expected records.

ProducerSync API v2 — Continuation Token Pagination

In v2 ProducerSync API endpoints, pagination is handled using continuation tokens returned in the links object of the response. This method is ideal for efficiently paging through large datasets.

First Page

Your initial request will return a response:

• containing set of results under the embedded key
• a links object, including a next URL for retrieving the next page

Note: The ProducerSync API uses embedded (no underscore). This differs from the Contracting API, which uses _embedded per the HAL+JSON standard. If you are integrating both APIs, make sure your code handles each key name separately.

Example Response:

{
  "embedded": {
    "licenses": [
      { ... },
      { ... }
    ]
  },
  "links": {
    "self": {
      "href": "https://access.agentsync.io/v2/licenses?continuationToken=0"
    },
    "next": {
      "href": "https://access.agentsync.io/v2/licenses?continuationToken=11862929"
    }
  }
}

Iterating with links.next

To retrieve the next page of results, follow the URL provided in the links.next.href field:

GET https://access.agentsync.io/v2/licenses?continuationToken=11862929

Repeat this pattern with each subsequent response until the end of the dataset is reached.

End of Results

When you've reached the final page:

• the response will NOT include an embedded object
• the links.next.href will include a continuationToken=0

Example Final Response:

{
  "links": {
    "self": {
      "href": "https://access.agentsync.io/v2/licenses?continuationToken=11862929"
    },
    "next": {
      "href": "https://access.agentsync.io/v2/licenses?continuationToken=0"
    }
  }
}

Optional: Controlling Page Size

You may pass a size query parameter to control how many results are returned per page (default = 250)

• Minimum: 1
• Maximum: 1000

GET /v2/licenses?size=500

Adjusting the page size will impact the number of continuation tokens required to page through the data.

No Results Case

If your query yields no results at all, the response will look like this:

{
  "links": {
    "self": {
      "href": "https://access.agentsync.io/v2/licenses?continuationToken=0"
    },
    "next": {
      "href": "https://access.agentsync.io/v2/licenses?continuationToken=0"
    }
  }
}

Ensure your integration handles this scenario gracefully.

ProducerSync API v1 — Page-Based Pagination

All array-returning ProducerSync API v1 endpoints use page-based pagination. The pagination metadata is included in the response using a page object and a links object to help navigate between pages.

Page Object

The page field provides details about the current page of results.

Example:

"page": {
  "size": 3,
  "totalElements": 476944,
  "totalPages": 158982,
  "number": 0
}

Customizing Pagination

You can customize pagination by setting the optional query parameters:

• size: The number of results per page --> directly impacts the page.size response value
• number: The page number (zero-indexed) --> directly impacts the page.number response value

Links Object

The links field helps you navigate through pages of results.

Example:

"links": {
  "first": {
    "href": "http://api.agentsync.io/v1/addresses?page=0&size=3"
  },
  "self": {
    "href": "http://api.agentsync.io/v1/addresses?page=0&size=3"
  },
  "next": {
    "href": "http://api.agentsync.io/v1/addresses?page=1&size=3"
  },
  "last": {
    "href": "http://api.agentsync.io/v1/addresses?page=158981&size=3"
  }
}

Best Practices

• Use the next link to reliably paginate through results
• Avoid hardcoding page numbers; use provided links instead
• Be sure to handle the case where no next link is present (end of results)