Definitions

Organization#

An organization is a firm's Filemark workspace. The access token identifies your API client's organization. Requests for records in another organization return 404. A delegated token can access the clients visible to its user.

Clients, entities, and tax years#

A client is a customer of your firm. Each client has legal entities, and each entity has tax-year engagements. Entity records include the registered name, corporation number, business number, and incorporation details where available. Tax-year records include the fiscal period and workflow status. Each record has a stable UUID.

Use GET /api/v1/clients/{client_id}/entities to list a client's entities, then GET /api/v1/entities/{entity_id}/tax-years to list an entity's tax years. You can also find engagements through GET /api/v1/search or GET /api/v1/engagements. The REST reference lists the returned fields.

Engagements#

An engagement represents an entity's tax year. Use the tax year's UUID as the engagement ID in /api/v1/engagements/... operations.

An engagement records its workflow status, source, optional service type, lock status, revision number, and filing time. The source identifies whether the return was prepared in Filemark or imported as a prior-year reference. Links connect amended returns to their earlier and later revisions.

Get engagement context returns the requested and current revisions. Get engagement history lists up to 100 linked revisions with amendment metadata.

Computation targets and cells#

A target is a schedule computation or a named result used by other schedules. Each input or output is a cell with a JSON type and a dotted path, such as schedule24.operationCode. A target's dependencies are the other targets it needs to compute its result.

Batch requests compute the requested targets and their dependencies together and return all their results. Rollover, reorganization, and screening targets run individually at their own paths.

Computations use the inputs in your request. Scenario computations use an engagement's saved inputs with any overrides you supply. Run computations covers both methods, input validation, strict contracts, and handoff to tax software.