This article explains how to use the Report API v2. In 2025, we introduced the new version of our report builder. The Report API v2 provides access to all the new report builder's data and functionalities.

The Report API v2 replaces the Custom Reports API v1. If you use the old version, we’ll share detailed email communication about the transition period and the planned removal date.
 

Before you start

To complete the setup, you need Administrator permissions. You might also need support from your IT department or Integrations team.

Understand the move to v2

The new Report API v2 matches the capabilities of the old version and includes improvements. As before, you can query reports one by one using the report ID.

Here’s what’s new with v2:

• It’s faster and more efficient at handling large datasets.
• You can explicitly select which reports to make available via API through a new dropdown. Note that only Administrators can select reports for API access.
• There's enhanced visibility and control for Administrators via a new API report list, even if you aren't the owner of a report. You can still only open reports shared with you or ones you own.
• Historical custom reports now include first name and last name. You don't need to get this information separately using the Employee API. The v2 shows the exact data you see in the UI.
• There's better filter support (previously, only IS or IS NOT was possible).

Note the following:

• We plan to remove the Custom Report API v1. We’ll inform you about the exact timeline via email.
• More features are coming soon, including raw data queries and create/update/delete endpoints for managing reports via API.

Step 1: Update your custom integration or build a new one

To use Report API v2, you need to either update your active custom integration or build a new one.

Update your custom integration

When you update the integration, you can keep using your existing API credentials.

Follow these steps:

1. Go to Settings > Security & integrations > API credentials.
2. Select the relevant custom integration and enable Read access for Reports.
3. Click Update.
4. The new Reporting API is now enabled, and you can make reports available.

Build a new custom integration

Refer to our dedicated Help Center article to review the requirements for building a custom integration.

1. Go to Settings > Security & integrations > API credentials.
2. Click Create custom integration.
3. Make sure to enable Read access for Reports.
4. Refer to the Developer Hub for instructions on how to set up a custom integration.

Step 2: Make reports available via API in the Analytics area

You need to review and enable the reports available for the API. If the Manage API access button doesn't appear, go back to Step 1 and update the integration. The button only becomes available once the integration has been saved with Report API v2 activated.

Here's how it works:

• Custom reports remain available through the Custom Reports API v1. You can't disable access to these.
• Reports you create with the new report builder are available via the Report API v2.

You can only see reports shared with you or ones you own. Review your report list and enable the reports you want to make available for the API. 

Follow these steps:

1. Go to Analytics > Reports.
2. Check the box next to the relevant report.
3. Click Manage API access.
4. From the dropdown, select Enabled.
5. Save your changes.

Step 3: Update and make the necessary changes in your API integration

To update and make the necessary changes in your API integration, follow these steps:

1. Adjust your integration code to use the new Report API v2 endpoints for enabled reports.
2. Update your API requests and authentication to include "Read access for Reports."
3. Test your integration to verify you receive the expected report data.

For technical details and sample queries, visit our Developer Hub and review the Report API v2 documentation.