Run computations

Run batch and rollover computations with the inputs in your request, or run a scenario computation from an engagement's saved inputs.

GET /api/v1/computations lists the available targets and their dependencies. The computation reference describes each target's input and output cells, required fields, accepted values, and example request.

The batch endpoint also accepts t2_return to compute a return's schedules together, carryforward to derive opening inputs from a source period, and multi_year to compute contiguous periods. Missing facts and unresolved findings remain visible in the results. A blocked carryforward withholds the affected opening inputs. These computations do not establish filing readiness.

Run a batch computation

curl --request POST https://api.filemark.ca/api/v1/computations/batch \
  --header "Authorization: Bearer $FILEMARK_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "compute": [
      "schedule3"
    ],
    "inputs": {
      "taxYear": 2025,
      "workpapers": [
        {
          "id": "wp-dividends-target",
          "templateId": "dividends",
          "linkedAccountIds": [],
          "adjustmentStatus": "ok",
          "customName": "Cedar Ridge 2025 capital dividend",
          "rows": [
            {
              "payerName": "Cedar Ridge Manufacturing Inc.",
              "amountCY": 80000,
              "isConnected": "no",
              "dividendType": "Capital Dividend",
              "direction": "paid",
              "dividendSource": "canadian_taxable",
              "denial112": false,
              "foreignCurrency": "CAD"
            }
          ],
          "sectionRows": {},
          "assumption": "Caller-supplied facts only; no CDA balance, election, recipient/share, payment, or filing verification"
        }
      ]
    }
  }'

import os
import requests

FILEMARK_ACCESS_TOKEN = os.environ["FILEMARK_ACCESS_TOKEN"]

response = requests.post(
    "https://api.filemark.ca/api/v1/computations/batch",
    headers={
        "Authorization": f"Bearer {FILEMARK_ACCESS_TOKEN}",
    },
    json={
        "compute": [
            "schedule3",
        ],
        "inputs": {
            "taxYear": 2025,
            "workpapers": [
                {
                    "id": "wp-dividends-target",
                    "templateId": "dividends",
                    "linkedAccountIds": [],
                    "adjustmentStatus": "ok",
                    "customName": "Cedar Ridge 2025 capital dividend",
                    "rows": [
                        {
                            "payerName": "Cedar Ridge Manufacturing Inc.",
                            "amountCY": 80000,
                            "isConnected": "no",
                            "dividendType": "Capital Dividend",
                            "direction": "paid",
                            "dividendSource": "canadian_taxable",
                            "denial112": False,
                            "foreignCurrency": "CAD",
                        },
                    ],
                    "sectionRows": {},
                    "assumption": "Caller-supplied facts only; no CDA balance, election, recipient/share, payment, or filing verification",
                },
            ],
        },
    },
)
response.raise_for_status()
print(response.json())

const FILEMARK_ACCESS_TOKEN = process.env.FILEMARK_ACCESS_TOKEN;

const response = await fetch("https://api.filemark.ca/api/v1/computations/batch", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${FILEMARK_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "compute": [
      "schedule3"
    ],
    "inputs": {
      "taxYear": 2025,
      "workpapers": [
        {
          "id": "wp-dividends-target",
          "templateId": "dividends",
          "linkedAccountIds": [],
          "adjustmentStatus": "ok",
          "customName": "Cedar Ridge 2025 capital dividend",
          "rows": [
            {
              "payerName": "Cedar Ridge Manufacturing Inc.",
              "amountCY": 80000,
              "isConnected": "no",
              "dividendType": "Capital Dividend",
              "direction": "paid",
              "dividendSource": "canadian_taxable",
              "denial112": false,
              "foreignCurrency": "CAD"
            }
          ],
          "sectionRows": {},
          "assumption": "Caller-supplied facts only; no CDA balance, election, recipient/share, payment, or filing verification"
        }
      ]
    }
  }),
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());

Set compute to 1 to 100 target names and provide inputs, including a four-digit taxYear. Dependencies run automatically. Omit payloadContract and handoff when unused, as these optional fields reject null. See Compute tax schedules for the request fields.

Batch responses group results by target under data.results. Rollover responses use data.result. Each result contains the target's output cells, ready and provisional booleans, and a warnings array. The response also includes computeVersion, engineSchemaVersion, ratesVersion, and timestamp to identify the engine, schemas, rate tables, and computation time.

