Overview

Fictix is an API for generating believable synthetic companies and using them to test software products. A Fictix company can include accounting data, banking activity, customer and vendor records, payroll, CRM data, tasks, native-shaped connector records, a simulation clock, webhooks, and planted scenarios for evaluating whether another application catches known business issues.

The most important developer idea is simple:

You create a demo job.
Fictix creates a generated company.
You fetch normalized data, exports, events, or native-shaped records.
You load or test that data in your own product.

Start in the Console

The Console is the front door for customers. Create an account or sign in to projects, then generate a company or select an existing one. Use its Connect to your builder panel or Company settings to obtain the runtime URL and project key for server-side code.

This keeps company creation, organization access, billing, key rotation, and webhook administration in one customer-facing place.

See Start In The Fictix Console before following an API quickstart.

What you can build

Use Fictix when you need to:

• create a realistic demo tenant without exposing real customer data
• populate a B2B SaaS product with believable business activity
• generate repeatable accounting, banking, CRM, payroll, task, and commerce data
• test ingestion pipelines against coherent cross-system records
• run scenario-based QA with planted truth, such as ghost employees, delayed payments, duplicate vendors, or reconciliation issues
• give AI agents or eval harnesses a synthetic company to inspect
• reproduce a customer-like state for demos, onboarding, QA, or sales engineering

The main API surface

Approved server-to-server integrations use this normalized control-plane surface:

POST /api/v1/demo-jobs
GET  /api/v1/demo-jobs/{job_id}
GET  /api/v1/demo-jobs/{job_id}/status
GET  /api/v1/demo-jobs/{job_id}/bundle
GET  /api/v1/demo-jobs/{job_id}/entities/{entity}
GET  /api/v1/demo-jobs/{job_id}/entities/{entity}/export

The demo_job resource wraps the lower-level project/runtime implementation and returns stable links, company metadata, dataset counts, quality status, and runtime identifiers in one place.

Base URLs

Use the base URL for the environment you are targeting:

Production:      https://api.fictix.ai
Staging:         https://api-staging.fictix.ai
Runtime handoff: https://staging.fictix.dev/{publish_id}/{service}/...

If your deployment uses a different host, keep the path structure the same and replace only the origin.

Authentication models

Fictix has a public discovery surface, a Console-managed bearer session, and one external credentialed auth layer:

Most customer integrations should use the project runtime key issued in the Console. The signed-in Console can create or control demo jobs with its managed WorkOS bearer session. External integrations may do so only with the Fictix-supplied admin key above. The management surface is not a self-service browser-key flow, and a Console session must never be copied or forwarded.

Response objects

Fictix responses use object names so clients can branch safely:

{
  "object": "demo_job",
  "contract_version": "2026-07-17",
  "id": "8f3a2d11",
  "status": "ready"
}

Common object names:

• demo_job
• demo_job_status
• demo_job_quality
• demo_bundle
• demo_entity_page
• demo_entity_export
• catalog_collection
• test_matrix
• test_run

Environment expectations

For a production-grade integration, plan for:

• idempotent demo job creation
• retries around network failures and 5xx responses
• handling 413 bundle-size responses by paging entities
• storing job_id, runtime.project_id, and runtime.slug
• never storing plaintext runtime API keys unless you need lower-level runtime access
• validating quality.summary before presenting generated data as clean
• using reserved synthetic domains in generated counterparty data

First integration decision

Before writing code, choose one of these integration modes: