Please make sure you have talked to Filed’s team to register you as a provider
in the system before you start.
workspaceToken (see
Authentication) against:
1. List connections and pick the connection ID
providerKey to narrow the list. The connection ID
doesn’t change, so you can store it once.
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
CallcreateClient 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.
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.