Each inputs field must be a published cell of a requested target or its dependencies and use the cell's JSON type. Unknown cells and type mismatches return 400 with validation details. A cell set to null is unanswered, and the result reports any unresolved requirements.

Default validation checks cell names, JSON types, and the rollover facts marked always required in the computation reference. Pin a strict contract to validate values against a target's schema.

An object can hold at most 1,000 members, and a request a bounded number of values (413). Nesting is limited to 12 levels (400). Numbers must be finite and at most 1e15 in absolute value (400). Unknown target names return 400.

Get handoff cells

Add handoff to return computed cells using your tax software's import identifiers and value formats.

curl --request POST https://api.filemark.ca/api/v1/computations/batch \
  --header "Authorization: Bearer $FILEMARK_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "compute": [
      "schedule8"
    ],
    "inputs": {
      "taxYear": 2025,
      "fiscalStart": "2025-01-01",
      "fiscalEnd": "2025-12-31",
      "isCCPC": true,
      "daysInYear": 365,
      "pyUCCPools": [
        {
          "ccaClass": "8",
          "closingUCC": 0
        }
      ],
      "assetData": [],
      "dispositions": [],
      "schedule8AdjustmentCoverage": {
        "schemaVersion": 2,
        "reviewed": true,
        "reviewedAt": "2026-07-19T12:00:00Z",
        "column205AdjustmentsApplicable": false,
        "column221AssistanceAfterDispositionApplicable": false,
        "column222RepaymentsAfterDispositionApplicable": false,
        "rentalPropertySeparateClassApplicable": false,
        "purposeBuiltRentalPropertyRulesApplicable": false,
        "rentalIncomeCcaLimitApplicable": false,
        "leasingPropertyRulesApplicable": false,
        "specifiedLeasingPropertyRulesApplicable": false,
        "affiliatedPersonStopLossApplicable": false,
        "reg1101_5qElectionApplies": false,
        "multipleClass10_1VehiclesPresent": false,
        "otherPrescribedSeparateClassRuleApplies": false,
        "specialDispositionRolloverOrDeferralApplies": false,
        "class14_1TransitionalOpeningBalanceApplicable": false,
        "specifiedEnergyPropertyRulesApplicable": false,
        "class1NrbAdditionalAllowanceEligible": false,
        "class1UnmodelledAdditionalAllowanceApplies": false,
        "class12ParagraphHalfYearExclusionApplies": false,
        "diepEligibilityAndAllocationConfirmed": false,
        "capitalGainRoutingComplete": false
      },
      "t2Jacket": {
        "filingStatus": {
          "firstYearAfterIncorporation": false,
          "firstYearAfterAmalgamation": false,
          "subsidiaryWindupS88": false
        }
      }
    },
    "handoff": {
      "vendor": "taxprep"
    }
  }'

import os
import requests

FILEMARK_ACCESS_TOKEN = os.environ["FILEMARK_ACCESS_TOKEN"]

response = requests.post(
    "https://api.filemark.ca/api/v1/computations/batch",
    headers={
        "Authorization": f"Bearer {FILEMARK_ACCESS_TOKEN}",
    },
    json={
        "compute": [
            "schedule8",
        ],
        "inputs": {
            "taxYear": 2025,
            "fiscalStart": "2025-01-01",
            "fiscalEnd": "2025-12-31",
            "isCCPC": True,
            "daysInYear": 365,
            "pyUCCPools": [
                {
                    "ccaClass": "8",
                    "closingUCC": 0,
                },
            ],
            "assetData": [],
            "dispositions": [],
            "schedule8AdjustmentCoverage": {
                "schemaVersion": 2,
                "reviewed": True,
                "reviewedAt": "2026-07-19T12:00:00Z",
                "column205AdjustmentsApplicable": False,
                "column221AssistanceAfterDispositionApplicable": False,
                "column222RepaymentsAfterDispositionApplicable": False,
                "rentalPropertySeparateClassApplicable": False,
                "purposeBuiltRentalPropertyRulesApplicable": False,
                "rentalIncomeCcaLimitApplicable": False,
                "leasingPropertyRulesApplicable": False,
                "specifiedLeasingPropertyRulesApplicable": False,
                "affiliatedPersonStopLossApplicable": False,
                "reg1101_5qElectionApplies": False,
                "multipleClass10_1VehiclesPresent": False,
                "otherPrescribedSeparateClassRuleApplies": False,
                "specialDispositionRolloverOrDeferralApplies": False,
                "class14_1TransitionalOpeningBalanceApplicable": False,
                "specifiedEnergyPropertyRulesApplicable": False,
                "class1NrbAdditionalAllowanceEligible": False,
                "class1UnmodelledAdditionalAllowanceApplies": False,
                "class12ParagraphHalfYearExclusionApplies": False,
                "diepEligibilityAndAllocationConfirmed": False,
                "capitalGainRoutingComplete": False,
            },
            "t2Jacket": {
                "filingStatus": {
                    "firstYearAfterIncorporation": False,
                    "firstYearAfterAmalgamation": False,
                    "subsidiaryWindupS88": False,
                },
            },
        },
        "handoff": {
            "vendor": "taxprep",
        },
    },
)
response.raise_for_status()
print(response.json())

