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

# Start data entry with a client ID

> Start data entry in one call when your product already knows the client's ID in the tax software

If your product stores each client's ID in the firm's tax software, you can
start data entry without showing anything to the user. Send that ID with the
Filed client and Filed works out which tax software connection reaches it.
Without an ID, Filed looks the client up by name instead.

Call it as soon as you have pushed the documents. Filed waits for them to be
processed and then prepares the entries on its own.

```mermaid theme={null}
flowchart LR
  A["Your server"] -->|"startDataEntry<br/>(clientId, softwareClientId?)"| B{"Client<br/>found?"}
  B -->|"yes"| C["STARTED<br/>webhook task.running"]
  C -->|"documents processed,<br/>entries prepared"| D["webhook task.paused<br/>(ready_for_review)"]
  B -->|"no"| E["NEEDS_TAX_SOFTWARE_CLIENT<br/>webhook task.paused<br/>(needs_tax_software_client)"]
  E -->|"user picks the client<br/>in Filed"| C
```

If you would rather have the user confirm the client, show
[Filed's dialog](/guides/start-data-entry-dialog) instead.

## Before you start

The firm needs two things in place before its users connect your product:

* An active Filed workspace.
* One or more active tax software connections in that workspace.

## Start data entry

```graphql theme={null}
mutation StartDataEntry($input: StartDataEntryInput!) {
  startDataEntry(input: $input) {
    taskId
    status
  }
}
```

<ParamField body="input.clientId" type="ID!" required>
  The Filed client, as returned by `createClient`.
</ParamField>

<ParamField body="input.softwareClientId" type="String">
  The client's ID in the tax software, for example `MHARPER` in UltraTax. Leave
  it out when you do not have it and Filed looks the client up by name; see
  [Without a client ID](#without-a-client-id).
</ParamField>

<ParamField body="input.softwareConnectionId" type="ID">
  The Filed tax software connection to use. Leave it out to let Filed choose.
</ParamField>

<ParamField body="input.softwareReturnId" type="String">
  The exact return ID. Only ProConnect needs it.
</ParamField>

<ResponseField name="taskId" type="ID!">
  The client's data entry task. It is the `taskId` on the webhooks that follow.
</ResponseField>

<ResponseField name="status" type="StartDataEntryStatus!">
  `STARTED`, `ALREADY_STARTED` or `NEEDS_TAX_SOFTWARE_CLIENT`; see below.
</ResponseField>

## What the status means

| Status | What happened | What to do |
| - | - | - |
| `STARTED` | The client is linked and data entry has started. | Wait for `task.paused` with `reason: ready_for_review`. |
| `ALREADY_STARTED` | Data entry was started for this client before. Nothing new was started. | Send the user to Filed to prepare again if new documents arrived. |
| `NEEDS_TAX_SOFTWARE_CLIENT` | No connection reaches that client ID, or no ID was sent and the name did not single out one client. | Show the user the `actionUrl` from `task.paused`. |

## How Filed chooses the connection

Filed looks at the tax software connections available to the Filed user who
connected your product.

* With one connection, Filed uses it.
* With several, Filed uses one whose client list contains the ID. If more than
  one does, it prefers the one whose desktop was online most recently, then
  that user's own connection, then the newest.
* With none, or when no client list contains the ID, the result is
  `NEEDS_TAX_SOFTWARE_CLIENT`.

Filed does not learn which of your users made the request, so a connection
that belongs to a different Filed user is not considered.

## Without a client ID

Filed compares the name you sent in `createClient` with the names in the
client lists of those same connections. If someone has since renamed the
client in Filed, the new name is used.

Case, accents, punctuation and word order do not matter; every word has to be
there.

| Name you sent | Name in the tax software | Result |
| - | - | - |
| Dante Hicks | HICKS, DANTE | Starts |
| Dante and Veronica Hicks | HICKS, DANTE & VERONICA | Starts |
| Acme Holdings, LLC | ACME HOLDINGS LLC | Starts |
| José Álvarez | ALVAREZ, JOSE | Starts |
| Dante Hicks | HICKS, DANTE R | Needs a person: middle initial on one side |
| Dante Hicks | HICKS, DAN | Needs a person: short form of the name |
| Dante Hicks | HICKS, DANTE & VERONICA | Needs a person: spouse on one side only |
| Acme Holdings LLC | ACME HOLDINGS | Needs a person: `LLC` on one side only |
| Mary O'Brien | OBRIEN, MARY | Needs a person: `O'Brien` and `OBrien` differ |
| Jane Doe | Two clients named Jane Doe | Needs a person: the name fits both |

* If exactly one tax software client has that name, Filed links it and starts.
* If none does, or more than one does, the result is
  `NEEDS_TAX_SOFTWARE_CLIENT` and a person picks the client in Filed.

Send the ID whenever you have it: it is the only way to be sure which client
is meant.

## After it starts

The events are the same as for the dialog; see
[After the user starts](/guides/start-data-entry-dialog#after-the-user-starts).
Data entry stops when the entries are ready: a person reviews them in Filed
and sends them to the tax software.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.