canonical: https://jentic.com/apis/api.freeagent.com/freeagent

# FreeAgent API

Jentic publishes the only available OpenAPI specification for FreeAgent API, keeping it validated and agent-ready. FreeAgent is a UK-focused cloud accounting platform used by freelancers, contractors, and small businesses to handle invoicing, expenses, project time tracking, bills, and bank reconciliation. The 66-endpoint OAuth 2.0 REST API covers invoices (with state transitions for sent, scheduled, cancelled), contacts, projects, tasks, timeslips, expenses, bills, bank accounts, bank transactions, and users - enough surface to drive a full bookkeeping workflow programmatically.

## For AI agents

Manage FreeAgent invoices with state transitions, log timeslips against projects, record expenses and bills, and reconcile bank transactions for UK small business accounting.

## Scope

Does not handle payroll, payment processing, or tax filing - use for invoicing, time tracking, expenses, bills, and bank reconciliation only.

## Capabilities

- Issue an invoice and transition it through draft, scheduled, sent, and cancelled states
- Log a timeslip against a project task with hours and billable status
- Record an out-of-pocket expense or supplier bill with VAT codes
- Reconcile bank transactions against invoices, expenses, and bills
- Manage contacts (clients and suppliers) with addresses and tax references
- Send an invoice to a client by email directly from the API

## Use cases

### Automated Invoicing for Agencies

Generate FreeAgent invoices at the end of each project sprint by pulling logged timeslips, drafting an invoice with billable lines, and emailing it to the client - all without leaving the agency's project tool. Replaces copy-paste between Toggl-style time tools and FreeAgent and shortens the time from work-done to cash-collected.

Example prompt: POST /invoices with line items derived from /timeslips, then PUT `/invoices/{id}/transitions/mark_as_sent` and POST `/invoices/{id}/send_email` to deliver it

### Bank Reconciliation Sync

Pull bank transactions from FreeAgent, match them against open invoices, expenses, and bills, and surface unreconciled items for human review. The /bank_accounts and /bank_transactions endpoints provide the raw feed; downstream code matches and reconciles based on amount and reference. Cuts month-end close time for small finance teams.

Example prompt: GET /bank_transactions for an account filtered to unreconciled, then match against /invoices and /bills by amount and reference

### Expense Capture from Receipts

Wire a receipt-OCR pipeline into FreeAgent so that scanned receipts become structured /expenses entries with VAT codes and project tags. The 66 endpoints include full CRUD on expenses and tying them to projects, so reimbursement and project profitability calculations stay accurate without manual entry.

Example prompt: POST /expenses with the OCR-extracted amount, date, VAT code, and projectId so the expense is recorded against the correct cost centre

### AI Agent Bookkeeping via Jentic

An AI bookkeeping agent that handles routine entries ("draft this week's invoices", "reconcile yesterday's bank feed") can call FreeAgent through Jentic. Jentic handles the OAuth 2.0 token refresh and exposes the 66 operations as discoverable tools, so the agent only needs the high-level intent and the entity IDs.

Example prompt: Search Jentic for 'draft and send a freeagent invoice', load the POST /invoices and send_email schemas, and execute against a contactId and project line items

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/invoices` | List invoices with filters |
| POST | `/invoices` | Create a new invoice |
| PUT | `/invoices/{id}/transitions/mark_as_sent` | Mark an invoice as sent |
| POST | `/invoices/{id}/send_email` | Email an invoice to the client |
| GET | `/contacts` | List clients and suppliers |
| POST | `/timeslips` | Log time against a project task |
| POST | `/expenses` | Record an expense |
| GET | `/bank_transactions` | Read bank transactions for reconciliation |

## Key resources

- **Invoices** — Issue, edit, transition, duplicate, and email invoices; pull invoice timeline
- **Contacts** — Manage clients and suppliers with addresses and tax references
- **Projects** — Create and update projects to which timeslips and expenses attach
- **Tasks** — Project tasks used as the unit for timeslip logging
- **Timeslips** — Log billable and non-billable hours against project tasks
- **Expenses** — Record out-of-pocket expenses with VAT codes
- **Bills** — Track supplier bills and their payment status
- **BankAccounts** — List bank accounts configured in FreeAgent
- **BankTransactions** — Read bank transactions and reconciliation status
- **Users** — List users and their roles in the FreeAgent account

## Why Jentic

- **Setup:** Wiring FreeAgent by hand means running its OAuth2 flow and coding your own calls to the invoices, timeslips, expenses, and bank transaction endpoints. Through Jentic you install once, import the FreeAgent API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** FreeAgent puts the invoice id in the URL path (`/invoices/{id}/transitions/mark_as_sent`, `/invoices/{id}/send_email`), so a rule can pin your agent to acting on one invoice. You choose the operations it may call, so sending an invoice email is not included unless you add it.
- **Credential handling:** Your FreeAgent token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create an invoice' or 'list bank transactions', and Jentic returns the matching FreeAgent operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Xero Accounting** — Cloud accounting platform with broader international coverage and a wider app marketplace
- **Faktoora e-Invoicing** — EN16931-compliant e-invoicing for EU B2B and B2G that pairs with FreeAgent's UK bookkeeping
- **Sage** — Established UK accounting suite with deeper enterprise features but heavier setup

## FAQ

### Why is there no official OpenAPI spec for FreeAgent API?

FreeAgent does not publish an OpenAPI specification, only narrative developer docs. Jentic generates and maintains this spec so that AI agents and developers can call FreeAgent API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the FreeAgent API use?

FreeAgent uses OAuth 2.0 with the authorization code flow. Through Jentic, the client credentials and per-user refresh tokens are stored in the encrypted vault and exchanged automatically so agents call the 66 endpoints without managing token lifetime themselves.

### Can I send an invoice to a client via the API?

Yes. POST `/invoices/{id}/send_email` triggers the email send using the invoice template configured in FreeAgent. Combined with PUT `/invoices/{id}/transitions/mark_as_sent`, this fully automates the issue-and-deliver step.

### How do I move an invoice from draft to sent?

Use the transition endpoints under `/invoices/{id}/transitions/.` PUT mark_as_sent moves the invoice from draft to sent, mark_as_scheduled queues a future send date, and mark_as_cancelled voids it. The transitions enforce FreeAgent's state machine rather than letting you free-edit the status.

### How do I draft an invoice through Jentic?

Run pip install jentic, then search 'create a freeagent invoice'. Jentic returns the POST /invoices operation with its schema. Execute with the contactId, dated_on, and invoice_items; Jentic handles the OAuth token automatically.

### Does the API support bank reconciliation against transactions?

Yes. GET /bank_transactions returns transactions with their reconciliation status. You match against /invoices, /bills, and /expenses by amount and reference, then post the reconciliation. The endpoints support filtering by date range and account so you can sync incrementally.

### Can I limit what my agent is allowed to do with the FreeAgent API?

Yes. Because you run Jentic One yourself, your own rules decide which of the 66 FreeAgent operations the agent may call and which credentials it may use, so you can grant read-only access to GET /bank_transactions and GET /invoices while withholding write actions. Since FreeAgent puts the invoice id in the URL path, such as PUT `/invoices/{id}/transitions/mark_as_sent` and POST `/invoices/{id}/send_email`, a rule can pin the agent to acting on a single invoice. Sending an invoice email is not available to the agent unless you explicitly add that operation to its allowed set.