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.

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 and will not sync, either automatically or manually. Support is added over time, and they begin syncing once V4 supports the platform.

To schedule a migration, reach out to [e-mail].

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

Authentication is unchanged

Requests are still authenticated with an API key in the api_key header. Generate keys in the Commenda Integrations Dashboard.

curl -X GET "https://api.integrations.commenda.io/v4/core/companies" \
  -H "api_key: YOUR_API_KEY"

Update your API calls

1. 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.

2. 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
   
3. 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.

   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.

4. 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
   
5. 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.

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_ids 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.

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.

If you later need data older than your chosen window, request a full sync from [e-mail].

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 for the current payloads and setup.

SDK

If you used the legacy RootFi SDK, switch to @commenda/integrations, 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_ids 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
• Support: [e-mail]