Step-by-step migration instructions

This guide includes updated read endpoints, pagination changes, recommendations for custom integrations, and a clear mapping of v1/v2 resources to their v3 equivalents. It’s designed to help you transition endpoints smoothly and efficiently.

Each table in this article is organized alphabetically and maps specific resources to their v1/v2 routes, the corresponding v3 equivalent, and any additional comments or considerations for those endpoints.

Pagination

In previous versions, pagination was implemented by passing page and per_page parameters. The backend would then use limit and offset to fetch the appropriate records. Additionally, links for next, prev, and last pages were included in the response headers. However, calculating the last page required a count of all matching records, which negatively impacted performance, especially with large datasets.

To address these performance issues, V3 introduces a cursor-based pagination system, eliminating the need for offset. This approach enhances efficiency and scalability.

Key changes in v3 pagination

No page Parameter: The page parameter is no longer supported. You may specify a per_page parameter in the first request only to define the number of records per page.
Cursor-Based Links: To navigate between pages, the response headers include cursor-based links:

• next: URL for the next page (if available).
• prev: URL for the previous page (if available).
• Note: A last link is no longer provided.

Recommendations for custom integrations

We encourage users of custom integrations to adopt the Client Credentials Flow to familiarize themselves with the new authentication process in Harvest V3.

Note: The Client Credentials Flow is not available for Greenhouse partners. Partners must use the Authorization Code Grant Type.