Skip to main content
GET
/
v2
/
data-structures
/
{table_id}
/
fields
Get Fields Schema
curl --request GET \
  --url https://api.qobra.co/v2/data-structures/{table_id}/fields \
  --header 'X-API-Key: <api-key>'
{
  "schema_hash": "a3f9d8c7b2e1",
  "count": 6,
  "fields": [
    {
      "api_key": "standard.id",
      "name": "ID",
      "type": "string",
      "format": null,
      "origin": "standard",
      "created_at": "2024-01-01T00:00:00Z",
      "currencies": null,
      "enum_values": null,
      "properties": null
    },
    {
      "api_key": "standard.user",
      "name": "User",
      "type": "object",
      "format": "user_reference",
      "origin": "standard",
      "created_at": "2024-01-01T00:00:00Z",
      "currencies": null,
      "enum_values": null,
      "properties": {
        "id": {
          "type": "string",
          "required": true
        },
        "email": {
          "type": "string",
          "required": true
        }
      }
    },
    {
      "api_key": "standard.date",
      "name": "Date",
      "type": "string",
      "format": "date",
      "origin": "standard",
      "created_at": "2024-01-01T00:00: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-01T00:00:00Z",
      "currencies": [
        "USD",
        "EUR"
      ],
      "enum_values": null,
      "properties": {
        "value": {
          "type": "number",
          "required": true
        },
        "currency": {
          "type": "string",
          "required": true
        }
      }
    },
    {
      "api_key": "standard.status",
      "name": "Status",
      "type": "string",
      "format": "enum",
      "origin": "standard",
      "created_at": "2024-01-01T00:00:00Z",
      "currencies": null,
      "enum_values": [
        "paid",
        "pending",
        "validated",
        "cancelled"
      ],
      "properties": null
    },
    {
      "api_key": "custom.quota_attainment",
      "name": "Quota Attainment",
      "type": "number",
      "format": "percentage",
      "origin": "custom",
      "created_at": "2024-01-15T10:30:00Z",
      "currencies": null,
      "enum_values": null,
      "properties": null
    }
  ]
}

​
Overview

This endpoint returns the complete field schema for a specific data structure. It tells you what fields are available, their types, formats, and constraints — enabling dynamic adaptation to your data structure.
Schema discovery is a V2 superpower. You no longer need to guess what fields exist — the API tells you.

​
Understanding API Key Prefixes

Every api_key starts with a prefix that indicates its origin:
PrefixMeaningDescription
standard.Standard MetricBuilt-in Qobra fields (commission amounts, periods, status)
custom.Custom MetricYour custom commission metrics and calculations
datatable.Data TableFields from external sources (CRM, databases)
Why it matters:
  • standard. fields are consistent across all Qobra accounts
  • custom. and datatable. fields are specific to your account
  • Always use api_key (not name) as your code identifier
Best practice: Map by api_key, display by name. Use api_key in your database/code, but show users the human-readable name.

​
Field Types Reference

​
Type: number

Used for: Numeric values (integers, decimals, percentages) Formats:
  • "percentage": Decimal percentage (0.85 = 85%)
  • "float": Floating point number
In extracted data: 
{
  "custom.quota_attainment": 0.87,
  "datatable.deal_size": 50000
}

​
Type: string

Formats:
  • "enum": Limited set of allowed values
  • null (no format): Free text
In extracted data: 
{
  "standard.status": "paid",
  "datatable.account_name": "Acme Corporation"
}

​
Type: object

Used for: Nested structures (currency amounts, user reference, record reference) Includes: properties field describing nested structure In extracted data: 
{
  "standard.user": {
    "id": "507f191e810c19729de860ea",
    "email": "[email protected]"
  },
  "standard.record": {
    "id": "507f191e810c19729de860ea",
    "name": "John Doe"
  },
  "standard.total_commission": {
    "value": 4250.0,
    "currency": "USD"
  }
}

​
Schema hash: Detecting changes

The schema_hash is a cryptographic fingerprint of your schema. It changes when a field is added, removed, or modified.
Store schema_hash after each successful sync to detect schema drift in production.
Recommended workflow: Fetch fields at the start of each extraction, compare schema_hash to your stored value, and only remap fields when it changes.

​
Best practices

Cache schema during session

Fetch schema once, reuse for the entire extraction.

Always use api_key

Never use name for field identification — it doesn’t display when extracting data.

Monitor schema_hash

Store hash and compare on each run to detect changes.

Validate before extraction

Check for required fields before long extractions.
Call this endpoint once per extraction session. Cache the schema for the duration of your data sync.

Authorizations

​
X-API-Key
string
header
required

Your Qobra API key. Generate it from Settings > API Keys in Qobra.

Path Parameters

​
table_id
string<ObjectId>
required

Unique identifier of the data structure (from /v2/data-structures)

Response

Successfully retrieved the fields schema for the data structure. Returns an object with the schema hash and an array of fields.

​
schema_hash
string
required

Hash of the schema (changes when fields are added/modified/removed). Use to detect schema changes.

​
count
integer
required

Number of fields in the data structure

​
fields
object[]
required

List of all fields in the data structure