---
name: fictix
description: Generate and read synthetic-company data (accounting, banking, CRM, payroll, tasks) through the Fictix API — auth layers, canonical entities, and pagination/export conventions.
---

# Fictix

Fictix generates a synthetic company — accounting, banking, CRM, payroll,
tasks, and native-shaped connector records — so you can test a product
against believable, reconciled data, with known issues planted on request.

A customer starts in the Fictix Console (`console.fictix.ai`), not the API:
sign up, generate or select a company, then copy the project API key and
runtime base URL from **Connect to your builder**. Don't try to construct a
company or a key by calling an API directly — there is no self-service
browser-key flow.

Staging also supports organization API keys for all current and future
companies in one organization. An admin creates the key in Organization
settings → Organization API keys. This feature is staging-only; use
`https://api-staging.fictix.ai` and read
`https://fictix-docs.vercel.app/get-started/organization-api-keys.md`.

```bash
export FICTIX_API_ORIGIN="https://api.fictix.ai"       # or api-staging.fictix.ai
export FICTIX_PROJECT_SLUG="<from Console Connect panel>"
export FICTIX_PROJECT_API_KEY="<from Console > Company settings > Company API keys>"
```

## Auth layers — use the narrowest one

| Header | Scope | Where it comes from |
| --- | --- | --- |
| `X-API-Key` | One generated company's runtime routes (`/api/v1/orgs/{slug}/...`) | Console → Company settings |
| `X-API-Key` (organization key, staging only) | All companies owned by one organization | Organization settings → Organization API keys |
| `Authorization: Bearer` | Signed-in Console and direct org-admin flows | Authenticated WorkOS org-user session managed by the Console; never copy it |
| `X-Admin-Key` | Fictix-approved external server-to-server management (`/api/v1/demo-jobs/...`) | `FICTIX_ADMIN_API_KEY` supplied by Fictix |

Never put any of these in browser JavaScript, a public env var, or a repo.

The three exports above support company keys. Organization keys instead use
`FICTIX_API_ORIGIN`, `FICTIX_ORGANIZATION_ID`, and
`FICTIX_ORGANIZATION_API_KEY`. The management credential is the Fictix-supplied
`FICTIX_ADMIN_API_KEY` (sent as `X-Admin-Key`), held by approved partners only.
Never invent other names, ask a user to use email/password auth, or extract a
bearer token from their Console session. The Console manages its own WorkOS
bearer session for Console actions; it is not a copyable customer credential or
an external integration variable.

## Provider APIs and SDKs

Read `https://fictix-docs.vercel.app/guides/connect-your-software.md` and
`https://fictix-docs.vercel.app/api-reference/provider-first-requests.md` before
constructing a provider request. Download public request templates from
`https://fictix-docs.vercel.app/provider-first-requests.json`; supported operations and
limits are in `https://fictix-docs.vercel.app/api-reference/provider-workflows.md`.

Public catalog snapshots observed October 28, 2026 report 60 entries in both
staging and production: 59 marked available/selectable and one FCI execute
preview that is not selectable. All 60 report approximate fidelity. These are
catalog reports, not provider-request tests or a strict upstream parity claim.
The published first-request templates were tested in staging only. Query the
environment's catalog and preserve each request's API version, path, body, and
content type. Native reads need
`read`; native writes need `write` and should send `Idempotency-Key`. FCI uses
the company-scoped execute route with `read` and `execute`; its body `org_id`
is the company project ID. Check application-level errors on HTTP 200. Relay
Financial has no implemented direct API contract.

## Canonical entities

`accounts`, `bank_accounts`, `bank_transactions`, `bills`, `customers`,
`customer_payments`, `deals`, `employees`, `invoices`, `items`,
`journal_entries`, `payroll_runs`, `tasks`, `vendor_payments`, `vendors`.

`payments` is a deprecated alias for `customer_payments`; `bill_payments` is
a deprecated alias for `vendor_payments`. Use the canonical names in new
code.

## Read, paginate, export

Read a company you already have with the project API key:

```bash
curl -sS "$FICTIX_API_ORIGIN/api/v1/orgs/$FICTIX_PROJECT_SLUG/data/customers?limit=100&offset=0" \
  -H "X-API-Key: $FICTIX_PROJECT_API_KEY"
```

- Page with `limit`/`offset`; keep paging while `offset + data.length <
  count`.
- Export an entity as CSV or JSON with `GET
  /api/v1/orgs/{slug}/export/{entity}?format=csv|json`, or pull the full CSV
  ledger bundle with `GET /api/v1/orgs/{slug}/export-pack/csv`.
- Discovery endpoints (`/api/v1/catalog/entities`,
  `/api/v1/catalog/connector-capabilities`) need no credential — use them to
  learn what's available before assuming a service or object type exists.
- Creating or controlling a company (`POST /api/v1/demo-jobs`) is an
  approved server-to-server control-plane surface for external integrations,
  not the first integration path for a normal Console customer. The signed-in
  Console uses its managed WorkOS bearer session; it requires a stable
  `Idempotency-Key` per request: retry only with the *same* key and *same*
  body; a different body with a reused key returns `409`.

## Error handling

Organization keys list company IDs and slugs through
`GET /api/v1/organizations/{org_id}/companies?limit=100&offset=0` with the
same `X-API-Key` header. This directory returns `companies`, a page `count`,
and an overall `total`; continue while `offset + count < total`. Select a
company through its runtime slug for subsequent requests. Organization keys
do not grant company creation, billing, membership, or key management.

- `detail` in an error response may be a plain string or a `{ code, message
  }` object — handle both.
- `413` on `/demo-jobs/{id}/bundle` means the response would exceed the
  bundle cap — page entities or export instead of parsing the record-count
  cap out of the error string.
- `contract_version` is a date-based string (e.g. `"2026-07-05"`) — never
  coerce it to a number.

## Further reading

Full brief: `https://fictix-docs.vercel.app/AGENTS.md` (also in this folder as
`AGENTS.md`). Worked requests: `examples.md` in this folder. Full docs as
Markdown: `https://fictix-docs.vercel.app/llms-full.txt`, or fetch a single page by
appending `.md` to its URL.