freeagentrb 0.1.4 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (100) hide show
  1. checksums.yaml +4 -4
  2. data/.env.example +3 -1
  3. data/CHANGELOG.md +65 -0
  4. data/Gemfile +3 -3
  5. data/Gemfile.lock +78 -61
  6. data/README.md +747 -3
  7. data/bin/console +2 -0
  8. data/bin/fixtures +148 -0
  9. data/freeagentrb.gemspec +4 -5
  10. data/lib/free_agent/client.rb +164 -4
  11. data/lib/free_agent/error_generator.rb +4 -3
  12. data/lib/free_agent/oauth.rb +48 -0
  13. data/lib/free_agent/object.rb +113 -17
  14. data/lib/free_agent/objects/account_lock.rb +4 -0
  15. data/lib/free_agent/objects/account_manager.rb +4 -0
  16. data/lib/free_agent/objects/balance_sheet.rb +4 -0
  17. data/lib/free_agent/objects/bank_feed.rb +4 -0
  18. data/lib/free_agent/objects/bank_transaction.rb +7 -12
  19. data/lib/free_agent/objects/bill.rb +1 -0
  20. data/lib/free_agent/objects/capital_asset.rb +4 -0
  21. data/lib/free_agent/objects/capital_asset_type.rb +4 -0
  22. data/lib/free_agent/objects/cashflow.rb +5 -0
  23. data/lib/free_agent/objects/cis_band.rb +4 -0
  24. data/lib/free_agent/objects/cis_settings.rb +4 -0
  25. data/lib/free_agent/objects/corporation_tax_return.rb +5 -0
  26. data/lib/free_agent/objects/credit_note.rb +1 -0
  27. data/lib/free_agent/objects/credit_note_reconciliation.rb +5 -0
  28. data/lib/free_agent/objects/estimate.rb +1 -0
  29. data/lib/free_agent/objects/expense.rb +5 -0
  30. data/lib/free_agent/objects/final_accounts_report.rb +4 -0
  31. data/lib/free_agent/objects/hire_purchase.rb +4 -0
  32. data/lib/free_agent/objects/invoice.rb +1 -9
  33. data/lib/free_agent/objects/journal_set.rb +4 -0
  34. data/lib/free_agent/objects/note.rb +4 -0
  35. data/lib/free_agent/objects/payroll_period.rb +4 -0
  36. data/lib/free_agent/objects/payroll_profile.rb +5 -0
  37. data/lib/free_agent/objects/practice.rb +4 -0
  38. data/lib/free_agent/objects/practice_client.rb +4 -0
  39. data/lib/free_agent/objects/price_list_item.rb +5 -0
  40. data/lib/free_agent/objects/profit_and_loss.rb +6 -0
  41. data/lib/free_agent/objects/property.rb +4 -0
  42. data/lib/free_agent/objects/recurring_invoice.rb +5 -0
  43. data/lib/free_agent/objects/sales_tax_period.rb +4 -0
  44. data/lib/free_agent/objects/self_assessment_return.rb +4 -0
  45. data/lib/free_agent/objects/stock_item.rb +5 -0
  46. data/lib/free_agent/objects/tax_timeline_item.rb +5 -0
  47. data/lib/free_agent/objects/timeline_item.rb +5 -0
  48. data/lib/free_agent/objects/transaction.rb +5 -0
  49. data/lib/free_agent/objects/trial_balance_item.rb +5 -0
  50. data/lib/free_agent/objects/vat_return.rb +4 -0
  51. data/lib/free_agent/rate_limiter.rb +67 -0
  52. data/lib/free_agent/resource.rb +6 -2
  53. data/lib/free_agent/resources/account_locks.rb +24 -0
  54. data/lib/free_agent/resources/account_managers.rb +19 -0
  55. data/lib/free_agent/resources/balance_sheet.rb +15 -0
  56. data/lib/free_agent/resources/bank_accounts.rb +5 -7
  57. data/lib/free_agent/resources/bank_feeds.rb +13 -0
  58. data/lib/free_agent/resources/bank_transaction_explanations.rb +41 -1
  59. data/lib/free_agent/resources/bank_transactions.rb +1 -1
  60. data/lib/free_agent/resources/capital_asset_types.rb +28 -0
  61. data/lib/free_agent/resources/capital_assets.rb +14 -0
  62. data/lib/free_agent/resources/cashflow.rb +8 -0
  63. data/lib/free_agent/resources/categories.rb +33 -0
  64. data/lib/free_agent/resources/cis_bands.rb +8 -0
  65. data/lib/free_agent/resources/cis_settings.rb +15 -0
  66. data/lib/free_agent/resources/clients.rb +8 -0
  67. data/lib/free_agent/resources/company.rb +12 -0
  68. data/lib/free_agent/resources/contacts.rb +2 -2
  69. data/lib/free_agent/resources/corporation_tax_returns.rb +34 -0
  70. data/lib/free_agent/resources/credit_note_reconciliations.rb +31 -0
  71. data/lib/free_agent/resources/credit_notes.rb +0 -10
  72. data/lib/free_agent/resources/email_addresses.rb +9 -0
  73. data/lib/free_agent/resources/estimate_items.rb +3 -4
  74. data/lib/free_agent/resources/estimates.rb +30 -3
  75. data/lib/free_agent/resources/expenses.rb +45 -0
  76. data/lib/free_agent/resources/final_accounts_reports.rb +24 -0
  77. data/lib/free_agent/resources/hire_purchases.rb +13 -0
  78. data/lib/free_agent/resources/invoices.rb +22 -0
  79. data/lib/free_agent/resources/journal_sets.rb +37 -0
  80. data/lib/free_agent/resources/notes.rb +37 -0
  81. data/lib/free_agent/resources/payroll.rb +32 -0
  82. data/lib/free_agent/resources/payroll_profiles.rb +9 -0
  83. data/lib/free_agent/resources/practice.rb +10 -0
  84. data/lib/free_agent/resources/price_list_items.rb +30 -0
  85. data/lib/free_agent/resources/profit_and_loss.rb +10 -0
  86. data/lib/free_agent/resources/projects.rb +2 -2
  87. data/lib/free_agent/resources/properties.rb +29 -0
  88. data/lib/free_agent/resources/recurring_invoices.rb +23 -0
  89. data/lib/free_agent/resources/sales_tax_periods.rb +37 -0
  90. data/lib/free_agent/resources/self_assessment_returns.rb +36 -0
  91. data/lib/free_agent/resources/stock_items.rb +13 -0
  92. data/lib/free_agent/resources/tasks.rb +5 -4
  93. data/lib/free_agent/resources/timeslips.rb +20 -3
  94. data/lib/free_agent/resources/transactions.rb +15 -0
  95. data/lib/free_agent/resources/trial_balance.rb +13 -0
  96. data/lib/free_agent/resources/users.rb +3 -3
  97. data/lib/free_agent/resources/vat_returns.rb +35 -0
  98. data/lib/free_agent/version.rb +1 -1
  99. data/lib/free_agent.rb +67 -0
  100. metadata +83 -24
