FreeAgent API entity map

This is an unofficial reconstruction of how FreeAgent API resources link to each other. FreeAgent does not publish an entity-relationship diagram; the graphs here are inferred from official API documentation - attribute tables where kind is URI, nested child resources, and list filters that take a resource URI (?contact=, ?project=, and so on).

Use this map to understand object relationships when integrating with FreeAgent, and to choose a sensible order when adding resources to the SDK. For what the SDK implements today, see API coverage.

When implementing SDK models, map documented URI links using the linked resources pattern - see ADR-0011.

How to read the diagrams

Line style Meaning
Solid arrow (-->) Documented required URI on create, or a list endpoint that requires a parent URI (for example bank transactions require bank_account)
Dashed arrow (-.->) Optional URI, nested line-item URI, or a link that appears after the record exists (for example rebilled_on_invoice, billed_on_invoice)

Edge labels use the wire field name from the API (contact, paid_invoice, project, and so on).

Caveats:

  • Optional URIs may be absent on any given record.
  • Some links apply only to certain company types (for example property on UkUnincorporatedLandlord companies).
  • Nested line items (invoice items, bill items) are documented on the parent resource page unless they have their own docs URL (estimate items do).
  • Currencies are ISO codes on resources, not URI references to a /currencies resource.
  • The Accountancy Practice API is a separate product surface and is not mapped here.

Cluster overview

Resources are grouped into clusters so no single diagram becomes unreadable. Each cluster has its own page with a focused diagram and a resource catalogue.

flowchart LR
  hub[Hub_overview]
  foundations[Foundations]
  projectsTime[Projects_and_time]
  sales[Sales]
  purchases[Purchases]
  banking[Banking]
  assetsJournals[Assets_and_journals]
  reports[Reports]
  hub --> foundations
  hub --> projectsTime
  hub --> sales
  hub --> purchases
  hub --> banking
  hub --> assetsJournals
  hub --> reports
Cluster Page What it covers
Foundations Foundations Company, contacts, users, categories
Projects and time Projects and time Projects, tasks, timeslips, notes
Sales Sales Invoices, estimates, recurring invoices, credit notes, stock items
Purchases Purchases Bills, expenses, hire purchases, attachments
Banking Banking Bank accounts, transactions, explanations, feeds
Assets and journals Assets and journals Capital assets, journal sets, properties, payroll
Reports Reports P&L, balance sheet, trial balance, tax returns - weak URI graphs

Using this map to sequence SDK work

Layers describe dependency pressure, not a mandatory backlog. A resource in a later layer can still be implemented first if its only upstream links are optional URIs you are willing to pass as opaque strings until typed services exist.

Layer Resources Rationale
0 - Done Company, Contacts, Categories, Users, Email addresses, OAuth helpers Company context, contacts, chart-of-accounts categories, and users are referenced across many resources
2 - Done Projects, Tasks, Timeslips, Notes Client work structure: projects require contact; tasks require project; timeslips require task, project, and user; notes hang off contacts or projects
3 - Sales documents Invoices, Estimates, Recurring invoices, Credit notes Invoices require only contact on create; project, bank_account, and item category URIs are optional
4 - Purchases Bills, Expenses Bills require contact; expenses require user and category
5 - Banking Bank accounts, Bank transactions, Bank transaction explanations Explanations link back to invoices, bills, contacts, projects, users, and stock
6 - Assets and books Capital assets, Journal sets, Properties, Payroll Heavier accounting surface; properties are landlord-only
7 - Reports P&L, Balance sheet, Trial balance, VAT returns, and similar Mostly date-bounded reads with few URI dependencies

Is Invoices blocked?

No. The only required URI when creating an invoice is contact, which the SDK already implements. Optional URIs use typed references where the SDK provides them (ProjectReference, BankAccountReference, CategoryReference on line items). property, recurring_invoice, and invoice-item stock_item may remain opaque URI strings until those resources are implemented.

The Invoices implementation introduces Sales cluster patterns reused by sibling resources: status transition methods, nested line-item updates on the parent payload, PDF and email actions, and company default-text settings under the resource path. See Sales cluster SDK patterns.

Resources that are nice to have nearby (before or shortly after invoices), depending on how deeply you want sample probes and typed models to resolve links:

Resource Why it sits near invoices
Categories Implemented. Invoice, estimate, and bill line items reference categories
Bank accounts Invoice remittance via bank_account; later needed for bank explanations with paid_invoice
Projects Implemented. Optional on invoices; required for tasks and timeslips
Users Implemented. Not needed for invoices; required for timeslips and expenses

Implement after invoices if you care about end-to-end flows: credit note reconciliations, estimate-to-invoice conversion, timeslip billed_on_invoice, expense or bill rebilled_on_invoice, and bank explanation paid_invoice.

When you add or retrofit an SDK endpoint, check the relevant cluster page and update it if the official docs expose a URI link not yet shown.

Table of contents

Copyright © Mark Heydon. Distributed under the MIT licence.

This site uses Just the Docs, a documentation theme for Jekyll.