const FILEMARK_ACCESS_TOKEN = process.env.FILEMARK_ACCESS_TOKEN;

const response = await fetch("https://api.filemark.ca/api/v1/computations/batch", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${FILEMARK_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "compute": [
      "schedule8"
    ],
    "inputs": {
      "taxYear": 2025,
      "fiscalStart": "2025-01-01",
      "fiscalEnd": "2025-12-31",
      "isCCPC": true,
      "daysInYear": 365,
      "pyUCCPools": [
        {
          "ccaClass": "8",
          "closingUCC": 0
        }
      ],
      "assetData": [],
      "dispositions": [],
      "schedule8AdjustmentCoverage": {
        "schemaVersion": 2,
        "reviewed": true,
        "reviewedAt": "2026-07-19T12:00:00Z",
        "column205AdjustmentsApplicable": false,
        "column221AssistanceAfterDispositionApplicable": false,
        "column222RepaymentsAfterDispositionApplicable": false,
        "rentalPropertySeparateClassApplicable": false,
        "purposeBuiltRentalPropertyRulesApplicable": false,
        "rentalIncomeCcaLimitApplicable": false,
        "leasingPropertyRulesApplicable": false,
        "specifiedLeasingPropertyRulesApplicable": false,
        "affiliatedPersonStopLossApplicable": false,
        "reg1101_5qElectionApplies": false,
        "multipleClass10_1VehiclesPresent": false,
        "otherPrescribedSeparateClassRuleApplies": false,
        "specialDispositionRolloverOrDeferralApplies": false,
        "class14_1TransitionalOpeningBalanceApplicable": false,
        "specifiedEnergyPropertyRulesApplicable": false,
        "class1NrbAdditionalAllowanceEligible": false,
        "class1UnmodelledAdditionalAllowanceApplies": false,
        "class12ParagraphHalfYearExclusionApplies": false,
        "diepEligibilityAndAllocationConfirmed": false,
        "capitalGainRoutingComplete": false
      },
      "t2Jacket": {
        "filingStatus": {
          "firstYearAfterIncorporation": false,
          "firstYearAfterAmalgamation": false,
          "subsidiaryWindupS88": false
        }
      }
    },
    "handoff": {
      "vendor": "taxprep"
    }
  }),
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());

The response includes data.handoff alongside data.results, with the same values used in Filemark's handoff exports.

{
  "vendor": "taxprep",
  "mappingTableVersion": "0.4.47",
  "vendorEdition": "T2 Taxprep 2024 v.2",
  "cells": [
    { "cellId": "CCACat.FD08C[1].FED.Ttw08cA5", "value": "50000" },
    { "cellId": "CCACat.FD08C[1].FED.Ttw08cA1", "value": "8" }
  ],
  "blocked": null,
  "warnings": []
}

Field	Meaning
`vendor`	Selected tax software, one of `"taxcycle"`, `"taxprep"`, or `"ifirm"`.
`mappingTableVersion`	Version of the Filemark mapping table used for the import identifiers.
`vendorEdition`	Software version used to map the identifiers. Check that your installed version matches before importing.
`cells`	For `taxprep`: `.csv` cell IDs. For `ifirm`: `cells/setdata` cell paths.
`forms`	For `taxcycle`: import field codes grouped by form (`[{form, cells}]`), used in place of `cells`. A `tableClear` entry clears a repeating table.
`warnings`	One `{code, message}` entry per computed cell unsupported by the selected software. Use `code` for error handling and `message` for display.
`blocked`	`null` when the handoff is built. Otherwise, `reason` explains the export restriction or conversion failure, with optional `code`, `action`, and `issues` fields. Computation results remain available in `data.results`.

