Please note, this API is out of date, you should of course be using the official Ruby wrapper (github.com/fac/freeagent-api-ruby).

The v1 API will be switched off on Monday 29th July 2013, and with it this repository will be taken offline.

Simple ActiveResource Ruby wrapper for the Freeagent Central API (www.freeagentcentral.com/developers/freeagent-api).

This supports all GET, POST, PUT and DELETE ActiveResource calls for the following API resources:

• Company

• Contacts

• Projects

• Tasks

• Invoices

• Invoice Items

• Timeslips

• Users

At the moment, the following API resources are NOT supported (although is being worked on):

• Expenses

• Attachments

Feel free to clone, fork and add tests.

To install as a Gem, just run:

$ sudo gem install freeagent_api -s http://gemcutter.org

Please note: version 0.2 is significantly different from 0.1 so if you are upgrading from the early development version please re-familiarise yourself with the documentation.

Freeagent.authenticate({
  :domain => 'yourdomain.freeagentcentral.com',
  :username => 'your@login.com',
  :password => 'your_password'})

Timelines

@invoice_timeline = Company.invoice_timeline
@tax_timeline = Company.tax_timeline

Find contacts

@contacts = Contact.find :all         # returns all contacts
@contact = Contact.find id            # returns specific contact

Create contact

# Required attributes
#   :first_name
#   :last_name

@contact = Contact.new params
@contact.save

Update contact

@contact.first_name = 'Joe'
@contact.save

Delete contact

Contact.delete id
# or
@contact.destroy

Find projects

@projects = Project.find :all         # returns all projects
@project = Project.find id            # returns specific project

Create project

# Required attribues
#   :contact_id
#   :name
#   :payment_term_in_days
#   :billing_basis                    # must be 1, 7, 7.5, or 8
#   :budget_units                     # must be Hours, Days, or Monetary
#   :status                           # must be Active or Completed

@project = Project.new params
@project.save

Update project

@project.name = 'Web design project'
@project.save

Delete project

Project.delete id
# or
@project.destroy

Nested resources

@invoices = @project.invoices
@timeslips = @project.timeslips

Find tasks

@tasks = Task.find :all               # returns all tasks
@task = Task.find id                  # returns specific task

Create task

# Required attributes
#   :name

@task = Task.new params
@task.save

Update task

@task.name = 'Create wireframes'
@task.save

Delete task

Task.delete id
# or
@task.destroy

Find Invoices

@invoices = Invoice.find :all         # returns all invoices
@invoice = Invoice.find id            # returns specific invoice

Create invoice

# Required attributes
#   :contact_id
#   :project_id
#   :dated_on
#   :reference
#   :status

@invoice = Invoice.new params
@invoice.save

Update invoice

@invoice.status = 'Sent'
@invoice.save

Delete invoice

Invoice.delete id
# or
@invoice.destroy

Changing status

@invoice.mark_as_draft
@invoice.mark_as_sent
@invoice.mark_as_cancelled

Find invoice items

@invoice_items = InvoiceItem.find :all  # returns all invoice items
@invoice_item = InvoiceItem.find id     # returns specific invoice item

Create invoice item

# Required attributes
#   :item_type                        # must be Hours, Days, Months, Years, Products, Services, Expenses, Discount, Credit, Comment
#   :description
#   :quantity
#   :price
#   :sales_tax_rate

@invoice_item = InvoiceItem.new params
@invoice_item.save

Update invoice item

@invoice_item.name = 'Create wireframes'
@invoice_item.save

Delete invoice item

InvoiceItem.delete id
# or
@invoice_item.destroy

Find timeslips

@timeslips = Timeslip.find :all, :params => {:from => '2009-10-01', :to => '2009-10-30'}
                                      # returns all timeslips (:from and :to dates required)
@timeslip = Timeslip.find id          # returns specific timeslip

Create timeslip

# Required attributes
#   :user_id
#   :hours
#   :dated_on
#   :task_id OR :new_task

@timeslip = Timeslip.new params
@timeslip.save

Update timeslip

@timeslip.hours = '3.5'
@timeslip.save

Delete timeslip

Timeslip.delete id
# or
@timeslip.destroy

Find users

@users = User.find :all       # returns all users
@user = User.find id          # returns specific user
@user = User.find_by_email email

Create user

# Required attributes
#   :first_name
#   :last_name
#   :email
#   :role                     # must be Owner, Director, Partner, Company Secretary, Employee, Shareholder, or Accountant
#   :password
#   :password_confirmation

@user = User.new params
@user.save

Update user

@user.first_name = 'Joe Bloggs'
@user.save

Delete user

User.delete id
# or
@user.destroy

• Aaron Russell - (www.aaronrussell.co.uk)

• Alex Comans - (www.alexcoomans.com)

Copyright © 2009-2010 Aaron Russell. See LICENSE for details.