AdvisorPlan:
a global summary plus a list of AdvisorStrategy recommendations, each with
evidence, an implementation plan, an optional savings estimate, and a status
you can drive. It runs as a background task, so the end-to-end sequence is:
start the run, poll the task until it finishes, read the plan, then accept or
dismiss each strategy. This recipe is the minimal call sequence to do that for
one client.
Every call uses a workspaceToken (see Authentication)
and goes to the single GraphQL endpoint:
AdvisorPlan and AdvisorStrategy field lists, the second trigger path, the
task result member, and the SavingsHorizon enum, see
Tax planning. For the polling mechanics, see
Tasks.
1. Start the run
There are two trigger mutations for an advisor run, both requiring aworkspaceToken and both returning a taskId you poll as a TAX_ADVISOR
task. Use the one that matches how you stage documents.
The Filed web app’s /planning route uses
initiateTaxAdvisor because
the in-app flow stages fresh uploads at the same moment it kicks off the run.
Recommend it as the primary path: upload files first (see
Uploading documents) to get uploadIds, then
call the mutation.
InitiateTaxAdvisorResult.taskId is nullable. A null value means the
ingestion accepted the upload but did not start a task; treat it as a soft
error and retry. See Tax planning, trigger via initiateTaxAdvisor.taskId. You will use it to find the task in the poll step.
2. Poll the task to completion
There is notask(id:) query. Poll the task you just started by listing the
client’s TAX_ADVISOR tasks and reading the entry whose id matches the
taskId returned above. The polling mechanics are documented on
Tasks; the short version:
status is no
longer RUNNING. COMPLETED means the run succeeded and advisorPlan is now
readable; FAILED means it did not, and errorMessage (plus
subTasks[].errorMessage) explains which stage failed.
3. Read the plan
Read the plan throughClient.advisorPlan. There is no top-level advisorPlan
query; reach it through me { ... on WorkspaceUser { workspace { clients(...) { advisorPlan } } } } (see Clients). Call it
without a runId to read the client’s current plan, or pass the runId from
the completed task to read that run’s plan. This recipe passes runId to pin
the read to the run you just polled.
advisorPlan returns null while the run is still RUNNING, or when the
client has no advisor run yet. Treat null as “no plan to show”, and keep
polling the task until status is COMPLETED before re-reading. For the full
AdvisorPlan field list (including taxYear, returnType, byDomain,
bySavingsHorizon, estimatedSavingsCentsByHorizon, and skillsApplied), see
Tax planning, read the plan.4. Update a strategy’s status
Drive each strategy’s workflow status withsetAdvisorStrategyStatus. It
requires a workspaceToken and identifies the strategy with clientId
plus the strategy’s domain and strategyId (both from AdvisorStrategy),
plus the plan’s runId to pin the change to the right run.
The real enum values are PROPOSED, SELECTED, and DISMISSED. Use
SELECTED for strategies the firm accepts, DISMISSED for those it rejects,
and PROPOSED to revert either back to the advisor’s original state. There is
no ACCEPTED value; “accept” maps to SELECTED.
Next steps
Once you have accepted (SELECTED) the strategies you want to act on, the
natural next steps are to work through each strategy’s implementationPlan and
to re-run tax prep so the accepted planning changes flow into the prepared
return. See Run tax prep end to end for that
recipe, and Tax planning for the full reference.