Entities, counts, and lineage

Fictix generates canonical business entities and can also expose native-shaped records for selected services.

Canonical entities are the stable integration layer. Native-shaped records are for testing product integrations that expect a provider-shaped API.

For a Console-created company, obtain the project key and runtime base URL from the Fictix Console before reading entities. Partner /demo-jobs page examples are documented separately in Entities and Exports. Runtime browsing uses /api/v1/orgs/{slug}/data/{entity}.

Canonical entity families

Common canonical entities:

• accounts
• bank_accounts
• bank_transactions
• bills
• customers
• customer_payments
• credit_memos
• deals
• employees
• invoices
• items
• journal_entries
• payroll_runs
• tasks
• vendor_payments
• vendors

Alias behavior:

• payments resolves to customer_payments
• bill_payments resolves to vendor_payments

Prefer canonical names in new integrations.

ASC clinical extensions

Companies created with company.industry: "asc_surgical" also expose:

• operating_rooms
• surgical_cases
• clinical_incidents
• dictation_scripts

These are additive entity families: they are absent from non-ASC companies. dictation_scripts.labels is a synthetic ground-truth extraction answer key, not real clinical documentation. See Healthcare / ASC Data.

Counts

Fictix exposes counts in multiple places:

• demo_job.dataset_summary.record_counts
• GET /api/v1/demo-jobs/{job_id}/status
• entity page response count
• catalog entity metadata

Use counts to:

• decide which loaders to run
• show UI totals
• verify exports
• detect partial loads

Runtime pages

Project-key runtime entity pages use this response shape:

{
  "data": [],
  "count": 0,
  "total_count": 0,
  "limit": 100,
  "offset": 0,
  "next_cursor": null,
  "service": null
}

This example shows an empty page. Runtime responses follow the RuntimeEntityPage schema in the public /openapi.json. count is the total for the requested canonical entity; data contains the current page.

Continue while offset + data.length < count. Advance the next offset by the number of rows actually returned, not by the requested page limit. Stop when offset + data.length >= count; treat an empty page before the reported count as a partial load that needs investigation.

Exports

Entity exports support:

format=json
format=csv

Use JSON when preserving nested structures matters. Use CSV when the host product has spreadsheet or batch-import workflows.

Lineage

Responses that derive from generated data include lineage metadata where available. Lineage is how an integration can answer:

• which generated company produced this record?
• which seed/config generated it?
• which validation certificate applies?
• does this data come from a scenario-injected run?

When loading Fictix data into another product, store lineage alongside imported records when possible.

Recommended host-product columns:

• fictix_job_id
• fictix_entity
• fictix_record_id
• fictix_seed
• fictix_dataset_hash
• fictix_loaded_at

Referential integrity

Fictix aims to keep core references coherent:

• invoices reference customers
• bills reference vendors
• customer payments reference invoices
• applied credit memos link to invoices and match the invoice customer and currency
• vendor payments reference bills
• bank transactions reference bank accounts
• invoice and bill lines reference items
• payroll runs reference employees
• journal entries balance debit and credit totals
• surgical cases reference operating rooms when the ASC pack is selected
• clinical incidents can reference surgical cases and their dictation scripts

Treat missing references as a data quality defect and inspect GET /api/v1/demo-jobs/{job_id}/quality.

Runtime-only integrations should record the project slug and the Console generation timestamp with their own loader result, then use the Console or an approved control-plane flow when they need the full certificate.

Synthetic safety

Generated emails and domains should use reserved namespaces such as:

• .example
• .test
• .invalid

This prevents synthetic data from appearing to belong to real companies or real people.