data/README.md CHANGED
@@ -1,8 +1,6 @@
1
1
  # FreeAgentRB
2
2
 
3
- **This library is a work in progress**
4
-
5
- FreeAgentRB is a Ruby library for interacting with the FreeAgent v2 API.
3
+ FreeAgentRB is the easiest and most complete Ruby library for the FreeAgent v2 API.
6
4
 
7
5
  ## Installation
8
6
 
@@ -23,6 +21,123 @@ See [this page](https://dev.freeagent.com/docs/quick_start) for more info.
23
21
  @client = FreeAgent::Client.new(access_token: "", sandbox: true)
24
22
  ```
25
23
 
24
+ ### API Versions
25
+
26
+ FreeAgent versions breaking changes by date. Without a version, each endpoint
27
+ behaves as it did before versioning was introduced. To opt in to a newer
28
+ version, pass `api_version`, which is sent as the `X-Api-Version` header. See
29
+ [the FreeAgent docs](https://dev.freeagent.com/docs/versioning) for more info.
30
+
31
+ ```ruby
32
+ @client = FreeAgent::Client.new(access_token: "", api_version: "2026-09-01")
33
+ ```
34
+
35
+ ### Rate Limiting
36
+
37
+ The library automatically tracks rate limiting based on the FreeAgent API's `Retry-After` header when you receive a 429 (Too Many Requests) response. You can access rate limit information through the client's rate limiter:
38
+
39
+ ```ruby
40
+ # Initialize with optional logger
41
+ require "logger"
42
+ logger = Logger.new($stdout)
43
+ @client = FreeAgent::Client.new(access_token: "", sandbox: true, logger: logger)
44
+
45
+ # Check rate limit status
46
+ @client.rate_limiter.status
47
+ # => "Not rate limited" or "Rate limited. Retry in 60 seconds"
48
+
49
+ # Check if currently rate limited
50
+ @client.rate_limiter.rate_limited?
51
+ # => true/false
52
+
53
+ # Get seconds until rate limit resets
54
+ @client.rate_limiter.reset_in
55
+ # => 60 (seconds remaining)
56
+
57
+ # Manually wait if rate limited
58
+ @client.rate_limiter.wait_if_rate_limited
59
+ ```
60
+
61
+ For testing rate limiting in the sandbox, enable the `X-RateLimit-Test` header:
62
+
63
+ ```ruby
64
+ # This artificially lowers sandbox API calls to 5 requests/minute
65
+ @client = FreeAgent::Client.new(
66
+ access_token: "",
67
+ sandbox: true,
68
+ enable_rate_limit_test: true
69
+ )
70
+ ```
71
+
72
+ ### OAuth
73
+
74
+ This library includes the ability to create, refresh and revoke OAuth tokens.
75
+
76
+ ```ruby
77
+ # Firstly, set the client details
78
+ @oauth = FreeAgent::OAuth.new(sandbox: true, client_id: "", client_secret: "")
79
+
80
+ # Generate an authorisation URL
81
+ # state can be nil
82
+ @oauth.authorise_url(redirect: "https://mysite.com/auth", state: "something")
83
+
84
+ # Create a Token from the authorisation code
85
+ @oauth.create(token: "abc123", redirect: "https://mysite.com/auth")
86
+
87
+ # Refresh a Token
88
+ @oauth.refresh(refresh_token: "abc123")
89
+ ```
90
+
91
+
92
+ ## Resources
93
+
94
+ Methods that return a list give you a `FreeAgent::Collection`, which responds
95
+ to `each`, `count`, `first` and `last`, along with `total` (from the
96
+ `X-Total-Count` header) and `pagination` (from the `Link` header).
97
+
98
+ Any extra keyword arguments are passed through to the API as query parameters
99
+ on list methods, or as attributes on create and update, so anything documented
100
+ by FreeAgent that isn't named below can still be sent.
101
+
102
+ Attributes that reference another record are given as full URLs, e.g.
103
+ `contact: "https://api.freeagent.com/v2/contacts/1"`.
104
+
105
+ ### Company
106
+
107
+ ```ruby
108
+ @client.company.retrieve
109
+
110
+ # The business categories a company can choose from, as strings
111
+ @client.company.business_categories
112
+
113
+ # Upcoming tax deadlines and payments
114
+ @client.company.tax_timeline
115
+ ```
116
+
117
+ ### Contacts
118
+
119
+ ```ruby
120
+ @client.contacts.list
121
+ @client.contacts.list(view: "active")
122
+ @client.contacts.retrieve(id: "12345")
123
+ @client.contacts.create first_name: "Dwight", last_name: "Schrute"
124
+ @client.contacts.update id: "12345", first_name: "Dwight Kurt"
125
+ @client.contacts.delete id: "12345"
126
+ ```
127
+
128
+ ### Users
129
+
130
+ ```ruby
131
+ @client.users.me
132
+ @client.users.update_me first_name: "Dwight"
133
+
134
+ @client.users.list
135
+ @client.users.retrieve(id: "12345")
136
+ @client.users.create email: "dwight@example.com", first_name: "Dwight", last_name: "Schrute", role: "Director"
137
+ @client.users.update id: "12345", role: "Employee"
138
+ @client.users.delete id: "12345"
139
+ ```
140
+
26
141
  ### Bank Accounts
27
142
 
28
143
  ```ruby
@@ -31,4 +146,633 @@ See [this page](https://dev.freeagent.com/docs/quick_start) for more info.
31
146
  @client.bank_accounts.retrieve(id: "12345")
32
147
  @client.bank_accounts.create type: "StandardBankAccount", name: "My Account", opening_balance: "10"
33
148
  @client.bank_accounts.update id: "12345", name: "My Other Account"
149
+ @client.bank_accounts.delete id: "12345"
150
+ ```
151
+
152
+ ### Bank Transactions
153
+
154
+ A bank account is required when listing.
155
+
156
+ ```ruby
157
+ @client.bank_transactions.list bank_account: "https://api.freeagent.com/v2/bank_accounts/1"
158
+ @client.bank_transactions.list bank_account: "...", view: "unexplained"
159
+ @client.bank_transactions.retrieve(id: "12345")
160
+ @client.bank_transactions.delete id: "12345"
161
+
162
+ # Upload a statement as an array of transactions
163
+ @client.bank_transactions.create bank_account: "...", statement: [
164
+ { dated_on: "2026-08-15", amount: "100.0", description: "Payment" }
165
+ ]
166
+
167
+ # Or upload a statement file (OFX, QIF, CSV)
168
+ @client.bank_transactions.upload bank_account: "...", statement: "statement.csv"
169
+ ```
170
+
171
+ ### Bank Transaction Explanations
172
+
173
+ ```ruby
174
+ @client.bank_transaction_explanations.list bank_account: "https://api.freeagent.com/v2/bank_accounts/1"
175
+ @client.bank_transaction_explanations.retrieve(id: "12345")
176
+ @client.bank_transaction_explanations.create bank_transaction: "...", dated_on: "2026-08-15", gross_value: "-100.0", category: "..."
177
+ @client.bank_transaction_explanations.update id: "12345", description: "Hosting"
178
+ @client.bank_transaction_explanations.delete id: "12345"
179
+
180
+ # File attachments, up to 50 per explanation. These endpoints always send
181
+ # X-Api-Version 2026-09-01 or later.
182
+ @client.bank_transaction_explanations.attachments id: "12345"
183
+ @client.bank_transaction_explanations.add_attachments id: "12345", attachments: [
184
+ { data: Base64.strict_encode64(File.binread("receipt.png")), file_name: "receipt.png", content_type: "image/png" }
185
+ ]
186
+ @client.bank_transaction_explanations.update_attachments id: "12345", attachments: [
187
+ { url: "https://api.freeagent.com/v2/attachments/1", description: "Printer receipt" },
188
+ { url: "https://api.freeagent.com/v2/attachments/2", _destroy: true }
189
+ ]
190
+ @client.bank_transaction_explanations.delete_attachments id: "12345"
191
+ ```
192
+
193
+ From 1 December 2026, explanations return an `attachments` array instead of a
194
+ single `attachment`, and attachments can only be changed through the endpoints
195
+ above.
196
+
197
+ ### Projects
198
+
199
+ ```ruby
200
+ @client.projects.list
201
+ @client.projects.list(view: "active")
202
+ @client.projects.list_for_contact contact: "https://api.freeagent.com/v2/contacts/1"
203
+ @client.projects.retrieve(id: "12345")
204
+ @client.projects.create contact: "...", name: "My Project", status: "Active", currency: "GBP", budget_units: "Hours"
205
+ @client.projects.update id: "12345", name: "Renamed Project"
206
+ @client.projects.delete id: "12345"
207
+ ```
208
+
209
+ ### Tasks
210
+
211
+ ```ruby
212
+ @client.tasks.list
213
+ @client.tasks.list_for_project project: "https://api.freeagent.com/v2/projects/1"
214
+ @client.tasks.retrieve(id: "12345")
215
+ @client.tasks.create project: "...", name: "My Task", currency: "GBP", is_billable: true, status: "Active"
216
+ @client.tasks.update id: "12345", name: "Renamed Task"
217
+ @client.tasks.delete id: "12345"
218
+ ```
219
+
220
+ ### Timeslips
221
+
222
+ ```ruby
223
+ @client.timeslips.list
224
+ @client.timeslips.list(from_date: "2026-01-01", to_date: "2026-01-31")
225
+ @client.timeslips.list_for_user user: "https://api.freeagent.com/v2/users/1"
226
+ @client.timeslips.list_for_task task: "https://api.freeagent.com/v2/tasks/1"
227
+ @client.timeslips.list_for_project project: "https://api.freeagent.com/v2/projects/1"
228
+ @client.timeslips.retrieve(id: "12345")
229
+ @client.timeslips.create task: "...", user: "...", project: "...", dated_on: "2026-08-15", hours: "7.5"
230
+
231
+ # Create several at once
232
+ @client.timeslips.create_many timeslips: [
233
+ { task: "...", user: "...", project: "...", dated_on: "2026-08-15", hours: "7.5" },
234
+ { task: "...", user: "...", project: "...", dated_on: "2026-08-16", hours: "6.0" }
235
+ ]
236
+
237
+ @client.timeslips.update id: "12345", hours: "8.0"
238
+ @client.timeslips.delete id: "12345"
239
+
240
+ @client.timeslips.start_timer id: "12345"
241
+ @client.timeslips.stop_timer id: "12345"
242
+ ```
243
+
244
+ ### Invoices
245
+
246
+ ```ruby
247
+ @client.invoices.list
248
+ @client.invoices.list(view: "open", nested_invoice_items: true)
249
+ @client.invoices.list_for_contact contact: "https://api.freeagent.com/v2/contacts/1"
250
+ @client.invoices.list_for_project project: "https://api.freeagent.com/v2/projects/1"
251
+ @client.invoices.retrieve(id: "12345")
252
+
253
+ @client.invoices.create contact: "...", dated_on: "2026-08-15", payment_terms_in_days: 30, invoice_items: [
254
+ { description: "Consultancy", item_type: "Hours", price: "100.0", quantity: "10.0" }
255
+ ]
256
+
257
+ @client.invoices.update id: "12345", reference: "002"
258
+ @client.invoices.delete id: "12345"
259
+ @client.invoices.duplicate id: "12345"
260
+
261
+ # Returns a Base64-encoded PDF
262
+ @client.invoices.retrieve_pdf id: "12345"
263
+
264
+ @client.invoices.email id: "12345", to: "someone@example.com", subject: "Your invoice"
265
+
266
+ @client.invoices.mark_as_sent id: "12345"
267
+ @client.invoices.mark_as_scheduled id: "12345"
268
+ @client.invoices.mark_as_draft id: "12345"
269
+ @client.invoices.mark_as_cancelled id: "12345"
270
+ @client.invoices.convert_to_credit_note id: "12345"
271
+ @client.invoices.direct_debit id: "12345"
272
+
273
+ # Recent activity across all invoices
274
+ @client.invoices.timeline
275
+
276
+ # The text added to the bottom of every new invoice
277
+ @client.invoices.default_additional_text
278
+ @client.invoices.update_default_additional_text "Thanks for your business"
279
+ @client.invoices.delete_default_additional_text
280
+ ```
281
+
282
+ `net_value`, `total_value`, `paid_value`, `due_value` and `sales_tax_value` are
283
+ returned as floats rather than the strings the API sends. The same applies to
284
+ credit notes, bills, estimates and expenses.
285
+
286
+ ### Estimates
287
+
288
+ ```ruby
289
+ @client.estimates.list
290
+ @client.estimates.list_for_contact contact: "https://api.freeagent.com/v2/contacts/1"
291
+ @client.estimates.list_for_project project: "https://api.freeagent.com/v2/projects/1"
292
+ @client.estimates.list_for_invoice invoice: "https://api.freeagent.com/v2/invoices/1"
293
+ @client.estimates.retrieve(id: "12345")
294
+ @client.estimates.create contact: "...", dated_on: "2026-08-15", currency: "GBP", reference: "001"
295
+ @client.estimates.update id: "12345", reference: "002"
296
+ @client.estimates.delete id: "12345"
297
+
298
+ # The copy is a draft dated today, with the next reference
299
+ @client.estimates.duplicate id: "12345"
300
+
301
+ # Returns a Base64-encoded PDF
302
+ @client.estimates.retrieve_pdf id: "12345"
303
+
304
+ @client.estimates.email id: "12345", to: "someone@example.com"
305
+
306
+ @client.estimates.mark_as_sent id: "12345"
307
+ @client.estimates.mark_as_draft id: "12345"
308
+ @client.estimates.mark_as_approved id: "12345"
309
+ @client.estimates.mark_as_rejected id: "12345"
310
+ @client.estimates.convert_to_invoice id: "12345"
311
+
312
+ # The text added to the bottom of every new estimate
313
+ @client.estimates.default_additional_text
314
+ @client.estimates.update_default_additional_text "Please respond within 21 days"
315
+ @client.estimates.delete_default_additional_text
316
+ ```
317
+
318
+ ### Estimate Items
319
+
320
+ ```ruby
321
+ @client.estimate_items.create estimate: "https://api.freeagent.com/v2/estimates/1",
322
+ item_type: "Hours", quantity: "10.0", price: "100.0", description: "Consultancy"
323
+ @client.estimate_items.update id: "12345", description: "Updated"
324
+ @client.estimate_items.delete id: "12345"
325
+ ```
326
+
327
+ ### Recurring Invoices
328
+
329
+ Read-only.
330
+
331
+ ```ruby
332
+ @client.recurring_invoices.list
333
+ @client.recurring_invoices.list_for_contact contact: "https://api.freeagent.com/v2/contacts/1"
334
+ @client.recurring_invoices.list_for_project project: "https://api.freeagent.com/v2/projects/1"
335
+ @client.recurring_invoices.retrieve(id: "12345")
336
+ ```
337
+
338
+ ### Price List Items
339
+
340
+ ```ruby
341
+ @client.price_list_items.list
342
+ @client.price_list_items.retrieve(id: "12345")
343
+ @client.price_list_items.create code: "CONS", quantity: "1.0", item_type: "Hours",
344
+ description: "Consultancy", price: "100.0"
345
+ @client.price_list_items.update id: "12345", price: "120.0"
346
+ @client.price_list_items.delete id: "12345"
347
+ ```
348
+
349
+ ### Stock Items
350
+
351
+ Read-only.
352
+
353
+ ```ruby
354
+ @client.stock_items.list
355
+ @client.stock_items.retrieve(id: "12345")
356
+ ```
357
+
358
+ ### Credit Notes
359
+
360
+ ```ruby
361
+ @client.credit_notes.list
362
+ @client.credit_notes.list_for_contact contact: "https://api.freeagent.com/v2/contacts/1"
363
+ @client.credit_notes.list_for_project project: "https://api.freeagent.com/v2/projects/1"
364
+ @client.credit_notes.retrieve(id: "12345")
365
+ @client.credit_notes.create contact: "...", dated_on: "2026-08-15", payment_terms_in_days: 30
366
+ @client.credit_notes.update id: "12345", reference: "002"
367
+ @client.credit_notes.delete id: "12345"
368
+
369
+ # Returns a Base64-encoded PDF
370
+ @client.credit_notes.retrieve_pdf id: "12345"
371
+
372
+ @client.credit_notes.email id: "12345", to: "someone@example.com"
373
+
374
+ @client.credit_notes.mark_as_sent id: "12345"
375
+ @client.credit_notes.mark_as_draft id: "12345"
376
+ ```
377
+
378
+ ### Credit Note Reconciliations
379
+
380
+ ```ruby
381
+ @client.credit_note_reconciliations.list
382
+ @client.credit_note_reconciliations.retrieve(id: "12345")
383
+ @client.credit_note_reconciliations.create credit_note: "https://api.freeagent.com/v2/credit_notes/1",
384
+ invoice: "https://api.freeagent.com/v2/invoices/2", gross_value: "50.0"
385
+ @client.credit_note_reconciliations.update id: "12345", gross_value: "75.0"
386
+ @client.credit_note_reconciliations.delete id: "12345"
387
+ ```
388
+
389
+ ### Bills
390
+
391
+ ```ruby
392
+ @client.bills.list
393
+ @client.bills.list_for_contact contact: "https://api.freeagent.com/v2/contacts/1"
394
+ @client.bills.list_for_project project: "https://api.freeagent.com/v2/projects/1"
395
+ @client.bills.retrieve(id: "12345")
396
+
397
+ @client.bills.create contact: "...", dated_on: "2026-08-15", due_on: "2026-09-15", reference: "Bill-001", bill_items: [
398
+ { description: "Stationery", category: "https://api.freeagent.com/v2/categories/285", total_value: "100.0" }
399
+ ]
400
+
401
+ @client.bills.update id: "12345", reference: "Bill-002"
402
+ @client.bills.delete id: "12345"
403
+ ```
404
+
405
+ ### Expenses
406
+
407
+ ```ruby
408
+ @client.expenses.list
409
+ @client.expenses.list(from_date: "2026-01-01", to_date: "2026-01-31")
410
+ @client.expenses.list_for_user user: "https://api.freeagent.com/v2/users/1"
411
+ @client.expenses.list_for_project project: "https://api.freeagent.com/v2/projects/1"
412
+ @client.expenses.retrieve(id: "12345")
413
+
414
+ @client.expenses.create user: "...", category: "https://api.freeagent.com/v2/categories/285",
415
+ dated_on: "2026-08-15", gross_value: "-12.0", description: "Train fare"
416
+
417
+ # Mileage expenses use the Mileage category
418
+ @client.expenses.create user: "...", category: "Mileage", dated_on: "2026-08-15",
419
+ mileage: 100, vehicle_type: "Car"
420
+
421
+ @client.expenses.update id: "12345", description: "Updated"
422
+ @client.expenses.delete id: "12345"
423
+
424
+ @client.expenses.mileage_settings
425
+ ```
426
+
427
+ ### Journal Sets
428
+
429
+ ```ruby
430
+ @client.journal_sets.list
431
+ @client.journal_sets.opening_balances
432
+ @client.journal_sets.retrieve(id: "12345")
433
+
434
+ @client.journal_sets.create dated_on: "2026-08-15", description: "Adjustment", journal_entries: [
435
+ { category: "https://api.freeagent.com/v2/categories/285", debit_value: "100.0", description: "Stationery" },
436
+ { category: "https://api.freeagent.com/v2/categories/750", debit_value: "-100.0", description: "Stationery" }
437
+ ]
438
+
439
+ @client.journal_sets.update id: "12345", description: "Updated"
440
+ @client.journal_sets.delete id: "12345"
34
441
  ```
442
+
443
+ ### Transactions
444
+
445
+ The general ledger, as opposed to bank transactions. Read-only, and date
446
+ ranges must span 12 months or less.
447
+
448
+ ```ruby
449
+ @client.transactions.list
450
+ @client.transactions.list from_date: "2026-01-01", to_date: "2026-06-30"
451
+ @client.transactions.retrieve(id: "12345")
452
+ ```
453
+
454
+ ### Notes
455
+
456
+ The parent record goes in the query string rather than the body, so pass
457
+ either `contact:` or `project:`.
458
+
459
+ ```ruby
460
+ @client.notes.list_for_contact contact: "https://api.freeagent.com/v2/contacts/1"
461
+ @client.notes.list_for_project project: "https://api.freeagent.com/v2/projects/1"
462
+ @client.notes.retrieve(id: "12345")
463
+ @client.notes.create note: "Called them", contact: "https://api.freeagent.com/v2/contacts/1"
464
+ @client.notes.update id: "12345", note: "Updated"
465
+ @client.notes.delete id: "12345"
466
+ ```
467
+
468
+ ### Bank Feeds
469
+
470
+ Read-only.
471
+
472
+ ```ruby
473
+ @client.bank_feeds.list
474
+ @client.bank_feeds.retrieve(id: "12345")
475
+ ```
476
+
477
+ ### Email Addresses
478
+
479
+ Verified sender addresses, returned as a plain `Array` of strings.
480
+
481
+ ```ruby
482
+ @client.email_addresses.list
483
+ # => ["me@example.com"]
484
+ ```
485
+
486
+ ### Account Locks
487
+
488
+ ```ruby
489
+ # The locks, plus earliest_lock_date and latest_lock_date
490
+ @client.account_locks.retrieve
491
+ @client.account_locks.update locked_to_date: "2026-03-31"
492
+ @client.account_locks.delete
493
+ ```
494
+
495
+ ### Categories
496
+
497
+ Unlike other resources this returns a plain `Array`, with each category tagged
498
+ with the `category_type` it was listed under.
499
+
500
+ ```ruby
501
+ @client.categories.list
502
+ # => [#<FreeAgent::Category description="Accommodation and Travel",
503
+ # nominal_code="250", category_type="admin_expenses_categories">, ...]
504
+
505
+ # Include bank account, user and other sub accounts
506
+ @client.categories.list sub_accounts: true
507
+
508
+ @client.categories.retrieve nominal_code: "001"
509
+
510
+ # category_group is one of income, cost_of_sales, admin_expenses,
511
+ # current_assets, liabilities or equities
512
+ @client.categories.create description: "Consulting", nominal_code: "047", category_group: "income"
513
+ @client.categories.update nominal_code: "047", description: "Consultancy"
514
+ @client.categories.delete nominal_code: "047"
515
+ ```
516
+
517
+ ### Capital Assets
518
+
519
+ Read-only.
520
+
521
+ ```ruby
522
+ @client.capital_assets.list
523
+ @client.capital_assets.list include_history: true
524
+ @client.capital_assets.retrieve(id: "12345")
525
+ ```
526
+
527
+ ### Capital Asset Types
528
+
529
+ ```ruby
530
+ @client.capital_asset_types.list
531
+ @client.capital_asset_types.retrieve(id: "12345")
532
+ @client.capital_asset_types.create name: "Computer Equipment"
533
+ @client.capital_asset_types.update id: "12345", name: "Vehicles"
534
+ @client.capital_asset_types.delete id: "12345"
535
+ ```
536
+
537
+ ### Hire Purchases
538
+
539
+ Read-only.
540
+
541
+ ```ruby
542
+ @client.hire_purchases.list
543
+ @client.hire_purchases.retrieve(id: "12345")
544
+ ```
545
+
546
+ ### Reports
547
+
548
+ All read-only.
549
+
550
+ ```ruby
551
+ # Returns a FreeAgent::BalanceSheet. Defaults to today
552
+ @client.balance_sheet.retrieve
553
+ @client.balance_sheet.retrieve as_at_date: "2026-03-31"
554
+ @client.balance_sheet.opening_balances
555
+
556
+ # Returns a FreeAgent::ProfitAndLoss. Defaults to the current accounting year to date
557
+ @client.profit_and_loss.summary from_date: "2026-01-01", to_date: "2026-03-31"
558
+ @client.profit_and_loss.summary accounting_period: "2025/26"
559
+
560
+ # Return a collection of FreeAgent::TrialBalanceItem
561
+ @client.trial_balance.summary
562
+ @client.trial_balance.summary to_date: "2026-03-31"
563
+ @client.trial_balance.opening_balances
564
+
565
+ # Returns a FreeAgent::Cashflow
566
+ @client.cashflow.retrieve from_date: "2026-01-01", to_date: "2026-03-31"
567
+ ```
568
+
569
+ ### Final Accounts Reports
570
+
571
+ Reports are identified by the date their accounting period ends, not by an id.
572
+
573
+ ```ruby
574
+ @client.final_accounts_reports.list
575
+ @client.final_accounts_reports.retrieve period_ends_on: "2026-03-31"
576
+ @client.final_accounts_reports.mark_as_filed period_ends_on: "2026-03-31"
577
+ @client.final_accounts_reports.mark_as_unfiled period_ends_on: "2026-03-31"
578
+ ```
579
+
580
+ ### VAT Returns
581
+
582
+ Identified by the date their period ends. Each return includes a `breakdown`
583
+ of the boxes on the return.
584
+
585
+ ```ruby
586
+ @client.vat_returns.list
587
+ @client.vat_returns.retrieve period_ends_on: "2026-03-31"
588
+ @client.vat_returns.mark_as_filed period_ends_on: "2026-03-31"
589
+ @client.vat_returns.mark_as_unfiled period_ends_on: "2026-03-31"
590
+
591
+ # Payments are identified by their due_on date
592
+ @client.vat_returns.mark_payment_as_paid period_ends_on: "2026-03-31", payment_date: "2026-05-07"
593
+ @client.vat_returns.mark_payment_as_unpaid period_ends_on: "2026-03-31", payment_date: "2026-05-07"
594
+ ```
595
+
596
+ ### Corporation Tax Returns
597
+
598
+ ```ruby
599
+ @client.corporation_tax_returns.list
600
+ @client.corporation_tax_returns.retrieve period_ends_on: "2026-03-31"
601
+ @client.corporation_tax_returns.mark_as_filed period_ends_on: "2026-03-31"
602
+ @client.corporation_tax_returns.mark_as_unfiled period_ends_on: "2026-03-31"
603
+ @client.corporation_tax_returns.mark_as_paid period_ends_on: "2026-03-31"
604
+ @client.corporation_tax_returns.mark_as_unpaid period_ends_on: "2026-03-31"
605
+ ```
606
+
607
+ ### Self Assessment Returns
608
+
609
+ Nested under a user, and identified by the date the period ends. FreeAgent's
610
+ docs call these Income Tax Returns.
611
+
612
+ ```ruby
613
+ @client.self_assessment_returns.list user_id: "12345"
614
+ @client.self_assessment_returns.retrieve user_id: "12345", period_ends_on: "2026-04-05"
615
+ @client.self_assessment_returns.mark_as_filed user_id: "12345", period_ends_on: "2026-04-05"
616
+ @client.self_assessment_returns.mark_as_unfiled user_id: "12345", period_ends_on: "2026-04-05"
617
+
618
+ # Payments are identified by their due_on date
619
+ @client.self_assessment_returns.mark_payment_as_paid user_id: "12345", period_ends_on: "2026-04-05", payment_date: "2027-01-31"
620
+ @client.self_assessment_returns.mark_payment_as_unpaid user_id: "12345", period_ends_on: "2026-04-05", payment_date: "2027-01-31"
621
+ ```
622
+
623
+ ### Sales Tax Periods
624
+
625
+ US and Universal companies only.
626
+
627
+ ```ruby
628
+ @client.sales_tax_periods.list
629
+ @client.sales_tax_periods.retrieve(id: "12345")
630
+ @client.sales_tax_periods.create sales_tax_name: "Sales Tax", sales_tax_registration_status: "Registered",
631
+ sales_tax_rate_1: "8.0", sales_tax_is_value_added: false, effective_date: "2026-01-01"
632
+ @client.sales_tax_periods.update id: "12345", sales_tax_rate_1: "8.5"
633
+ @client.sales_tax_periods.delete id: "12345"
634
+ ```
635
+
636
+ ### CIS Bands
637
+
638
+ ```ruby
639
+ @client.cis_bands.list
640
+ ```
641
+
642
+ ### CIS Settings
643
+
644
+ ```ruby
645
+ @client.cis_settings.retrieve
646
+ @client.cis_settings.update contractor_details: { reporting_starts_on: "2024-05-06", paye_ni_period: "Monthly" }
647
+
648
+ # Deregister as a contractor
649
+ @client.cis_settings.update contractor_details: nil
650
+ ```
651
+
652
+ ### Payroll
653
+
654
+ Organised by tax year, then by period within that year. Read-only apart from
655
+ the payment transitions.
656
+
657
+ ```ruby
658
+ @client.payroll.list year: 2026
659
+
660
+ # A period, with its payslips
661
+ @client.payroll.retrieve year: 2026, period: 1
662
+
663
+ # PAYE payments due to HMRC, identified by their due_on date
664
+ @client.payroll.payments year: 2026
665
+ @client.payroll.mark_payment_as_paid year: 2026, payment_date: "2025-05-22"
666
+ @client.payroll.mark_payment_as_unpaid year: 2026, payment_date: "2025-05-22"
667
+ ```
668
+
669
+ ### Payroll Profiles
670
+
671
+ ```ruby
672
+ @client.payroll_profiles.list year: 2026
673
+ @client.payroll_profiles.list year: 2026, user: "https://api.freeagent.com/v2/users/1"
674
+ ```
675
+
676
+ ### Properties
677
+
678
+ `UkUnincorporatedLandlord` companies only.
679
+
680
+ ```ruby
681
+ @client.properties.list
682
+ @client.properties.retrieve(id: "12345")
683
+ @client.properties.create name: "12 High Street"
684
+ @client.properties.update id: "12345", name: "14 High Street"
685
+ @client.properties.delete id: "12345"
686
+ ```
687
+
688
+ ### Attachments
689
+
690
+ ```ruby
691
+ @client.attachments.retrieve(id: "12345")
692
+ @client.attachments.delete id: "12345"
693
+ ```
694
+
695
+ ### Accountancy Practice API
696
+
697
+ If you've authenticated as an accountancy practice, you can list the clients
698
+ your practice has access to and make requests on their behalf. See
699
+ [the FreeAgent docs](https://dev.freeagent.com/docs/accountancy_practice_api)
700
+ for more info.
701
+
702
+ These endpoints are only available to practice-level access tokens. If each of
703
+ your users connected their own FreeAgent account via OAuth, you don't need any
704
+ of this — their token is already scoped to their company.
705
+
706
+ #### Practice details
707
+
708
+ ```ruby
709
+ @client.practice.retrieve
710
+ # => #<FreeAgent::Practice name="My Practice", subdomain="mypracticesubdomain">
711
+ ```
712
+
713
+ #### Clients
714
+
715
+ ```ruby
716
+ @client.clients.list
717
+ @client.clients.list(view: "active")
718
+ @client.clients.list(sort: "-created_at")
719
+ @client.clients.list(updated_since: "2026-01-01T00:00:00Z")
720
+
721
+ # Fetch only the id, name and subdomain, up to 500 per page
722
+ @client.clients.list(minimal_data: true, per_page: 500)
723
+ ```
724
+
725
+ `view` accepts `all`, `active`, `inactive`, `closed`, `practice`, `linked`,
726
+ `copilot` and `demo`. `sort` accepts `created_at` and `updated_at`, prefixed
727
+ with `-` for descending order. `from_date` and `to_date` are also supported.
728
+
729
+ #### Account managers
730
+
731
+ ```ruby
732
+ @client.account_managers.list
733
+ @client.account_managers.retrieve(id: "123")
734
+
735
+ # The account manager the access token belongs to
736
+ @client.account_managers.me
737
+ ```
738
+
739
+ #### Making requests on behalf of a client
740
+
741
+ Requests are scoped to one of your clients by sending its subdomain in the
742
+ `X-Subdomain` header. Set it when building the client:
743
+
744
+ ```ruby
745
+ @client = FreeAgent::Client.new(access_token: "", subdomain: "testcompany")
746
+
747
+ # Every request is now made against that client's account
748
+ @client.invoices.list
749
+ @client.contacts.list
750
+ ```
751
+
752
+ Or derive a scoped client from your practice-level one, which is handy when
753
+ iterating over several clients:
754
+
755
+ ```ruby
756
+ @practice = FreeAgent::Client.new(access_token: "")
757
+
758
+ @practice.clients.list(minimal_data: true).each do |client|
759
+ @practice.on_behalf_of(client.subdomain).invoices.list
760
+ end
761
+ ```
762
+
763
+ `on_behalf_of` returns a new client and leaves the original untouched, so the
764
+ practice-level client can still be used for `clients`, `account_managers` and
765
+ `practice`.
766
+
767
+ ## Development
768
+
769
+ Tests stub every request with [WebMock](https://github.com/bblimke/webmock),
770
+ using the example responses from the [FreeAgent API docs](https://dev.freeagent.com/docs)
771
+ saved in `test/fixtures`. To refresh them when the docs change:
772
+
773
+ ```sh
774
+ bin/fixtures # every page
775
+ bin/fixtures contacts bills # just these pages
776
+ ```
777
+
778
+ Then run the tests with `bundle exec rake test`.