Skip to main content

​
Overview

This quickstart will guide you through your first data extraction with Qobra’s V2 API. By the end, you’ll have extracted reporting data from your account. What you’ll learn:
  • How to discover available data structures
  • How to inspect field schemas
  • How to extract data with pagination
Time required: ~5 minutes.
You’ll need a Qobra API key. If you don’t have one, generate it in your Qobra settings.

​
The 3-Step Workflow

1

Discover Data Structures

Find which tables are available in your Qobra account (statements reporting or records reporting)
2

Inspect Field Schema

Get the structure of each table: field names, types, and metadata
3

Extract Data

Pull the actual data with efficient pagination

​
Step 1: Discover Your Data Structures

What’s a data structure? Think of it as a table in Qobra — it could be your statements reporting or records reporting. Endpoint: GET /v2/data-structures 
curl --request GET \
  --url https://api.qobra.co/v2/data-structures \
  --header 'X-API-Key: YOUR_API_KEY'

​
Example Response

{
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "name": "Commission Statements",
      "type": "statement_reporting",
      "total_records": 15420,
      "links": {
        "fields": "https://api.qobra.co/v2/data-structures/507f1f77bcf86cd799439011/fields",
        "records": "https://api.qobra.co/v2/reporting/507f1f77bcf86cd799439011/statements"
      }
    },
    {
      "id": "507f1f77bcf86cd799439012",
      "name": "Sales Opportunities",
      "type": "record_reporting",
      "total_records": 8934,
      "links": {
        "fields": "https://api.qobra.co/v2/data-structures/507f1f77bcf86cd799439012/fields",
        "records": "https://api.qobra.co/v2/reporting/507f1f77bcf86cd799439012/records"
      }
    }
  ]
}
Each data structure includes links that point to the next endpoints you’ll need. Use them to navigate the API naturally.

​
Step 2: Inspect the Field Schema

Now that you know what data structures exist, inspect their fields to understand what data you can extract. Endpoint: GET /v2/data-structures/{table_id}/fields 
curl --request GET \
  --url https://api.qobra.co/v2/data-structures/507f1f77bcf86cd799439011/fields \
  --header 'X-API-Key: YOUR_API_KEY'

​
Example Response

{
  "schema_hash": "a3f5c89b2e1d4f7e9c8b6a3d5e7f9c1b",
  "count": 5,
  "fields": [
    {
      "api_key": "standard.id",
      "name": "ID",
      "type": "string",
      "format": null,
      "origin": "standard",
      "created_at": "2024-01-15T10:30:00Z",
      "currencies": null,
      "enum_values": null,
      "properties": null
    },
    {
      "api_key": "standard.total_commission",
      "name": "Total Commission",
      "type": "object",
      "format": "currency",
      "origin": "standard",
      "created_at": "2024-01-15T10:30:00Z",
      "currencies": ["USD", "EUR", "GBP"],
      "enum_values": null,
      "properties": {
        "value": {
          "type": "number",
          "required": true
        },
        "currency": {
          "type": "string",
          "required": true
        }
      }
    },
    {
      "api_key": "standard.date",
      "name": "Date",
      "type": "date",
      "format": "date",
      "origin": "standard",
      "created_at": "2024-01-15",
      "currencies": null,
      "enum_values": null,
      "properties": null
    },
    {
      "api_key": "standard.status",
      "name": "Status",
      "type": "string",
      "format": "enum",
      "origin": "standard",
      "created_at": "2024-01-15T10:30:00Z",
      "enum_values": ["paid", "pending", "validated"],
      "currencies": null,
      "properties": null
    },
    {
      "api_key": "custom.bonus_attainment",
      "name": "Bonus Attainment",
      "type": "number",
      "format": "percentage",
      "origin": "custom",
      "created_at": "2024-03-20T14:22:00Z",
      "currencies": null,
      "enum_values": null,
      "properties": null
    }
  ]
}
Understanding API Keys:
  • standard. = Standard metric (built-in fields)
  • custom. = Custom metric (your custom fields)
  • datatable. = Data table field (from external sources)
Store the schema_hash! Compare it on future calls to detect when fields have changed.

​
Step 3: Extract Your Data

Now extract the actual records. The API uses ID-based pagination for optimal performance with large datasets. Endpoint: GET /v2/reporting/{table_id}/statements or GET /v2/reporting/{table_id}/records 
curl --request GET \
  --url 'https://api.qobra.co/v2/reporting/507f1f77bcf86cd799439011/statements?limit=1000' \
  --header 'X-API-Key: YOUR_API_KEY'

​
Example Response

{
  "data": [
    {
      "standard.id": "65a1b2c3d4e5f6g7h8i9j0k1",
      "standard.total_commission": {
        "value": 4250.0,
        "currency": "USD"
      },
      "standard.date": "2024-01-01",
      "standard.status": "paid",
      "custom.bonus_attainment": 0.87,
    },
    // ... 999 more records
  ],
  "meta": {
    "next_start_id": "65a1b2c3d4e5f6g7h8i9j999",
    "has_more": true,
    "next_url": "https://api.qobra.co/v2/reporting/507f1f77bcf86cd799439011/statements?start_id=65a1b2c3d4e5f6g7h8i9j999&limit=1000"
  }
}
Always use next_url for pagination when dealing with large datasets.

​
Troubleshooting

Problem: Your API key is invalid or missing.Solution:
  • Verify you’re passing the key in the X-API-Key header (not as a query parameter)
  • Regenerate your API key in Qobra settings
Problem: The data structure ID doesn’t exist.Solution:
  • Call /v2/data-structures first to get valid IDs
  • Don’t hardcode IDs—they may change between environments
Problem: The table exists but has no records yet.Solution:
  • Check total_records in the data structure response
  • Ensure data has been synced into Qobra
Problem: You’re reusing the same start_id or not following next_url.Solution:
  • Always update next_url from meta.next_url after each request

​
Next Steps

Explore All Endpoints

Complete endpoint reference with all parameters
You’re ready! You now know the V2 API workflow. Dive deeper into the sections above or start building your integration.