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

# Find or create a client by your external ID (partners)

> For partners: look up a Filed client from the ID your own system uses for it, and create it linked to that ID when it doesn't exist

> [!NOTE]
>
> Please make sure you have talked to Filed's team to register you as a provider
> in the system before you start.

This API is for partners: products that integrate with Filed on a firm's
behalf, such as a practice-management or document platform. Your system knows a
client by its own ID, for example your client number. Filed stores that ID on
a **connection link**: the link between a Filed client and a client in a connected system. To find the
Filed client, find the connection, then filter clients by that connection and
your ID. If nothing matches, create the client with the same connection and ID
so the next lookup finds it.

Everything here uses a **`workspaceToken`** (see
[Authentication](https://developers.apps.filed.com/guides/authentication.md)) against:

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

```mermaid theme={null}
---
config:
  theme: base
  look: classic
  layout: elk
  fontFamily: "Geist, ui-sans-serif, system-ui, sans-serif"
  flowchart:
    curve: linear
  themeVariables:
    fontSize: 14px
    primaryColor: "#ffffff"
    primaryBorderColor: "#d4cabc"
    primaryTextColor: "#1e150e"
    lineColor: "#a89a88"
    edgeLabelBackground: "#ffffff"
---
flowchart LR
  A["1. connections"] -->|"connection id"| B["2. clients(filters.connectionLink)"]
  B -->|"found"| C["Use the client"]
  B -->|"empty list"| D["3. createClient<br/>(sourceConnectionId, sourceExternalId)"]
  D -->|"client id"| C
```

## 1. List connections and pick the connection ID

```graphql theme={null}
query ListConnections {
  me {
    ... on WorkspaceUser {
      workspace {
        connections {
          id
          providerKey
          name
          status
        }
      }
    }
  }
}
```

```json theme={null}
{
  "data": {
    "me": {
      "workspace": {
        "connections": [
          {
            "id": "019a4c2e-5b1f-7d20-9c3e-4a8b2d6f1e07",
            "providerKey": "karbon",
            "name": "Karbon",
            "status": "active"
          }
        ]
      }
    }
  }
}
```

Pick the connection whose clients carry your IDs, such as the connection for
your own system. Pass `providerKey` to narrow the list. The connection ID
doesn't change, so you can store it once.

> [!WARNING]
>
> A link's external ID is the ID the connected system uses for the client. On a
> tax-software connection that is the tax software's own client ID (see [Create
> clients from tax software](https://developers.apps.filed.com/guides/create-clients-from-tax-software.md)), not
> yours. Don't write your own IDs onto a tax-software connection: those links
> never match the software's clients, and Filed then imports the same taxpayer
> as a second client.

## 2. Find the client by connection ID and external ID

```graphql theme={null}
query FindClientByExternalId($connectionId: ID!, $externalId: String!) {
  me {
    ... on WorkspaceUser {
      workspace {
        clients(
          filters: {
            connectionLink: { connectionId: $connectionId, externalId: $externalId }
          }
        ) {
          id
          name
          status
          returnType
          taxYear
        }
      }
    }
  }
}
```

```json theme={null}
{
  "connectionId": "019a4c2e-5b1f-7d20-9c3e-4a8b2d6f1e07",
  "externalId": "10432"
}
```

```bash cURL theme={null}
curl -X POST https://router.apps.filed.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_WORKSPACE_TOKEN" \
  -d '{
    "query": "query FindClientByExternalId($connectionId: ID!, $externalId: String!) { me { ... on WorkspaceUser { workspace { clients(filters: { connectionLink: { connectionId: $connectionId, externalId: $externalId } }) { id name status returnType taxYear } } } } }",
    "variables": {
      "connectionId": "019a4c2e-5b1f-7d20-9c3e-4a8b2d6f1e07",
      "externalId": "10432"
    }
  }'
```

```json theme={null}
{
  "data": {
    "me": {
      "workspace": {
        "clients": [
          {
            "id": "018f9c2a-3d5f-7a10-b2c4-9e8d7f6a5b4c",
            "name": "Jane Taxpayer",
            "status": "active",
            "returnType": "F1040",
            "taxYear": 2025
          }
        ]
      }
    }
  }
}
```

`externalId` must match exactly; surrounding spaces are ignored. The result is
a list: the same external ID can be linked to more than one Filed client, for
example one per tax year. Both `taxYear` and `status` take lists, so narrow it
with, for example, `filters: { connectionLink: { connectionId: $connectionId,
externalId: $externalId }, taxYear: [2025], status: [active] }`.
An empty list means no client is linked to that ID on that connection: go to
step 3.

## 3. Create the client when none is found

Call [`createClient`](https://developers.apps.filed.com/apis/clients#create-a-client) with the same connection
and ID as `sourceConnectionId` and `sourceExternalId`. Filed links the new
client to that connection under your ID, so step 2 finds it from then on.

```graphql theme={null}
mutation CreateClient($input: CreateClientInput!) {
  createClient(input: $input) {
    client {
      id
      name
      returnType
      taxYear
    }
    taskId
  }
}
```

```json theme={null}
{
  "input": {
    "name": "Jane Taxpayer",
    "returnType": "F1040",
    "taxYear": 2025,
    "sourceConnectionId": "019a4c2e-5b1f-7d20-9c3e-4a8b2d6f1e07",
    "sourceExternalId": "10432",
    "importRequestId": "10432:2025"
  }
}
```

```bash cURL theme={null}
curl -X POST https://router.apps.filed.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_WORKSPACE_TOKEN" \
  -d '{
    "query": "mutation CreateClient($input: CreateClientInput!) { createClient(input: $input) { client { id name returnType taxYear } taskId } }",
    "variables": {
      "input": {
        "name": "Jane Taxpayer",
        "returnType": "F1040",
        "taxYear": 2025,
        "sourceConnectionId": "019a4c2e-5b1f-7d20-9c3e-4a8b2d6f1e07",
        "sourceExternalId": "10432",
        "importRequestId": "10432:2025"
      }
    }
  }'
```

```json theme={null}
{
  "data": {
    "createClient": {
      "client": {
        "id": "018f9c2a-3d5f-7a10-b2c4-9e8d7f6a5b4c",
        "name": "Jane Taxpayer",
        "returnType": "F1040",
        "taxYear": 2025
      },
      "taskId": null
    }
  }
}
```

Send the same `importRequestId` for the same client and tax year, so a retry
returns the existing client instead of creating a second one. Connected [with
OAuth](https://developers.apps.filed.com/guides/connect-with-oauth.md)? Leave out `sourceConnectionId` and
`importRequestId`: Filed uses your token's connection, and matches repeat calls
on `sourceExternalId`, `taxYear` and `returnType`. Add `uploadIds` to attach
documents in the same call.

Use the client's `id` with the other client APIs, for example
[`addClientDocuments`](https://developers.apps.filed.com/guides/recipes/onboard-a-client#3-add-documents-to-an-existing-client).


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