> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apps.filed.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Task Triggers

> Start tax prep and data entry tasks from the Filed GraphQL API

Task trigger mutations start background work and return a `taskId`. Use the
[Tasks API](/apis/tasks) to poll that task until it is no longer `RUNNING`.

Task triggers are reached through the [`me`](/apis/me) flow as a
`WorkspaceUser`, so authenticate with a **`workspaceToken`**. All requests go to:

```http theme={null}
https://router.apps.filed.com/graphql
```

<Note>
  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.
</Note>

## Shared return type

Both `triggerTaxPrep` and `triggerDataEntry` return `TriggerTaskResult`.

```graphql theme={null}
type TriggerTaskResult {
  taskId: ID!
}
```

<ResponseField name="taskId" type="ID!">
  The background task ID. Poll it through [Tasks](/apis/tasks) or through the
  client's task list until the task reaches `COMPLETED` or `FAILED`.
</ResponseField>

## 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.

```graphql theme={null}
mutation TriggerTaxPrep($input: TriggerTaxPrepInput!) {
  triggerTaxPrep(input: $input) {
    taskId
  }
}
```

```graphql theme={null}
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

<ParamField path="input.clientId" type="ID!" required>
  The client to run tax prep for.
</ParamField>

<ParamField path="input.returnType" type="ReturnType!" required>
  The return form for the client: `F1040`, `F1041`, `F1065`, `F1120`, `F1120S`,
  or `F990`.
</ParamField>

<ParamField path="input.taskId" type="ID">
  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.
</ParamField>

<ParamField path="input.software" type="String">
  The tax software provider key. Use this with `softwareConnectionId` and
  `softwareClientId` when the run should prepare for or continue into data entry.
</ParamField>

<ParamField path="input.softwareConnectionId" type="ID">
  The Filed connection ID for the tax software integration.
</ParamField>

<ParamField path="input.softwareClientId" type="String">
  The client identifier inside the tax software.
</ParamField>

<ParamField path="input.softwareClientVersion" type="String">
  Optional software-specific client version string.
</ParamField>

<ParamField path="input.runDataEntry" type="Boolean">
  When `true`, tax prep continues into data entry during the same run. Provide
  `software`, `softwareConnectionId`, and `softwareClientId` when setting this.
</ParamField>

<ParamField path="input.forceReconcile" type="Boolean">
  When `true`, reconciliation runs again even if an earlier reconciliation result
  exists.
</ParamField>

<ParamField path="input.force" type="Boolean">
  When `true`, start a run even when an existing tax prep task is already running
  for the client.
</ParamField>

<ParamField path="input.skills" type="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.
</ParamField>

### Example: tax prep only

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

```json theme={null}
{
  "data": {
    "triggerTaxPrep": {
      "taskId": "019f0fc4-9298-7bdd-91f6-7f6e77cdbd9b"
    }
  }
}
```

### Example: tax prep with data entry

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

<Warning>
  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.
</Warning>

## 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.

```graphql theme={null}
mutation TriggerDataEntry($input: TriggerDataEntryInput!) {
  triggerDataEntry(input: $input) {
    taskId
  }
}
```

```graphql theme={null}
input TriggerDataEntryInput {
  taskId: ID!
  clientId: ID!
  software: String
  softwareConnectionId: ID!
  softwareClientId: String!
}
```

### Arguments

<ParamField path="input.taskId" type="ID!" required>
  The source tax prep task ID. In the web app, this is the latest `TAX_PREP` task
  for the client.
</ParamField>

<ParamField path="input.clientId" type="ID!" required>
  The client whose prepared fields should be entered.
</ParamField>

<ParamField path="input.software" type="String">
  Optional tax software provider key.
</ParamField>

<ParamField path="input.softwareConnectionId" type="ID!" required>
  The Filed connection ID for the target tax software integration.
</ParamField>

<ParamField path="input.softwareClientId" type="String!" required>
  The client identifier inside the tax software.
</ParamField>

### Example request

```json theme={null}
{
  "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

```json theme={null}
{
  "data": {
    "triggerDataEntry": {
      "taskId": "019f0fd1-15ef-74e8-adff-42c89edbf0fd"
    }
  }
}
```

<Warning>
  Data entry writes to the selected tax software connection. Confirm the
  connection and `softwareClientId` with the user before calling this mutation.
</Warning>

## 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.

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

<ParamField path="clientId" type="ID!" required>
  The client whose latest tax prep task should be used as the data entry source.
</ParamField>

<ResponseField name="tasks.id" type="ID!">
  Use this value as `TriggerDataEntryInput.taskId`.
</ResponseField>

<ResponseField name="tasks.status" type="TaskStatus!">
  The task state: `RUNNING`, `COMPLETED`, or `FAILED`. Prefer a completed tax prep
  task before triggering data entry.
</ResponseField>

## 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`.

```graphql theme={null}
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
            }
          }
        }
      }
    }
  }
}
```

```graphql theme={null}
enum TaskStatus {
  RUNNING
  COMPLETED
  FAILED
}

enum DataEntryErrorCode {
  INVALID_CREDENTIALS
  CAPTCHA_FAILED
  CLIENT_NOT_FOUND
  CLIENT_ALREADY_OPEN
  NOT_REGISTERED
  TIMEOUT
  UNKNOWN
}
```

<ResponseField name="tasks.status" type="TaskStatus!">
  Use `RUNNING` to keep polling, `COMPLETED` to read results, and `FAILED` to show
  or report `errorMessage`.
</ResponseField>

<ResponseField name="subTasks.errorCode" type="DataEntryErrorCode">
  Machine-readable data entry failure code when a data entry stage fails. Values
  include `INVALID_CREDENTIALS`, `CLIENT_NOT_FOUND`, `TIMEOUT`, and `UNKNOWN`.
</ResponseField>

## MCP usage pattern

For Filed MCP tools and AI agents:

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

<Tip>
  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.
</Tip>