API release notes: version 1 changes

Release date: November 12, 2026. These notes cover what changed in the existing version 1 APIs. Version 2 is a separate platform and has its own API release notes: version 2. You do not have to move to version 2 because of these changes.

Overview

Version 1 is still the API your current integrations call. This release changes three areas of that API: client balances can be included when you read clients, country and county names are checked when you save clients, contacts, and staff, and closing a job now requires a closed status.

You can also return reports as JSON, as well as PDF or CSV. Addresses for clients, contacts, staff, and the rest of version 1 are otherwise unchanged.

Key highlights

  • Ask for work-in-progress and accounts-receivable balances on a client read. If you omit the option, the response stays as it was.

  • The API matches a country or county name sent for a client, contact, or member of staff before it saves the record. If a name does not exist, the API reports it on that row instead of storing it.

  • Closing a job now requires the closed status. The previous close address, which could close a job without a status, is no longer available.

  • You can request a report as JSON.

What's new

Client balances

What's new. Client reads accept an optional includeBalances parameter. Set it to true and the response includes the client's work-in-progress balance and accounts-receivable balance. If you leave it out, or set it to false, the API does not fill in those balances.

Why it matters. A credit-control or billing integration can show what a client owes without a second call. Existing callers that do not send the parameter are unaffected.

What you can do. Retrieve one client, or a filtered client list, with balances included. The same option is available on the version 1 client query feed.

GET /Clients/{clientId}?includeBalances=true

Country and county on clients, contacts, and staff

What's new. When you create or update a client, contact, or member of staff and send a country or county by name, version 1 matches that name to the firm's country and county records before it saves.

Why it matters. Integrations that still send a country name, rather than a code, get a clear result when the name is unknown. The API no longer stores a value the practice cannot use.

What you can do. Keep sending the names you already send.

  • If the API cannot match a name on a create or a partial update, it skips that row and the response gives the reason.

  • If a country and county do not belong together on a full replace, the API rejects the replace.

  • If the API cannot match a name on a full replace, the existing save rules apply.

Reports as JSON

What's new. Report generation accepts JSON as well as PDF and CSV.

Why it matters. You can use a report as data, not only as a file to download.

What you can do. Request the same report you already run and ask for JSON. If the report has no rows, the response has no content, as it does for an empty PDF or CSV.

Changes for existing integrations

Closing a job has moved. The address POST /Jobs/{jobId}/Close is no longer available. Close a job with:

POST /Jobs/{jobId}/Close/{statusId}

The status must be one that is marked closed. If you omit the status, the API does not close the job. It returns an error that asks for the status. Callers that posted to the old address need to add the status to the path.

The older job close operation takes the job identifier in the request instead of in the address. It has the same rule. If you leave out the status, the API now returns an error. It no longer closes the job on its own.

Client, contact, and staff addresses are unchanged. The includeBalances option is optional and defaults to off, so current client reads keep their previous shape. Country and county checking runs on create, partial update, and full replace. If a create or partial update sends an unknown country or county name, the API skips that row and returns the reason with the row. One unknown name does not fail the whole batch.

No other version 1 resource changed its address in this release. Permission to call version 1 is unchanged. You do not need version 2 to keep a version 1 integration working.

Getting started

These changes are for integrations that already call version 1. Use the same access you use today.

  • To get balances, add includeBalances=true to the client read you already make.

  • To close a job, take the closed status your practice uses and add it to the new close address.

  • To get a report as data, set the output format to JSON.

Field lists and examples for these operations are in the API reference. For the link, go to IRIS Firm Management APIs.

Known limitations

  • The API fills in balances after it reads the client list. On the client query feed, you cannot filter or sort by the balance fields.

  • Country and county matching uses the names held for the firm. A name that is valid in another country list does not match.

  • JSON reports return the report data only. They do not add a file download of the PDF or CSV.