FreeAgent Pet

Integration with FreeAgent accounting software API. Manage contacts, invoices, expenses, projects, and bank accounts for UK small businesses.

Features

• Contacts - Manage clients and suppliers
• Invoices - Create, list, and manage invoices
• Expenses - Track and categorize expenses
• Projects - Manage projects and budgets
• Bank Accounts - View and manage bank accounts
• Company Info - Get company details and settings

Setup

1. Register Your App

1. Go to FreeAgent Developer Dashboard
2. Create a new application
3. Note your Client ID and Client Secret

2. Get OAuth Access Token

FreeAgent uses OAuth 2.0 authentication. You need to:

1. Redirect users to authorize your app:

   https://api.freeagent.com/v2/approve_app?client_id=YOUR_CLIENT_ID&response_type=code&redirect_uri=YOUR_REDIRECT_URI

2. Exchange the authorization code for tokens:

   curl -X POST https://api.freeagent.com/v2/token_endpoint \
     -u "CLIENT_ID:CLIENT_SECRET" \
     -d "grant_type=authorization_code" \
     -d "code=AUTH_CODE" \
     -d "redirect_uri=YOUR_REDIRECT_URI"

3. Store the access token

3. Configure Environment

Create a .env file:

FREEAGENT_ACCESS_TOKEN=your_access_token_here

# Optional: Use production environment (default: sandbox)
FREEAGENT_ENVIRONMENT=production

# Optional: For token refresh
FREEAGENT_REFRESH_TOKEN=your_refresh_token
FREEAGENT_CLIENT_ID=your_client_id
FREEAGENT_CLIENT_SECRET=your_client_secret

Available Tools (29 total)

Company & Users

• freeagent-test-connection - Test API connection
• freeagent-get-company - Get company information
• freeagent-get-current-user - Get current user profile
• freeagent-list-users - List all users

Contacts

• freeagent-list-contacts - List all contacts
• freeagent-get-contact - Get contact by ID
• freeagent-create-contact - Create a contact
• freeagent-update-contact - Update a contact
• freeagent-delete-contact - Delete a contact

Projects

• freeagent-list-projects - List all projects
• freeagent-get-project - Get project by ID
• freeagent-create-project - Create a project
• freeagent-update-project - Update a project
• freeagent-delete-project - Delete a project

Invoices

• freeagent-list-invoices - List all invoices
• freeagent-get-invoice - Get invoice by ID
• freeagent-create-invoice - Create a draft invoice
• freeagent-update-invoice - Update an invoice
• freeagent-delete-invoice - Delete an invoice
• freeagent-mark-invoice-as-sent - Mark invoice as sent

Expenses

• freeagent-list-expenses - List all expenses
• freeagent-get-expense - Get expense by ID
• freeagent-create-expense - Create an expense
• freeagent-update-expense - Update an expense
• freeagent-delete-expense - Delete an expense

Bank Accounts

• freeagent-list-bank-accounts - List all bank accounts
• freeagent-get-bank-account - Get bank account by ID
• freeagent-create-bank-account - Create a bank account
• freeagent-update-bank-account - Update a bank account
• freeagent-delete-bank-account - Delete a bank account

Usage Examples

# Test connection
opencode run "test freeagent connection"

# Get company info
opencode run "get freeagent company information"

# List contacts
opencode run "list all freeagent contacts"

# List open invoices
opencode run "list open freeagent invoices"

# List overdue invoices
opencode run "list overdue freeagent invoices"

# List expenses from last month
opencode run "list freeagent expenses from 2026-01-01 to 2026-01-31"

# Create a contact
opencode run "create a freeagent contact for Acme Corp with email [email protected]"

Environment Switching

By default, the pet uses the sandbox environment for safe testing.

# Use sandbox (default)
FREEAGENT_ENVIRONMENT=sandbox opencode run "list contacts"

# Use production
FREEAGENT_ENVIRONMENT=production opencode run "list contacts"

Read-Only Mode

Enable read-only mode to prevent accidental writes:

pets read-only freeagent on

This disables all create, update, and delete operations.

Rate Limits

FreeAgent enforces these rate limits per user:

• 120 requests per minute
• 3600 requests per hour
• 15 token refreshes per minute

Exceeding limits returns HTTP 429 with a Retry-After header.

Token Expiry

Access tokens expire after 1 hour. Use the refresh token to get a new access token:

curl -X POST https://api.freeagent.com/v2/token_endpoint \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_REFRESH_TOKEN"

API Documentation

• FreeAgent API Docs
• OAuth Documentation
• API Introduction

Troubleshooting

401 Unauthorized

Your access token has expired. Refresh it using your refresh token.

403 Forbidden

Your app doesn't have permission for this endpoint. Check your app's access level in the FreeAgent Developer Dashboard.

429 Too Many Requests

You've hit the rate limit. Wait for the time specified in the Retry-After header.

Missing Tools

If write tools are missing, check if read-only mode is enabled:

pets read-only --status