Introduction to Odata v2

OData v2 is the next generation of the Aptem OData API. It introduces a new gateway architecture with built-in rate limiting, improved documentation, and a growing set of data feeds. OData v2 runs alongside the existing v1 API, so your current v1 reports and integrations continue to work unchanged.

What is available in OData v2

OData v2 currently provides access to the following feed:

Additional feeds will be added to OData v2 over time. The v1 API remains available for all existing feeds (Users, Reviews, ReviewResponses, Tasks, and others documented in the OData dictionary). For a full list of fields available on each v2 feed, see the interactive documentation at /odata/2.0/docs on your tenant, or the Actions feed reference.

How to access OData v2

Prerequisites

• An active Aptem administrator account with access to your tenant

• Your OData API key (this is the same key used for v1, supplied to you by Aptem)

Accessing the documentation

To browse the OData v2 documentation for your tenant:

1. Log into your Aptem tenant as normal.

2. In your browser address bar, replace everything after your tenant URL with /odata/2.0/docs.

For example, if your tenant URL is https://yourtenant.aptem.co.uk

navigate to: https://yourtenant.aptem.co.uk/odata/2.0/docs

This page lists all available v2 feeds with descriptions, field definitions, and example responses. You must be logged into your Aptem tenant to view it.

Accessing the metadata

You must be logged in to your Aptem tenant to access this. To retrieve the OData metadata document (useful for understanding the data model and field types), navigate to:

The metadata document describes all available entities, their properties, and data types in a machine-readable format.

Viewing feed data in the browser

To query a feed directly in the browser (for example to check what data is returned), navigate to:

The response displays as raw JSON. Select Pretty print at the top of the page to format the data so it is easier to read.

For building reports in Excel or integrating with other tools, you will need your API key. See the sections below for details.

Differences between v1 and v2

Rate limiting

OData v2 applies rate limits to protect platform performance. The default limits are:

• 120 requests per 60 seconds per user per tenant

• 4 concurrent requests per user per tenant

If you exceed these limits, the API returns a 429 Too Many Requests response. When this happens:

• Check the Retry-After header in the response, which tells you how many seconds to wait before sending another request.

• If you are running reports in Excel, reduce the number of queries refreshing at the same time, or add filters to reduce the volume of data each query returns.

For most reporting use cases, these limits will not be reached. They are designed to prevent runaway queries from affecting the platform, not to restrict normal usage.

Pagination

Results are always paged. Each page returns up to 1,000 items. When more items are available, the response includes an @odata.nextLink field containing the URL of the next page.

To read through a full result set, follow the @odata.nextLink until it is no longer present in the response. Do not build your own paging by incrementing $skip, as this can miss or duplicate items if data changes between requests.

If you need smaller pages, send a Prefer header with your request:

Using OData v2 in Excel

You can build OData reports in Excel the same way as v1. The v2 feeds connect slightly differently from V1 in Excel Power Query. Instead of connecting to the base URL and navigating to a table, you query the feed URL directly with your field selection in the URL. 

Example Power Query M code for the actions feed:

For a full guide on how query options work, see How to query OData v2 feeds. For ready-made queries you can copy, see OData v2 query examples.

For complete report-building guides that combine v2 actions with v1 data (reviews, users, programmes), see:

• Building a reviews and actions report using OData in Excel

Using OData v2 in integrations

If you are building a custom integration against the OData v2 feeds, make a standard HTTP GET request to the feed URL with your API key in the X-API-Token header.

Example request:

The response is JSON. You can use standard OData query parameters to control what is returned:

• $select to choose specific fields, for example ?$select=Id,Action,Status,DueDate

• $filter to filter results, for example ?$filter=Status eq 'Open'

These can be combined:

The same rate limits apply to integration requests: 120 requests per 60 seconds and 4 concurrent requests per user per tenant. If you exceed these limits, the API returns a 429 Too Many Requests response with a Retry-After header. Your integration should handle this by waiting the specified number of seconds before retrying.

For the full list of available fields and data types, see the Actions feed reference, the metadata document at /odata/2.0/$metadata, or the interactive documentation at /odata/2.0/docs on your tenant.

Getting help

If you have questions about OData v2, need your API key, or are unsure whether a feed is available on your tenant:

• Contact your Implementation Consultant if you are still in implementation

• Contact your Customer Success Manager if you are a live customer

• Raise a support ticket