Migration guide v1 → v2

Do you need to migrate?

Only the reporting endpoints have a v2. v2 is not a new version of the whole API — it is a reporting-focused subset.

If your integration does not call GET /v1/reporting or GET /v1/reporting/{data_table_id}/records, you have nothing to migrate.

Support status of every endpoint

Endpoint	Status	Action
`GET /v1/reporting`	Deprecated	Migrate to fetch statements records
`GET /v1/reporting/{data_table_id}/records`	Deprecated	Migrate to fetch reporting records
`GET /v1/users`	Maintained on v1	Nothing to do
`PUT /v1/users/bulk`	Maintained on v1	Nothing to do
`DELETE /v1/users/archive/bulk`	Maintained on v1	Nothing to do
`PUT /v1/users/groups/bulk`	Maintained on v1	Nothing to do
`PUT /v1/users/managers/bulk`	Maintained on v1	Nothing to do
`GET /v1/tables/{data_table_key}/records`	Maintained on v1	Nothing to do
`POST /v1/tables/{data_table_key}/records/bulk`	Maintained on v1	Nothing to do
`GET /v1/imports/{import_id}`	Maintained on v1	Nothing to do

The deprecated reporting endpoints are still served today and no removal date is announced. As with any breaking change on the Qobra API, you would be notified by email two months in advance. The endpoints maintained on v1 have no end-of-life date — there is no v2 equivalent to move to.

What changes on reporting

Tables are addressed by ID

Statements now take a table_id, discovered through /v2/data-structures

Fields are discoverable

/v2/data-structures/{table_id}/fields returns the exact keys, types and formats of your data

ID-based pagination

offset is replaced by start_id, and the response hands you a ready-made next_url

Incremental syncs

last_modified_after / last_modified_before let you pull only what moved

Endpoint mapping

v1	v2
`GET /v1/reporting`	`GET /v2/reporting/{table_id}/statements`
`GET /v1/reporting/{data_table_id}/records`	`GET /v2/reporting/{table_id}/records`

The v1 statements endpoint took no table in its path. In v2 both endpoints do, so start by listing your data structures to get the table_id to call.

Parameter mapping

v1	v2	Notes
`offset`	`start_id`	Pass the ID of the last record received, or follow `meta.next_url`
`limit`	`limit`	Unchanged in meaning, accepts 1 to 2000
—	`last_modified_after`	New. ISO 8601 datetime, for incremental syncs
—	`last_modified_before`	New. ISO 8601 datetime

Response shape

The envelope changes and the record keys are prefixed.

{
  "count": 4570,
  "next": "https://api.qobra.co/v1/reporting?offset=100&limit=100",
  "data": [
    {
      "id": "6545110915808dbcc34531ef",
      "date": "2023-11-30",
      "payment": 8500.0,
      "payment_currency": "USD",
      "user": { "id": "5537a5b0...", "email": "john-doe@company.com" }
    }
  ]
}

{
  "data": [
    {
      "standard.id": "65a1b2c3d4e5f6g7h8i9j0k1",
      "standard.date": "2024-01-01",
      "standard.total_commission": { "value": 8500.0, "currency": "USD" },
      "standard.user": { "id": "507f191e...", "email": "sarah@company.com" }
    }
  ],
  "meta": {
    "next_start_id": "65a1b2c3d4e5f6g7h8i9j999",
    "has_more": true,
    "next_url": "https://api.qobra.co/v2/reporting/507f.../statements?start_id=65a1b2c3d4e5f6g7h8i9j999&limit=1000"
  }
}

Three differences to handle in your parser:

Envelope: count / next / data becomes data / meta. Page forward with meta.next_url and stop on meta.has_more.
Prefixed keys: every field is namespaced by its origin — standard. for built-in fields, custom. for your custom metrics, datatable. for data table fields.
Currency amounts: the v1 pair <field> + <field>_currency becomes a single object { "value": …, "currency": … }.

Field keys are specific to your account. Do not guess them from this page — read them from the fields endpoint, which returns every api_key with its type, format, currencies and enum values.

Migrate in three steps

Find your table_id

Call GET /v2/data-structures. Each entry carries its id, its type (statement_reporting or record_reporting) and links pointing at the endpoints to call next.

Map your fields

Call GET /v2/data-structures/{table_id}/fields and match each v1 key you consume to its v2 api_key. Store the returned schema_hash to detect later schema changes.

Switch your extraction loop

Replace the offset loop with meta.next_url, and unwrap currency objects where your v1 code read a _currency sibling key.

The quickstart runs these three calls end to end, with cURL, Python and JavaScript snippets you can copy. Your API key is unchanged — the same X-API-Key header authenticates both versions, and v1 and v2 can run side by side while you test.

Checklist

My ETL reads /v1/reporting with offset pagination

Call /v2/data-structures once to resolve the statement reporting table_id, then paginate with meta.next_url instead of incrementing offset.

My warehouse schema has <field>_currency columns

Those columns disappear. Read value and currency from the field’s object instead, or flatten it back to two columns in your transformation layer.

I only push users, groups and managers to Qobra

Nothing to migrate. Those endpoints stay on v1 and are maintained.

I need to detect when fields change

Compare the schema_hash returned by the fields endpoint between two runs. This has no v1 equivalent.

Next steps

Quickstart Guide

Run the three v2 calls end to end in 5 minutes

Endpoints Reference

Every v2 parameter and response field

Need a hand? Reach us at support@qobra.co or through the in-app chat.

Inbound data integrations

Outbound data integrations

Public API Documentation

Authentication

Do you need to migrate?

Support status of every endpoint

What changes on reporting

Tables are addressed by ID

Fields are discoverable

ID-based pagination

Incremental syncs

Endpoint mapping

Parameter mapping

Response shape

Migrate in three steps

Checklist

Next steps

Quickstart Guide

Endpoints Reference

​Do you need to migrate?

​Support status of every endpoint

​What changes on reporting

Tables are addressed by ID

Fields are discoverable

ID-based pagination

Incremental syncs

​Endpoint mapping

​Parameter mapping

​Response shape

​Migrate in three steps

​Checklist

​Next steps

Quickstart Guide

Endpoints Reference

Do you need to migrate?

Support status of every endpoint

What changes on reporting

Endpoint mapping

Parameter mapping

Response shape

Migrate in three steps

Checklist

Next steps