Task Triggers - Filed Engineering

Task trigger mutations start background work and return a taskId. Use the Tasks API to poll that task until it is no longer RUNNING. Task triggers are reached through the me flow as a WorkspaceUser, so authenticate with a workspaceToken. All requests go to:

https://router.apps.filed.com/graphql

This page is optimized for Filed MCP tools and AI agents. It spells out the minimal mutation sequence for tax prep and data entry so agents do not need to infer trigger arguments from product UI code.

Shared return type

Both triggerTaxPrep and triggerDataEntry return TriggerTaskResult.

type TriggerTaskResult {
  taskId: ID!
}

taskId

ID!

The background task ID. Poll it through Tasks or through the client’s task list until the task reaches COMPLETED or FAILED.

Trigger tax prep

triggerTaxPrep starts a TAX_PREP task for a client. The task extracts forms, reconciles data, and can optionally continue into data entry if the tax software fields are provided.

mutation TriggerTaxPrep($input: TriggerTaxPrepInput!) {
  triggerTaxPrep(input: $input) {
    taskId
  }
}

input TriggerTaxPrepInput {
  taskId: ID
  clientId: ID!
  returnType: ReturnType!
  software: String
  softwareConnectionId: ID
  softwareClientId: String
  softwareClientVersion: String
  runDataEntry: Boolean
  forceReconcile: Boolean
  force: Boolean
  skills: RunSkillSelectionInput
}

enum ReturnType {
  F1040
  F1041
  F1065
  F1120
  F1120S
  F990
}

input RunSkillSelectionInput {
  workspace: [String!]
  user: [String!]
}

Arguments

input.clientId

ID!

required

The client to run tax prep for.

input.returnType

ReturnType!

required

The return form for the client: F1040, F1041, F1065, F1120, F1120S, or F990.

input.taskId

Optional existing tax prep task ID. Pass this when reusing or re-running a specific tax prep task. Omit it to start a fresh task.

input.software

String

The tax software provider key. Use this with softwareConnectionId and softwareClientId when the run should prepare for or continue into data entry.

input.softwareConnectionId

The Filed connection ID for the tax software integration.

input.softwareClientId

String

The client identifier inside the tax software.

input.softwareClientVersion

String

Optional software-specific client version string.

input.runDataEntry

Boolean

When true, tax prep continues into data entry during the same run. Provide software, softwareConnectionId, and softwareClientId when setting this.

input.forceReconcile

Boolean

When true, reconciliation runs again even if an earlier reconciliation result exists.

input.force

Boolean

When true, start a run even when an existing tax prep task is already running for the client.

input.skills

RunSkillSelectionInput

Optional per-run skill selection. Omit it to apply all active skills. Pass explicit workspace or user skill name lists to constrain the run.

Example: tax prep only

{
  "input": {
    "clientId": "019f0fb6-37b1-7800-b7bc-0d11288504b1",
    "returnType": "F1040",
    "runDataEntry": false
  }
}

{
  "data": {
    "triggerTaxPrep": {
      "taskId": "019f0fc4-9298-7bdd-91f6-7f6e77cdbd9b"
    }
  }
}

Example: tax prep with data entry

{
  "input": {
    "clientId": "019f0fb6-37b1-7800-b7bc-0d11288504b1",
    "returnType": "F1040",
    "software": "proconnect",
    "softwareConnectionId": "019f0fb8-f8c9-7f6a-b504-7d8e989c3c34",
    "softwareClientId": "CLIENT-123",
    "runDataEntry": true
  }
}

Only set runDataEntry: true when the user has selected the target tax software connection and client. Data entry can write data back to the tax software.

Trigger data entry

triggerDataEntry starts data entry from an existing tax prep task. Use this when tax prep has already completed or prepared fields and the user now wants to send those fields to tax software.

mutation TriggerDataEntry($input: TriggerDataEntryInput!) {
  triggerDataEntry(input: $input) {
    taskId
  }
}

input TriggerDataEntryInput {
  taskId: ID!
  clientId: ID!
  software: String
  softwareConnectionId: ID!
  softwareClientId: String!
}

Arguments

input.taskId

ID!

required

The source tax prep task ID. In the web app, this is the latest TAX_PREP task for the client.