The handoff covers the requested targets and their dependencies. A t2_return or carryforward request also includes the computed T2 jacket and the Schedule 141 disclosure. A schedule141 request includes the disclosure without the rest of the return. Other requests leave out the jacket, apart from line 727 when you request schedule92. You can combine handoff with payloadContract.

Get the import file

Set handoff.format to "file" to receive an import file for the selected tax software.

"handoff": {
  "vendor": "taxprep",
  "format": "file"
}

The response uses data.handoff.files in place of cells or forms and retains the other handoff fields. Each file's content is base64-encoded, including CSV files.

{
  "vendor": "taxprep",
  "mappingTableVersion": "0.4.47",
  "vendorEdition": "T2 Taxprep 2024 v.2",
  "files": [
    {
      "filename": "filemark_taxprep.csv",
      "mediaType": "text/csv; charset=utf-8",
      "encoding": "base64",
      "content": "W0ZpbGVtYXJrfDB8MF0NCg…"
    }
  ],
  "blocked": null,
  "warnings": []
}

`format`	Result
omitted, or `"json"`	`cells` or `forms`, as above.
`"file"`	`files`. For `taxprep` and `ifirm`: one `.csv`. For `taxcycle`: one `.xlsx` per form.

Pin a strict contract

Set payloadContract to the target's boundaryProfileId and payloadSchemaVersion from the computation reference to validate its inputs and outputs against that schema version.

A contract applies to one directly requested target. An unpublished contract returns 400.
Input validation runs before computation. A mismatch returns 400 with each invalid cell and failed constraint in error.details.
Output validation runs after computation. A result outside the selected schema returns 422 with error.code set to result_not_representable. Use a schema version that supports the result. Engine faults return 500.

Within one payloadSchemaVersion, outputs can gain keys and enum members, bounds can widen, and optional inputs can be added. Removing output keys, changing types, narrowing enums, or tightening input constraints requires a new version. Clients should accept unknown output keys and enum members.

Run a rollover

Send the inputs to the rollover, reorganization, or screening target's path.

curl --request POST https://api.filemark.ca/api/v1/computations/rollovers/section-86 \
  --header "Authorization: Bearer $FILEMARK_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "inputs": {
      "old_shares": {
        "acb": 100000,
        "puc": 80000,
        "fmv": 150000,
        "isCapitalProperty": true,
        "allSharesOfClassDisposed": true,
        "outlaysAndExpenses": 0,
        "priorS53_2_g1DeductionsAmount": null
      },
      "new_shares": [
        {
          "label": "Cedar Ridge Holdings preferred",
          "fmv": 90000,
          "legalStatedCapital": 60000
        },
        {
          "label": "Cedar Ridge Holdings common",
          "fmv": 50000,
          "legalStatedCapital": 50000
        }
      ],
      "boot": {
        "fmv": 10000
      },
      "party": {
        "issuerResidentInCanada": true,
        "s85ElectionFiled": false,
        "inCourseOfReorganizationOfCapital": true,
        "isRelatedReorganization": false,
        "giftToRelatedPerson": 0
      }
    }
  }'

import os
import requests

FILEMARK_ACCESS_TOKEN = os.environ["FILEMARK_ACCESS_TOKEN"]

response = requests.post(
    "https://api.filemark.ca/api/v1/computations/rollovers/section-86",
    headers={
        "Authorization": f"Bearer {FILEMARK_ACCESS_TOKEN}",
    },
    json={
        "inputs": {
            "old_shares": {
                "acb": 100000,
                "puc": 80000,
                "fmv": 150000,
                "isCapitalProperty": True,
                "allSharesOfClassDisposed": True,
                "outlaysAndExpenses": 0,
                "priorS53_2_g1DeductionsAmount": None,
            },
            "new_shares": [
                {
                    "label": "Cedar Ridge Holdings preferred",
                    "fmv": 90000,
                    "legalStatedCapital": 60000,
                },
                {
                    "label": "Cedar Ridge Holdings common",
                    "fmv": 50000,
                    "legalStatedCapital": 50000,
                },
            ],
            "boot": {
                "fmv": 10000,
            },
            "party": {
                "issuerResidentInCanada": True,
                "s85ElectionFiled": False,
                "inCourseOfReorganizationOfCapital": True,
                "isRelatedReorganization": False,
                "giftToRelatedPerson": 0,
            },
        },
    },
)
response.raise_for_status()
print(response.json())

