> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qobra.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Fields Schema
> Retrieves the complete schema (field names, types, formats) for a specific data structure. Essential for understanding what fields are available before extracting data.
## 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:
| Prefix | Meaning | Description |
| ------------ | ------------------- | ----------------------------------------------------------- |
| `standard.` | **Standard Metric** | Built-in Qobra fields (commission amounts, periods, status) |
| `custom.` | **Custom Metric** | Your custom commission metrics and calculations |
| `datatable.` | **Data Table** | Fields 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:**
```json theme={null}
{
"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:**
```json theme={null}
{
"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:**
```json theme={null}
{
"standard.user": {
"id": "507f191e810c19729de860ea",
"email": "john.doe@company.com"
},
"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
Fetch schema once, reuse for the entire extraction.
Never use `name` for field identification — it doesn't display when extracting
data.
Store hash and compare on each run to detect changes.
Check for required fields before long extractions.
Call this endpoint **once per extraction session**. Cache the schema for the
duration of your data sync.
## OpenAPI
````yaml get /v2/data-structures/{table_id}/fields
openapi: 3.0.2
info:
version: 2.0.0
title: Qobra API v2
description: >-
Modern data extraction API for Qobra - Optimized for high-volume data
extraction with ID-based pagination and flexible schema discovery.
license:
name: Proprietary
url: https://www.qobra.co/terms
servers:
- url: https://api.qobra.co
description: Production API
security: []
paths:
/v2/data-structures/{table_id}/fields:
get:
tags:
- public_api
- v2
- discovery
summary: Get Fields Schema
description: >-
Retrieves the complete schema (field names, types, formats) for a
specific data structure. Essential for understanding what fields are
available before extracting data.
operationId: GET_/v2/data-structures/(table_id)/fields
parameters:
- name: table_id
in: path
required: true
schema:
type: string
format: ObjectId
description: Unique identifier of the data structure (from /v2/data-structures)
responses:
'200':
description: >-
Successfully retrieved the fields schema for the data structure.
Returns an object with the schema hash and an array of fields.
content:
application/json:
schema:
$ref: '#/components/schemas/FieldsResponse'
examples:
fields-success:
$ref: '#/components/examples/FieldsResponseExample'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedErrorResponse'
examples:
unauthorized-error:
$ref: '#/components/examples/UnauthorizedErrorResponseExample'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundErrorResponse'
examples:
not-found-error:
$ref: '#/components/examples/NotFoundErrorResponseExample'
security:
- api_key: []
components:
schemas:
FieldsResponse:
type: object
properties:
schema_hash:
type: string
description: >-
Hash of the schema (changes when fields are added/modified/removed).
Use to detect schema changes.
count:
type: integer
description: Number of fields in the data structure
fields:
type: array
items:
$ref: '#/components/schemas/FieldModel'
description: List of all fields in the data structure
required:
- schema_hash
- count
- fields
UnauthorizedErrorResponse:
type: object
properties:
message:
type: string
description: Human-readable error message
type:
type: string
enum:
- UnauthorizedError
description: Type of the error
required:
- message
- type
NotFoundErrorResponse:
type: object
properties:
message:
type: string
description: Human-readable error message
resource:
type: string
description: Resource that caused the error
type:
type: string
enum:
- NotFoundError
description: Type of the error
required:
- message
- resource
- type
FieldModel:
type: object
properties:
api_key:
type: string
description: >-
Field identifier to use in API responses (e.g., 'standard.user',
'datatable.amount')
name:
type: string
description: Human-readable name of the field
type:
$ref: '#/components/schemas/FieldCoreType'
format:
allOf:
- $ref: '#/components/schemas/FieldFormat'
type: string
nullable: true
origin:
$ref: '#/components/schemas/FieldOrigin'
created_at:
type: string
format: date-time
description: When this field was created
currencies:
type: array
items:
type: string
nullable: true
description: List of currency codes for currency fields (e.g., ['USD', 'EUR'])
enum_values:
type: array
items:
type: string
nullable: true
description: Allowed values for picklist/multipicklist fields
properties:
allOf:
- $ref: '#/components/schemas/ObjectProperties'
type: object
nullable: true
description: >-
Nested structure for object/reference fields (can be null for
non-object fields)
required:
- api_key
- name
- type
- format
- origin
- created_at
- currencies
- enum_values
- properties
FieldCoreType:
type: string
enum:
- string
- number
- boolean
- date
- array
- object
description: Core data type of the field
FieldFormat:
type: string
enum:
- currency
- percentage
- float
- date
- enum
- group_id
- reference
- user_reference
description: Specific format of the field value (for display/parsing)
FieldOrigin:
type: string
enum:
- standard
- custom
- datatable
description: >-
Origin of the field: standard (Qobra system field), custom (user-defined
metric), datatable (imported CRM/data field)
ObjectProperties:
type: object
description: Structure for OBJECT type fields (e.g., nested user object)
additionalProperties:
$ref: '#/components/schemas/PropertySchema'
PropertySchema:
type: object
properties:
type:
type: string
description: Type of the nested property
required:
type: boolean
description: Whether this property is required
required:
- type
- required
examples:
FieldsResponseExample:
value:
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
UnauthorizedErrorResponseExample:
value:
message: You're trying to access resource you're not authorized to.
type: UnauthorizedError
NotFoundErrorResponseExample:
value:
message: We couldn't find the requested resource
resource: ObjectModel
type: NotFoundError
securitySchemes:
api_key:
type: apiKey
name: X-API-Key
in: header
description: Your Qobra API key. Generate it from Settings > API Keys in Qobra.
````