This article documents the workflows integrators most often build against the FileTrac SOAP API. Each pattern shows the sequence of methods, the data that flows between them, and the gotchas to plan for.

Pattern 1 — Create a New Claim End-to-End

Use this pattern when an external system (a carrier policy admin system, a FNOL intake form, a partner integration) needs to file a new claim into FileTrac and then enrich it with notes, contacts, and an initial reserve.

Sequence

Resolve the client company. Call GetClientCompanies, filter to the carrier, and capture ClientCompanyID.
(Optional) Resolve the client contact. Call GetClientContacts with the ClientCompanyID to find the right Claim Rep. Capture ClientContactID. When omitted, FileTrac assigns the default UNASSIGNED Rep.
(Optional) Resolve the adjuster. Call GetUsers with UserRole=Adjuster and the relevant filter (last-name prefix, client company). Capture AdjusterID.
Create the claim. Call AddClaim supplying at minimum: Login, Password, CompanyKey, ClientCompanyID, ClientClaimNum. Add the Insured fields, Loss Location fields, Loss Info fields, and as much Coverage data as is known. Capture the returned claimID.
(Optional) Add additional contacts. Call AddClaimContact per non-insured / non-claimant / non-agent contact, or include them in the <Contacts> wrapper of step 4.
(Optional) Add a kickoff note. Call AddClaimNote with Note = the FNOL intake summary.
(Optional) Establish initial reserves. Call AddReserve once per reserve type (e.g., Indemnity, Legal Expenses). Supply the contact for contact-level reserves, or omit for claim-level reserves.

Gotchas

ClientCompanyName must match exactly. Use ClientCompanyID whenever possible to avoid silent name-mismatch failures.
Adjuster mapping by name requires exact username match. When you can't guarantee that, prefer AdjusterID from GetUsers. AdjusterEmail is the most forgiving non-ID identifier.
Date fields prefer mm/dd/yyyy format on the AddClaim envelope. Invalid dates are silently nulled.
The Primary Insured / Claimant / Agent contacts are created automatically by the Insured* / Claimant* / Agent* field sets — do not duplicate them in the <Contacts> wrapper.

Pattern 2 — Poll for Changes (Incremental Ingestion)

Use this pattern to keep a downstream system (a data warehouse, a BI tool, a notification service) in sync with FileTrac claim updates.

Sequence

Persist the last-poll timestamp. On the first run, choose a sensible backfill window (e.g., the last 90 days).
Call GetUpdatedClaims with DateFrom = the persisted timestamp. Optionally set ExcludeClaimsOfBDXCompanies=true if downstream systems do not handle Bordereaux carriers.
For each returned ClaimUpdateExtract, call GetClaimDetail with the FileTracClaimID. This returns the full claim with all populated nested lists (notes without emails, reports without binaries, reserves with full history).
For each note that requires email content, call GetClaimNotes with IncludeNoteEmails=true for that claim.
For each report that requires binary content, call GetClaimReports per FileTracReportID. Pull large reports (30 MB+) one at a time to avoid timeouts.
For each invoice that requires line items, call GetInvoiceDetail per InvoiceID.
Persist the latest DateOfUpdate returned as the new last-poll timestamp.

Gotchas

GetUpdatedClaims includes activity, not just claim-record edits. Notes, reserve changes, and report uploads also surface a claim in the list. This is broader than a CRM-style "modified since" query.
Clock skew matters. The server applies DateFrom against its own clock. If your client clock is ahead, you'll silently miss updates. Persist the DateOfUpdate from each result, not your own polling timestamp.
GetClaimSummaries also accepts DateUpdatedSince. For pipelines that need top-level claim data and not the lookup-keys-only response, GetClaimSummaries with DateUpdatedSince is the heavier alternative to GetUpdatedClaims.

Pattern 3 — Working with Payments

The API supports three distinct payment kinds. Choose the right method:

Scenario	Method	Notes
Insured paid their deductible	`AddDeductiblePayment`	Pulls down the deductible balance. Requires a payee contact.
Adjusting company received payment on an invoice	`AddInvoicePayment`	Splits automatically on overflow into a primary + excess payment.
Carrier paid against an established reserve	`AddReservePayment`	Requires both a reserve and a payee contact.
Subrogation, salvage, or reinsurance proceeds received	`AddReserveRecovery`	Recovery is tracked but does not reduce the reserve's incurred amount.

Void via inverse amount

To void a payment or recovery, send the same method call with the same payee, reserve (if applicable), and a negative amount. There is no separate void endpoint. Invoice payments do not have a documented void pattern — they remain on record once applied.

Always validate balances first

For deductible payments, query the claim via GetClaimDetail and compute Deductible minus sum-of-prior-deductible-payments before submitting.
For reserve payments, compute Incurred minus sum-of-prior-payments-against-that-reserve.
For invoice payments, query GetInvoiceDetail and compute Total minus sum-of-prior-invoice-payments. Catch the overflow scenario in advance.

Pattern 4 — Working with Reports

Uploading

Read the file from disk in your integration code; base64-encode the contents.
Call UploadReport with the encoded ReportFile, the ClaimID, and metadata (title, file name, description, timestamp).
Persist the returned ReportID for future reference. There is no idempotency guard — re-submitting the same payload uploads a duplicate report.

Retrieving

The API exposes two reading patterns:

Lightweight metadata. GetClaimDetail returns a Reports list with ID, title, file name, date, and confidential flag — no binary content.
Full retrieval. GetClaimReports returns the same metadata plus the base64-encoded ReportFile.

For claims with many large reports (30 MB+ each, totaling 100 MB+), retrieve reports individually by FileTracReportID rather than pulling the full list. The same caution applies to media items via GetReportMedia.

File-name conventions

Invalid characters are stripped from file names server-side.
Duplicate names get an underscore-suffix (_2, _3, …) where higher numbers represent more recent uploads. Set ExcludeDuplicateNameSuffix=1 on GetClaimReports to retrieve the original names instead.

Pattern 5 — ID versus Name Lookups

Many methods accept either an ID or a name. The general rule:

Use IDs when you have them. IDs are stable, exact, and immune to FileTrac UI relabels.
Use names only as a substitute when the ID is not available. Names require exact matches — case, whitespace, and punctuation all matter.
GetClient* and GetUsers are your lookup methods. Run them once per integration session and cache the results.

Per-method guidance

Field	Prefer	Fallback
Client company	`ClientCompanyID` from `GetClientCompanies`	`ClientCompanyName` (exact match)
Client contact	`ClientContactID` from `GetClientContacts`	`ClientContactName` (exact match)
Adjuster on a claim	`AdjusterID` from `GetUsers`	`AdjusterEmail`, then exact-username match (`AdjusterFirstName` + `AdjusterLastName`)
Contact type	`ContactTypeID` from `GetContactTypes`	`ContactType` name (enum value)
Reserve type	`ReserveTypeID` (from `GetClaimDetail` on a representative claim)	`ReserveType` name
Recovery type	`RecoveryTypeID` from `GetRecoveryTypes`	`RecoveryType` name
Reserve on a claim	`ReserveID` from the reserve's previous response	`ReserveName` (only when type is unique on the claim)
Payee contact on a claim	`PayeeID` (the contact's `ID` from `GetClaimDetail`)	New-contact creation via `PayeeFirstName` + `PayeeLastName` + `PayeeContactType`

Pattern 6 — Idempotency and Retry

The API does not provide idempotency keys. Re-submitting the same payload creates duplicates for most insert methods. To make integrations safe to retry:

Persist the returned ID immediately after each successful insert. If a downstream step fails, your retry logic should know which step succeeded.
For AddClaim, ClientCompanyID + ClientClaimNum acts as a natural deduplication key. A second call with the same combination updates rather than inserts.
For AddReserve, FileTracClaimID + ReserveTypeID acts the same way. A second call updates the same reserve and records the change in the Changes sublist.
For other insert methods, no natural key exists. AddClaimNote, AddClaimContact, UploadReport, and the payment methods all duplicate on retry. Wrap retries in a transactional layer that confirms the previous attempt's success before re-submitting.

Pattern 7 — Caching Lookup Lists

Lookup data changes infrequently. Cache the following per integration session (or longer with manual invalidation):

GetClientCompanies — typically pulled at session start.
GetContactTypes — pull once, reuse for the lifetime of the integration version.
GetRecoveryTypes — same.
GetUsers — refresh daily or on demand; user lists change with hiring/turnover.
GetClientContracts — refresh weekly or on demand; contracts change with renewal cycles.

Caching these avoids an extra round-trip before every insert that requires a lookup value.

Common Integration Patterns

Pattern 1 — Create a New Claim End-to-End

Sequence

Gotchas

Pattern 2 — Poll for Changes (Incremental Ingestion)

Sequence

Gotchas

Pattern 3 — Working with Payments

Void via inverse amount

Always validate balances first

Pattern 4 — Working with Reports

Uploading

Retrieving

File-name conventions

Pattern 5 — ID versus Name Lookups

Per-method guidance

Pattern 6 — Idempotency and Retry

Pattern 7 — Caching Lookup Lists

Related Articles