const FILEMARK_ACCESS_TOKEN = process.env.FILEMARK_ACCESS_TOKEN;

const response = await fetch("https://api.filemark.ca/api/v1/computations/rollovers/section-86", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${FILEMARK_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "inputs": {
      "old_shares": {
        "acb": 100000,
        "puc": 80000,
        "fmv": 150000,
        "isCapitalProperty": true,
        "allSharesOfClassDisposed": true,
        "outlaysAndExpenses": 0,
        "priorS53_2_g1DeductionsAmount": null
      },
      "new_shares": [
        {
          "label": "Cedar Ridge Holdings preferred",
          "fmv": 90000,
          "legalStatedCapital": 60000
        },
        {
          "label": "Cedar Ridge Holdings common",
          "fmv": 50000,
          "legalStatedCapital": 50000
        }
      ],
      "boot": {
        "fmv": 10000
      },
      "party": {
        "issuerResidentInCanada": true,
        "s85ElectionFiled": false,
        "inCourseOfReorganizationOfCapital": true,
        "isRelatedReorganization": false,
        "giftToRelatedPerson": 0
      }
    }
  }),
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());

Compute over saved data

POST /api/v1/engagements/{engagement_id}/computations/scenario runs a temporary computation using an engagement's saved inputs and the overrides in your request. It requires tax-data:read and tax:compute.

curl --request POST https://api.filemark.ca/api/v1/engagements/$ENGAGEMENT_ID/computations/scenario \
  --header "Authorization: Bearer $FILEMARK_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "compute": [
      "part_i_tax"
    ],
    "inputs": {}
  }'

import os
import requests

ENGAGEMENT_ID = "<engagement-id>"
FILEMARK_ACCESS_TOKEN = os.environ["FILEMARK_ACCESS_TOKEN"]

response = requests.post(
    f"https://api.filemark.ca/api/v1/engagements/{ENGAGEMENT_ID}/computations/scenario",
    headers={
        "Authorization": f"Bearer {FILEMARK_ACCESS_TOKEN}",
    },
    json={
        "compute": [
            "part_i_tax",
        ],
        "inputs": {},
    },
)
response.raise_for_status()
print(response.json())

const ENGAGEMENT_ID = "<engagement-id>";
const FILEMARK_ACCESS_TOKEN = process.env.FILEMARK_ACCESS_TOKEN;

const response = await fetch(`https://api.filemark.ca/api/v1/engagements/${ENGAGEMENT_ID}/computations/scenario`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${FILEMARK_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "compute": [
      "part_i_tax"
    ],
    "inputs": {}
  }),
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());

Send inputs: {} to compute the engagement as saved. Each supplied field replaces its entire top-level cell for this computation, and null marks it unanswered.

The engagement controls its taxation period and the cells Filemark sets from its prior returns and corporate group. Overrides to taxYear, taxYearId, currentYear, daysInYear, fiscalStart, fiscalEnd, priorTaxYearStart, priorTaxYearEnd, pinnedFormRevisions, or a cell Filemark sets return 400 with the affected cells in error.details. Use the batch endpoint with a full set of inputs to compute a different period.

The response includes results, data.appliedOverrides listing the replaced cells, and data.sourceStateSha256 identifying the saved input snapshot. Overrides apply only to this request. See the scenario reference for response fields.

Export a scenario

Supply scenario.inputs when creating an export job to build a separate draft package and comparison from the engagement's saved inputs and your overrides. The job leaves the saved return unchanged and reports readiness as unevaluated.

Include the scenario computation's sourceStateSha256, computeVersion and ratesVersion to require the same saved inputs, engine version and rate tables. The job records any you leave out when it is created. A change to any of them is reported as a conflict. Reuse the original idempotency key when retrying the same export request, then follow the job's downloadPage to download the package in a signed-in Filemark session.

Run computations

Run a batch computation#

Get handoff cells#

Get the import file#

Pin a strict contract#

Run a rollover#

Compute over saved data#

Export a scenario#