> ## Documentation Index
> Fetch the complete documentation index at: https://integrations.docs.commenda.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrating from V3 to V4

> What changes between the V3 and V4 Integrations APIs, and how to move your integration over.

V4 is a redesigned API and is not backward-compatible with V3 at the route or response level. The good news: the fundamentals are unchanged. You authenticate the same way, and individual records keep the same field-level shape. Most of the work is updating your base URL and route paths, and adjusting to the wrapped response envelope.

## How the migration works

Your connections are migrated for you by the Commenda team. You do not re-run OAuth or reconnect your customers as part of the move.

* **Connections are copied as-is.** Each connection carries over with the same status it had in V3. The migration does not change a connection's state or trigger a re-authentication.
* **Your code is what changes.** Point your integration at the V4 base URL and routes (below). Once you cut over, V4 becomes the source of truth for that organization.

<Note>
  Connections for platforms that V4 does not yet support are still copied over, but they are inert: they will not appear in the [Commenda Integrations Dashboard](https://integrations.commenda.io/) and will not sync, either automatically or manually. Support is added over time, and they begin syncing once V4 supports the platform.
</Note>

To schedule a migration, reach out to [support@commenda.io](mailto:support@commenda.io).

## What changes at a glance

|                   | V3                                         | V4                                                               |
| ----------------- | ------------------------------------------ | ---------------------------------------------------------------- |
| Base URL          | `https://api.rootfi.dev/v3`                | `https://api.integrations.commenda.io/v4`                        |
| Regions           | Separate regional endpoints                | Single base URL for all regions                                  |
| Authentication    | `api_key` header                           | `api_key` header (unchanged)                                     |
| Route shape       | `/{category}/{model}`                      | `/v4/core/companies/{companyId}/{model}`                         |
| Query interface   | REST and GraphQL                           | REST only                                                        |
| Response envelope | `{ data: [...], prev, next, total_count }` | `{ data: { data: [...], prev, next, total_count }, request_id }` |
| Record identifier | `rootfi_id`                                | `rootfi_id` (values are reassigned)                              |
| Dashboard         | `integrate.rootfi.dev`                     | `integrations.commenda.io`                                       |
| SDK               | Legacy RootFi SDK                          | [`@commenda/integrations`](/api-reference/v4/sdk/nodejs)         |

## Authentication is unchanged

Requests are still authenticated with an API key in the `api_key` header. Generate keys in the [Commenda Integrations Dashboard](https://integrations.commenda.io/settings/api-keys).

```bash theme={null}
curl -X GET "https://api.integrations.commenda.io/v4/core/companies" \
  -H "api_key: YOUR_API_KEY"
```

## Update your API calls

<Steps>
  <Step title="Switch the base URL">
    Replace the V3 host with `https://api.integrations.commenda.io`. All routes live under the `/v4` prefix. V4 serves every region from this single base URL, so any regional endpoints you used in V3 collapse into this one.
  </Step>

  <Step title="Scope routes to a company">
    V3 routes were category-scoped (`/accounting/invoices`). V4 routes are scoped to a company and drop the category prefix.

    ```
    V3   GET https://api.rootfi.dev/v3/accounting/invoices
    V4   GET https://api.integrations.commenda.io/v4/core/companies/{companyId}/invoices
    ```
  </Step>

  <Step title="Update filtering and pagination">
    V4 filters on any field using operator keys, paginates with `limit` and a `next` cursor, and expands related objects with `expand`.

    ```bash theme={null}
    curl -X GET "https://api.integrations.commenda.io/v4/core/companies/{companyId}/invoices?status[eq]=PAID&limit=50&expand=line_items" \
      -H "api_key: YOUR_API_KEY"
    ```

    Pass the `next` cursor back as the `next` query parameter to page forward.
  </Step>

  <Step title="Adjust to the wrapped response envelope">
    V4 wraps every response in `{ data, request_id }`. For reads, the payload sits inside `data`, so the records array moves one level down and list metadata moves alongside it.

    ```
    V3   response.data          // the records array
         response.next          // pagination cursor

    V4   response.data.data     // the records array
         response.data.next     // pagination cursor (also prev, total_count)
         response.request_id    // per-request identifier
    ```
  </Step>

  <Step title="Move off GraphQL">
    GraphQL is no longer supported. V4 is REST only, so any queries you ran against the V3 GraphQL playground must move to the REST endpoints above.
  </Step>
</Steps>

## Record IDs and the stable join key

V4 re-syncs your data into its own storage, so `rootfi_id` values are **not** the same as they were in V3. If you stored `rootfi_id`s to reference records, you will need to re-map them after cutover.

The identifier that is stable across both versions is `platform_id`, the record's ID on the source platform. Join on `platform_id` to reconcile V3 records with their V4 equivalents.

## Choose your initial sync window

When your organization moves to V4, its first sync backfills a historical window rather than the platform's entire history. Pick a window based on how much history you need.

<Note>
  We suggest the **last 30 days** up to the **last quarter**, and no longer than that. A larger window means a slower first sync with limited added value for most integrations.
</Note>

If you later need data older than your chosen window, request a full sync from [support@commenda.io](mailto:support@commenda.io).

## Webhooks

Your webhook endpoints carry over during the migration, and the event types are the same as in V3: `DATA_MODEL_CHANGES`, `CONNECTION_CHANGED`, `SYNC_COMPLETED`, and `SYNC_STARTED`. See [Webhooks](/documentation/concepts/webhooks) for the current payloads and setup.

## SDK

If you used the legacy RootFi SDK, switch to [`@commenda/integrations`](/api-reference/v4/sdk/nodejs), which is generated from the V4 OpenAPI spec and typed end to end.

## Migration checklist

* [ ] Base URL switched to `https://api.integrations.commenda.io/v4`.
* [ ] Routes scoped to `{companyId}` and category prefixes removed.
* [ ] Filtering and pagination updated to operator keys, `limit`, and the `next` cursor.
* [ ] Response parsing updated for the wrapped envelope (`data.data` for records, `request_id` present).
* [ ] GraphQL queries moved to REST.
* [ ] Stored `rootfi_id`s re-mapped, or lookups switched to `platform_id`.
* [ ] Initial sync window chosen and confirmed with Commenda.
* [ ] Webhook consumers verified against the V4 payloads.

## Support

* **Documentation:** [integrations.docs.commenda.io](https://integrations.docs.commenda.io)
* **Support:** [support@commenda.io](mailto:support@commenda.io)