input.clientId

ID!

required

The client whose prepared fields should be entered.

input.software

String

Optional tax software provider key.

input.softwareConnectionId

ID!

required

The Filed connection ID for the target tax software integration.

input.softwareClientId

String!

required

The client identifier inside the tax software.

Example request

{
  "input": {
    "taskId": "019f0fc4-9298-7bdd-91f6-7f6e77cdbd9b",
    "clientId": "019f0fb6-37b1-7800-b7bc-0d11288504b1",
    "software": "proconnect",
    "softwareConnectionId": "019f0fb8-f8c9-7f6a-b504-7d8e989c3c34",
    "softwareClientId": "CLIENT-123"
  }
}

Example response

{
  "data": {
    "triggerDataEntry": {
      "taskId": "019f0fd1-15ef-74e8-adff-42c89edbf0fd"
    }
  }
}

Data entry writes to the selected tax software connection. Confirm the connection and softwareClientId with the user before calling this mutation.

Find the latest tax prep task

If an agent needs to trigger data entry and does not already have a tax prep task ID, read the latest client TAX_PREP task first.

query LatestTaxPrepTask($clientId: ID!) {
  me {
    ... on WorkspaceUser {
      workspace {
        clients(filters: { ids: [$clientId] }) {
          id
          tasks(type: TAX_PREP, limit: 1) {
            id
            status
            errorMessage
          }
        }
      }
    }
  }
}

clientId

ID!

required

The client whose latest tax prep task should be used as the data entry source.

tasks.id

ID!

Use this value as TriggerDataEntryInput.taskId.

tasks.status

TaskStatus!

The task state: RUNNING, COMPLETED, or FAILED. Prefer a completed tax prep task before triggering data entry.

Poll trigger results

Poll the task returned by either mutation through the client’s task list. Use TAX_PREP for tax prep runs. Data entry is represented as stages within the tax prep pipeline and by the task returned from triggerDataEntry.

query PollClientTaxPrepTasks($clientId: ID!) {
  me {
    ... on WorkspaceUser {
      workspace {
        clients(filters: { ids: [$clientId] }) {
          id
          tasks(type: TAX_PREP, limit: 5) {
            id
            status
            startedAt
            completedAt
            errorMessage
            subTasks {
              id
              type
              status
              errorMessage
              errorCode
            }
          }
        }
      }
    }
  }
}

enum TaskStatus {
  RUNNING
  COMPLETED
  FAILED
}

enum DataEntryErrorCode {
  INVALID_CREDENTIALS
  CAPTCHA_FAILED
  CLIENT_NOT_FOUND
  CLIENT_ALREADY_OPEN
  NOT_REGISTERED
  TIMEOUT
  UNKNOWN
}

tasks.status

TaskStatus!

Use RUNNING to keep polling, COMPLETED to read results, and FAILED to show or report errorMessage.

subTasks.errorCode

DataEntryErrorCode

Machine-readable data entry failure code when a data entry stage fails. Values include INVALID_CREDENTIALS, CLIENT_NOT_FOUND, TIMEOUT, and UNKNOWN.

MCP usage pattern

For Filed MCP tools and AI agents:

Query the client and confirm returnType.
Query workspace connections and select the tax software connection.
For tax prep only, call triggerTaxPrep with runDataEntry: false.
For tax prep plus data entry, call triggerTaxPrep with runDataEntry: true and include the software connection fields.
For data entry after tax prep, query the latest TAX_PREP task and call triggerDataEntry.
Poll the returned taskId and surface errorMessage or subTasks.errorCode if the task fails.

When triggering data entry, never guess the tax software client ID. Ask the user or read it from the selected integration connection’s client list before calling the mutation.

​Shared return type

​Trigger tax prep

​Arguments

​Example: tax prep only

​Example: tax prep with data entry

​Trigger data entry

​Arguments

​Example request

​Example response

​Find the latest tax prep task

​Poll trigger results

​MCP usage pattern

Shared return type

Trigger tax prep

Arguments

Example: tax prep only

Example: tax prep with data entry

Trigger data entry

Arguments

Example request

Example response

Find the latest tax prep task

Poll trigger results

MCP usage pattern