FreeAgent API Orchestration Skill

FreeAgent is an online accounting system for freelancers and small businesses. This skill provides intelligent navigation to FreeAgent API resources and orchestrates common workflows.

Quick Reference: Which Resource Do I Need?

resources/authentication-setup.md

resources/contacts-organizations.md

resources/accounting-objects.md

resources/banking-financial.md

resources/advanced-patterns.md

resources/examples.md

resources/endpoints.md

Orchestration Protocol

Phase 1: Task Analysis

Identify what the user needs:

By Resource Type:

• Authentication issue? →

  authentication-setup.md

• Managing contacts/clients? →

  contacts-organizations.md

• Financial data (invoices, expenses, projects)? →

  accounting-objects.md

• Banking/reconciliation? →

  banking-financial.md

• Error or production concern? →

  advanced-patterns.md

• Practical example needed? →

  examples.md

By HTTP Method:

• GET: List or retrieve → check relevant domain resource
• POST: Create → load resource file, check required fields
• PUT: Update → load resource file, verify patch fields
• DELETE: Remove → check resource-specific constraints

Phase 2: Resource Navigation

Load the appropriate resource file and:

1. Find the endpoint section (e.g., "Contacts", "Invoices", "Bank Accounts")
2. Review required/optional parameters
3. Check request and response formats
4. Use provided curl or Python examples

For template code:

templates/api-request-template.sh

templates/python-client.py

Phase 3: Execution & Validation

Before API call:

• Verify authentication is set up (check

  authentication-setup.md

  if needed)
• Validate required fields are present
• Format dates as ISO 8601 (YYYY-MM-DD) and timestamps (YYYY-MM-DDTHH:MM:SSZ)
• Use correct resource URLs (e.g.,

  https://api.freeagent.com/v2/contacts/123

  )

During API call:

• Use templates as starting points
• Monitor rate limit headers:

  X-RateLimit-Remaining

• Implement retry logic for 429 errors (see

  advanced-patterns.md

  )

After API call:

• Check response status code
• Parse JSON response (resource name is top-level key)
• Apply error handling patterns if needed

Quick Start: Authentication

1. Create OAuth app: https://dev.freeagent.com/
2. Get authorization code:

   https://api.freeagent.com/v2/approve_app?client_id=YOUR_ID

3. Exchange for tokens at

   https://api.freeagent.com/v2/token_endpoint

4. Store in environment variables:

   FREEAGENT_ACCESS_TOKEN

   ,

   FREEAGENT_REFRESH_TOKEN

5. Include in every request:

   Authorization: Bearer $FREEAGENT_ACCESS_TOKEN

→ See Authentication & Setup for detailed walkthrough

API Domain Overview

Production URL:

https://api.freeagent.com/v2/

https://api.sandbox.freeagent.com/v2/

/token_endpoint

/contacts

/company

/users

/invoices

/projects

/expenses

/timeslips

/estimates

/credit_notes

/bank_accounts

/bank_transactions

/categories

/tasks

Rate Limits: 120 requests/minute, 3600 requests/hour Response Format: JSON with resource wrapper (e.g.,

{"contact": {...}}

{"contacts": [...]}

Common HTTP Patterns

GET /v2/contacts?view=active&page=1&per_page=100

GET /v2/contacts/123

POST /v2/contacts

PUT /v2/invoices/456

DELETE /v2/timeslips/789

?view=open_or_overdue

?updated_since=2025-01-01T00:00:00Z

Templates & Code Examples

Bash/cURL Template:

templates/api-request-template.sh

• Flexible curl template for any endpoint
• GET/POST/PUT/DELETE support
• Header and parameter configuration

Python Client:

templates/python-client.py

• Reusable FreeAgentClient class
• Error handling and rate limit support
• Convenience methods for common resources

Practical Examples:

resources/examples.md

• Real-world workflows (create invoice, log timeslip, etc.)
• Python code patterns with the client class
• Error handling examples
• Bulk operations (import/export)

Resource Files Summary

authentication-setup.md

contacts-organizations.md

accounting-objects.md

banking-financial.md

advanced-patterns.md

examples.md

endpoints.md

Troubleshooting Quick Links

401 Unauthorized → Authentication Setup 422 Validation Error → Advanced Patterns 429 Rate Limit → Advanced Patterns Specific Endpoint Help → Check relevant domain resource file above

Remember: Load only the resource file(s) you need for the current task. Start with the Quick Reference table above to identify which resource contains your answer.