Skip to main content
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) against:

1. List connections and pick the connection ID

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.
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), 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

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