Docs

Definitions

Organization

Your API client belongs to one organization: the firm's Filemark workspace. The access token identifies the organization, so no request carries an organization ID, and a resource in another organization returns 404. A delegated token is narrowed further, to the clients its user can see.

Clients, entities, and tax years

Records form a tree, and each level is addressed by a stable UUID:

  • Client: the firm's end customer.
  • Entity: a legal entity belonging to a client, with its registered name, corporation number, business number, and incorporation details when known.
  • Tax year: one taxation-year engagement for an entity, with its fiscal period and workflow status.

The REST reference lists every field. GET /api/v1/clients/{client_id}/entities and GET /api/v1/entities/{entity_id}/tax-years walk the tree; GET /api/v1/search and GET /api/v1/engagements find engagements directly.

Engagements

"Engagement" and "tax year" name the same record: the engagement ID that /api/v1/engagements/... operations take is the tax year's UUID.

An engagement carries a workflow status, a source (prepared in Filemark or imported as a prior-year reference), an optional service type, a lock flag, and return lifecycle metadata: revision number, filing time, and links to the engagement it amends or that amends it.

An amended return is a new engagement revision linked to its parent. Get engagement context resolves the revision you asked for and the current one; Get engagement history lists the chain, up to 100 revisions, without edit diffs or the people involved.

Saved data

Saved data is what Filemark has stored for an engagement. These reads return it unchanged:

  • Trial balance: active accounts with their balances, before any adjusting entries or tax adjustments, each with its GIFI code. GIFI is the CRA's standard chart of accounts for financial statements filed with a return.
  • Account and adjustments: the saved classification, the accepted GIFI mapping, posted book adjusting entries, and the workpaper tax-adjustment sources linked to the account.
  • Documents and workpapers: registry metadata only. File contents and workpaper payloads are never returned.
  • Review summary: persisted review indicators such as sign-offs and review marks, not a filing-readiness verdict.

A form catalog sits beside the saved data: the production forms whose declared tax-year window covers the engagement's year. It is support metadata, not a determination that the client must file a form.

Computation targets and cells

A target is one computation the engine publishes: a schedule, or a named result other schedules consume. A cell is one addressable input or output of a target, named by a dotted path such as schedule24.operationCode, with a published JSON type. A dependency is a target another target needs; batch dependencies run automatically and their results come back alongside.

Batch targets are computed together from one request. Rollover, reorganization, and screening targets each run alone by path.

Nothing a computation reads comes from a workspace unless you call the saved-state scenario operation. Run computations covers both, the default input boundary, the strict payloadContract option, and handoff, which returns computed cells as the receiving tax software's import identifiers.

Filemark | Definitions