Quantum data extracts: Format and delivery guide
Understand the files you receive, validate deliveries, and load Quantum data into your reporting systems.
Table of Contents
Quantum data extracts deliver your organization’s Approvals & Disclosures data as files for external reporting, analytics, and integrations. Your data team can download the files from Data extracts in the admin panel or collect them over SFTP, then load them into your reporting system or data warehouse.
This guide is for administrators, data engineers, and reporting teams. You do not need an existing Lextegrity integration. If you are migrating one, also read Moving from Lextegrity to Quantum data extracts.
Start with the basics
| Term | What it means |
|---|---|
| Dataset | A table of related information, such as disclosures, form answers, or users. Each record set is delivered in one extract file. |
| Record | One request, disclosure, or attestation. Its record_id connects it to related data. |
| Unit | The primary form response or an individual benefit/spend line within a record. One record can have several units. |
| Party and user | A party is a person or organization. A user is a sign-in account. Their identifiers are different. |
| Row key | The column or combination of columns that uniquely identifies a row. Use the whole key when applying changes. |
| Cutoff | The point in time represented by the extract. It is different from the time files arrive. |
| Full extract | A complete snapshot of the exported dataset at a cutoff. |
| Delta extract | Rows inserted, updated, or deleted since the last successful delivery. |
| Manifest | A JSON file identifying the extract file and its validation information. Think of it as the delivery’s packing list. |
| Baseline | The dataset state against which subsequent changes are compared. |
Choose the datasets for your report
| Reporting goal | Start with | Add when needed |
|---|---|---|
| Disclosure volumes, status, and outcomes | records | users for submitters; record_responses for answers |
| Benefit or spending analysis | records + record_units | record_unit_parties + parties for participant shares |
| Answers across forms | record_responses | records for status; question and form-version identifiers for context |
| Approval progress and activity | approval_steps + record_actions | records + users |
| Tasks and follow-up | tasks | task_parties + parties |
| Risk reporting | risk_scores + risk_score_factors | records; only risk-enabled record types have scores |
| People and access | parties + users | Address, attribute, relationship, role, group, and capability datasets |
| Delivery monitoring | extract_log | The corresponding manifest and extract file |
Before you connect
- Identify the owner of your data pipeline and the reports or systems that will use it.
- Open Data extracts in the admin panel. Use SFTP access to view the connection details and manage SSH connection setup. This configuration is self-service for authorized administrators. Access is isolated by customer.
- Obtain the column catalog and sample full, delta, and manifest files for your integration. The catalog should identify ordered headers, data types, nullability, row keys, relationships, and schema version. The tables and examples below explain how to use the data; examples show selected columns rather than complete file layouts.
- Agree delivery monitoring, file retention and retrieval arrangements, the initial full load, and recovery procedures with your Case IQ team.
- Test the complete download, validation, and loading process before relying on reports.
Download extracts in Quantum
- Open Data extracts in the admin panel and select Downloads.
- Under Latest extracts, locate one of the three most recent extracts. Each entry shows its kind, cutoff date and time, and file count.
- Expand the entry to view its available files and download the files you need.
- For older extracts, use Folders. Select the month, using Newer year or Older year when needed, then locate the relevant extract.
- Check the dataset, extract kind, and cutoff before loading files into your reporting system. Follow the validation steps below.
The three entries under Latest extracts are shortcuts to recent deliveries, not a three-extract retention limit. File counts describe the delivery and do not indicate the number of rows.
What a delivery contains
Each dataset (record set) arrives as one gzip-compressed CSV extract file and a JSON manifest. CSV stores data in rows and columns; gzip reduces the download size. The manifest identifies the extract file and provides its row count, byte size, and SHA-256 checksum for validation. It is written after that dataset’s extract file.
Files are organized in a monthly YYYY-MM folder. The following illustrative names identify the dataset, extract kind, and UTC cutoff. Use the filename provided in the manifest rather than constructing it:
{dataset}_{full|delta}_{cutoff}.csv.gz
{dataset}_{full|delta}_{cutoff}_manifest.jsonFor illustration, a US-region delivery for the October 27, 2026 cutoff could be named:
records_delta_20261027T050000Z.csv.gz
records_delta_20261027T050000Z_manifest.jsonSchedule and reporting cutoff
Extracts run every calendar day with a reporting cutoff of 01:00 local time: America/New_York for the US region and Europe/Paris for the EU region. All datasets in a run share one cutoff. Data timestamps and filename cutoffs use UTC, so the UTC equivalent changes with daylight saving time.
The delivery target is 06:00 local time on ordinary days and 09:00 local time on the first of each month, when the monthly full is also produced. The cutoff describes the data, not its arrival time. Use your agreed service arrangements for operational monitoring.
Full and delta extracts
| Kind | Contents | Use |
|---|---|---|
| Full | Complete exported state at the cutoff; no delta-only columns. | Initialize or reconcile your reporting tables. Generated on the first of each month alongside that day’s delta; authorized Case IQ operators can also request an ad-hoc full. |
| Delta | Changes compared with the last successful delivery. change_type and extract_cutoff are appended to the normal columns. | Apply changes to your existing tables using the dataset’s complete row key. |
Changes are determined by comparing exported states, not by filtering a row’s last-updated timestamp. Monthly fulls reset the delivery baseline.
| change_type | Meaning | Recommended processing |
|---|---|---|
| insert | A row appears in the newly delivered state. | Create the row by its key. |
| update | A previously delivered row has changed. | Replace/update the row by its key using the delivered values. |
| delete | A previously delivered row is no longer present. The delta carries its key and last delivered values. | Remove the row from your current-state table, or mark it deleted in a separate history design. |
Example: initialize, update, and refresh
The following is a recommended loading approach for a current-state reporting table:
- First load: validate a full extract, load it into a staging table, then make it your reporting baseline. For example, an ad-hoc October 30 full contains records R1 and R2.
- Next delivery: the October 31 delta updates R1, inserts R3, and deletes R2. After applying it, your table contains the latest R1 and R3.
- Monthly refresh: validate the November 1 full and use it to reconcile or replace the current-state table at that cutoff. That full already represents the state at the November 1 cutoff; do not apply the same-cutoff delta as additional changes on top of it. If you maintain a separate change-history store, process the delta there under its own checkpoint.
- Continue: apply subsequent deltas in cutoff order. Record the dataset, cutoff, kind, and processed file identity so retries are safe.
R1–R3 are simplified example IDs. Real Quantum identifiers are UUIDs. Test your chosen full-refresh and history-retention approach before production use.
CSV and field format
| Property | Format |
|---|---|
| Encoding | UTF-8 without a byte-order mark (BOM). |
| CSV structure | RFC 4180, comma delimiter, LF line endings, double-quoted text. Use a CSV-aware parser that supports commas, quotes, and line breaks inside quoted values. |
| Headers | Lowercase snake_case. |
| Nulls | An empty field means null; do not automatically convert it to zero or false. |
| Timestamps | YYYY-MM-DDTHH:MM:SSZ in UTC. |
| Dates | YYYY-MM-DD. |
| Booleans | true or false. |
| Numbers | Decimal point, no grouping separators; monetary amounts use four decimal places. |
| Identifiers | UUIDs represented as text. Preserve them as identifiers. |
| Codes and labels | A corresponding <column>_label is included where a human-readable label exists. |
| One-to-many data | Separate rows in child datasets, not JSON lists or objects in a cell. |
Common metadata
tenant_slug identifies the customer. Depending on the dataset, created_at, updated_at, created_by_user_id, and updated_by_user_id describe creation and updates. Creator/updater fields in record_actions and approval_steps are empty because their source rows do not record those values; use the workflow actor fields for event attribution. Do not assume every dataset has the same metadata columns.
Dataset reference and row keys
Quantum provides the following 21 datasets. A + means all listed columns together form the row key.
| Dataset | What one row represents | Row key |
|---|---|---|
| records | One request, disclosure, or attestation | record_id |
| record_units | One primary response or benefit/spend line | unit_id |
| record_unit_parties | One participant’s share of a benefit/spend line | allotment_element_id |
| record_responses | One answered question on a unit; one row per selected option for multi-select | answer_id |
| record_actions | One workflow event | action_id + action_source |
| approval_steps | One approver seat on a stage in an approval run; also includes stages without approvers | stage_id + approver_user_id |
| attachments | One file link from an answer, record, comment, or task | attachment_id + link_source + link_id |
| tasks | One task | task_id |
| task_parties | One party linked to a task | task_id + party_id |
| parties | One person or organization, including its active FMV version where applicable | party_id |
| party_addresses | One address | address_id |
| party_attributes | One customer-defined attribute value on a party | party_id + attribute_key |
| party_relationships | One directed relationship, stored once | relationship_id |
| users | One sign-in account | user_id |
| user_roles | One role assignment | assignment_id |
| role_capabilities | One capability on a role | role_id + capability_key |
| user_groups | One user admitted to an approver group by one membership rule | group_id + user_id + rule_id |
| user_capability_exceptions | One per-user capability grant or deny | exception_id |
| risk_scores | One record’s current risk score | record_id |
| risk_score_factors | One factor cited for a record’s risk score | record_id + factor_key |
| extract_log | One extract file delivery entry | file_id |
Handle special keys explicitly. An approval stage with no approvers has an empty approver_user_id; retain that stage row rather than discarding it. A person admitted to a group by two rules has two rows, so group_id + user_id alone is not unique. For multi-select answers, retain each individual response row and apply changes by answer_id, not by question alone.
Read records, units, and amounts
Start with records for status, submission dates, decisions, outcome, and submitter references. Join record_units using record_id. Use unit_kind and is_primary to distinguish the primary response from benefit/spend lines.
Read approval status from records.status. The primary response unit can remain open after its record is decided. Record statuses are open, info_requested, on_hold, approved, rejected, closed, canceled, expired, update_pending, and retired. Other datasets have their own status vocabularies.
On spend lines, value_amount/value_currency preserve entered amounts; normalized_amount/normalized_currency hold reporting-currency values. Participant shares in record_unit_parties distinguish requested, approved, and actual amounts. A record’s total_amount sums its non-removed spend lines in reporting currency and is null when there are no such lines.
Worked example: one disclosure across several files
Suppose a disclosure includes two benefit lines: 100 USD and 50 USD. Its primary form also contains a multi-select answer with two selected options.
These illustrative CSV excerpts show selected columns only. IDs are shortened for readability, and the choices and amounts are fictional. Actual files contain the complete dataset headers and UUID identifiers.
1. The record
record_id,status,total_amount
"R1","approved",150.00002. Its units
unit_id,record_id,unit_kind,is_primary,value_amount,value_currency,normalized_amount,normalized_currency
"U1","R1","response",true,,,,
"U2","R1","support",false,100.0000,"USD",100.0000,"USD"
"U3","R1","support",false,50.0000,"USD",50.0000,"USD"records.record_id = record_units.record_id connects R1 to all three units. U1 holds the primary response; U2 and U3 are spend lines. The record’s reporting total is 150, not three times 150.
3. Its multi-select answer
answer_id,record_id,unit_id,question_key,value_code,value_label
"F1","R1","U1","benefit_categories","meal","Meal"
"F2","R1","U1","benefit_categories","travel","Travel"record_responses.unit_id = record_units.unit_id links both answers to U1. Use record_id to relate them to R1. Two selected options mean two rows, not two disclosures.
Avoid double-counting: count distinct record_id for disclosure counts. Aggregate spend lines to one row per record before joining them to answers or participant shares. Joining two spend lines to two selected options by record alone produces four rows and can double the apparent spend.
Read form answers and attachments
record_responses identifies the form version, question, unit, and answer. Keep the form-version and question identifiers with the answer so reports retain its context. Fields such as semantic_key and reporting_concept provide additional reporting context where populated.
| Fields | Meaning |
|---|---|
| value_text | Text answer. |
| value_number | Numeric or currency amount. |
| value_date + value_date_end | Date or the start and end of a date range. |
| value_code + value_label | Coded answer and readable label; value_code carries the currency code for a currency answer. |
| value_ref + value_ref_name | Reference and display name for an item such as a party, department, country, or cost center. |
| converted_amount + converted_currency_code | Currency-answer amount converted to the comparison currency. These are response fields, distinct from normalized_amount/normalized_currency on spend lines. |
Currency-answer example
A fictional answer entered as 100 EUR and converted to 110 USD would appear in these selected columns. The exchange result is illustrative, not a current exchange rate.
answer_id,value_number,value_code,converted_amount,converted_currency_code
"F3",100.0000,"EUR",110.0000,"USD"Use the entered amount and currency when showing what the submitter answered. Use the converted pair for comparison-currency analysis. Do not add a currency answer to spend totals merely because it contains a monetary value.
Attachments from answers, records, comments, and tasks are exported as metadata, not file contents. Use link_source and link_id to identify the linked item, and consult the current column catalog for the supported source values. Retain the complete attachment/link key because one file can have multiple links.
Read people and access information
A party is a person or organization; a user is a sign-in account. Join submitter, approver, and actor *_user_id fields to users.user_id. Join documented party references to parties.party_id. These identifiers are not interchangeable.
Party types include candidate, employee, external_person, and organization. User statuses are active, locked, deactivated, and deleted. Addresses, attributes, and directed relationships have separate child datasets. Role assignments and capability exceptions include effective dates. Group memberships are derived from rules at the cutoff. Parties include only the active fair-market-value (FMV) version.
Read workflow and risk information
record_actions contains workflow events, with action_source identifying their source. approval_steps describes approval runs, stages, and approver seats. A seat represents an individual approver’s participation; a step with several approvers can therefore produce several rows.
Use stage_phase for phase context, stage_sequence for ordering, and stage_kind for review versus approval. stage_scope distinguishes record-wide and participant/benefit scope. Keep run and stage identifiers when interpreting repeated approval activity. Apply delivered seat deletions when processing reassignment instead of assuming every former seat remains as an inactive row.
risk_scores contains the current bucket (low, med, high, or critical), brief, rationale, and scoring time. Only risk-enabled record types have rows. risk_score_factors contains factors cited by the model, their direction (increases or decreases), and explanatory detail. These are current assessments, not a complete questionnaire-rule list or score history. Numeric risk scores and manual score adjustments are not included.
Validate and load a delivery
- Wait for each expected dataset’s manifest. It is written after that dataset’s extract file.
- Check completeness and integrity. Confirm the listed extract file exists; validate its byte size and SHA-256 checksum; reconcile its row count.
- Decompress and parse the extract file. Use the dataset’s column catalog and a CSV-aware parser. Check headers and schema version before loading.
- Apply the data. Load a full as a baseline or refresh. Apply deltas using the complete row key and change_type. Stage and validate data before replacing a working reporting table.
- Save a processing checkpoint only after ingestion succeeds. Record dataset, cutoff, kind, and file identity. Make retries safe so they do not duplicate rows.
- Monitor the entire run. One dataset’s manifest does not mean every dataset has arrived. Datasets can be retried independently. For reports joining datasets, use a common completed cutoff.
Empty is different from missing. A header-only CSV is a valid empty result. An empty delta means no changes; it does not mean clear the table. An empty full represents an empty exported dataset at that cutoff. A missing expected extract file or absent manifest requires investigation.
Delivery success is different from ingestion success. If Quantum delivered a file successfully but your loader failed, the next delta is not guaranteed to repeat those changes. Recover and process the missed delivery before advancing. If it cannot be recovered, coordinate a new full baseline with Case IQ.
Use the delivery log
extract_log includes file_id, run_id, dataset, filename, folder, kind, cutoff, trigger, status, publication time, row/change counts, byte size, SHA-256, schema version, retry reference, and customer identifier. Statuses are published, failed, and superseded; triggers are scheduled or operator. This delivery log is separate from the internal application audit trail and from your own ingestion checkpoints.
Data boundaries
- Draft records and draft units are excluded.
- Soft-removed rows remain with removal or retirement timestamps. Hard deletes appear as delta delete rows.
- Anonymous records mask submitter and creator/updater identities. Event actor fields are also masked when the actor is the anonymous submitter. These expected blanks are not processing errors.
- Attachment contents, internal storage paths, and the internal application audit trail are not delivered.
- Party extracts exclude national ID, date of birth, and additional emails, phones, and websites. Only the active FMV version is included.
- Migrated records contain status transitions derived during migration, not Lextegrity’s complete per-action history.
Technical reference and help
Use the dataset and key reference, format rules, and worked examples above when designing your integration. Obtain the complete column catalog and sample files from your Case IQ team for parser implementation, including column order, types, nullability, relationships, and the manifest’s exact property names.
For help with access, delivery monitoring, retrieving missed files, or an ad-hoc full, contact your Case IQ team. For a processing issue, include the dataset, cutoff, full/delta kind, manifest or filename, error, and failed checksum, size, or row-count checks. Include only the data needed to investigate.
Reporting extracts versus inbound HR sync
Reporting extracts move data out of Quantum to your reporting systems. HR sync moves employee data into Quantum. The application’s Data management → SFTP HR data sync area configures inbound folders and mappings; use the extract-specific connection details for outbound reporting.
For inbound employee files, see Configure HR data sync and SFTP intake.