The FreeAgent API provides secure programmatic access to the FreeAgent service, allowing you to build cool and useful tools and services on top.
This initial release of our API, covering the FreeAgent data listed on the right, will soon be enhanced with support for Bank Accounts and their associated Transactions and Entries, and for Payroll, Expenses and Taxes. Keep an eye on The Central for updates.
The FreeAgent API uses a RESTful style using XML over HTTP. Four HTTP methods are used: GET, POST, PUT and DELETE.
All API requests should be made via HTTPS using your own unique FreeAgent URL (e.g. https://nosteptwo.freeagentcentral.com), just like when you access the site through a browser. Authentication is managed using HTTP Basic Authentication. The user name and password you use to authenticate should be the email address and password you use to log into the website.
Every request to the FreeAgent API must be in XML format which means the "Content-Type" header must be set to "application/xml". To tell FreeAgent to send an XML response, the "Accept" header must also be set to "application/xml". Here's an example using Curl:
curl -u userid:password -H 'Accept: application/xml' -H 'Content-Type: application/xml' \
https://company.freeagentcentral.com/company/users
If an API request fails, the error information is returned with the HTTP status code. If you supply incorrect login details, you'll get a 401 Unauthorized response, such as:
HTTP/1.x 401 Unauthorized
Date: Fri, 14 Mar 2008 11:03:30 GMT
If you request a specific resource which cannot be found, you'll receive a 404 Not Found response:
HTTP/1.x 404 Not Found
Date: Fri, 14 Mar 2008 11:06:32 GMT
If you POST or PUT a resource with invalid XML, you'll receive a 400 Bad Request response, and the body of the reponse will contain the errors (if applicable):
HTTP/1.x 400 Bad Request
Date: Fri, 14 Mar 2008 11:06:32 GMT
<?xml version="1.0" encoding="UTF-8"?>
<errors>
<error>Name has already been taken</error>
</errors>
If a request causes a new record to be created (new Contact, Invoice, Project etc), the response will use a 201 Created status and the URI to the newly created resource will be present in the Location header:
HTTP/1.x 201 Created
Location: /projects/1/tasks/125
Date: Fri, 14 Mar 2008 11:06:32 GMT
Any other successful operation will use a 200 OK status code:
HTTP/1.x 200 OK
Date: Fri, 14 Mar 2008 11:10:22 GMT
The URIs in the FreeAgent API are the same as those you see in the browser. Here are some examples:
There are two resources available at the Company level. The /company/invoice_timeline resource provides information about due and overdue invoices:
<?xml version="1.0" encoding="UTF-8"?>
<invoice-timeline-items type="array">
<invoice_timeline_item>
<reference>Abstract Web Design 001</reference>
<summary>Payment: Abstract Web Design 001: £1,000.00 received</summary>
<description>Jackson Pollock: Abstract Web Design</description>
<dated_on>Tue Mar 18 00:00:00 UTC 2008</dated_on>
<amount>1000.0</amount>
</invoice_timeline_item>
</invoice-timeline-items>
The /company/tax_timeline resource provides information about upcoming tax events:
<?xml version="1.0" encoding="UTF-8"?>
<timeline-items type="array">
<timeline_item>
<description>Corporation Tax, year ending 05 Apr 07*</description>
<nature>Submission Due</nature>
<dated_on>Sat Apr 05 00:00:00 UTC 2008</dated_on>
<amount_due></amount_due>
<is_personal>false</is_personal>
</timeline_item>
<timeline_item>
<description>Corporation Tax, year ending 05 Apr 08*</description>
<nature>Payment Due</nature>
<dated_on>Tue Jan 06 00:00:00 UTC 2009</dated_on>
<amount_due>190.14</amount_due>
<is_personal>false</is_personal>
</timeline_item>
<timeline_item>
<description>Corporation Tax, year ending 05 Apr 08*</description>
<nature>Submission Due</nature>
<dated_on>Sun Apr 05 00:00:00 UTC 2009</dated_on>
<amount_due></amount_due>
<is_personal>false</is_personal>
</timeline_item>
</timeline-items>
The GET /contacts resource contains a list of all contacts. The XML representation is formatted like this:
<?xml version="1.0" encoding="UTF-8"?>
<contact>
<id type="integer">28</id>
<organisation-name></organisation-name>
<first-name>Andy</first-name>
<last-name>Warhol</last-name>
<address1></address1>
<address2></address2>
<address3></address3>
<town></town>
<region></region>
<country>United Kingdom</country>
<postcode></postcode>
<phone-number></phone-number>
<email></email>
<billing-email></billing-email>
<contact-name-on-invoices type="boolean">true</contact-name-on-invoices>
<sales-tax-registration-number></sales-tax-registration-number>
<uses-contact-invoice-sequence type="boolean">true</uses-contact-invoice-sequence>
<account-balance>1000.00</account-balance>
</contact>
Single contacts can be requested directly using GET /contacts/contact_id where contact_id is the ID of the contact.
To create a contact you should POST to /contacts. You only need to specify the required elements which for contacts are <first-name> and <last-name>, e.g.:
<?xml version="1.0" encoding="UTF-8"?>
<contact>
<first-name>Mark</first-name>
<last-name>Rothko</last-name>
</contact>
Updating a contact doesn't require every element. To update a contact's phone number, you should PUT to /contacts/contact_id with:
<?xml version="1.0" encoding="UTF-8"?>
<contact>
<phone-number>020 1234 4321</phone-number>
</contact>
To delete a contact you should DELETE to /contacts/contact_id. A contact can only be deleted if it has no projects. If the DELETE is unsuccessful, the response will be 409 Conflict.
To obtain a list of bills for a given period, use the GET /bills resource. This resource requires a view parameter which is used to specify the date range of the bills to retrieve. The format of this parameter is yyyy-mm-dd_yyyy-mm-dd where the first date is the 'from' date and the second date is the 'to' date.
The XML representation of a bill is:
<?xml version="1.0" encoding="UTF-8"?> <bill> <bill-type>Purchase of Capital Asset</bill-type> <cached-paid-value type="decimal">2050.0</cached-paid-value> <comments>A big pile of stuff</comments> <contact-id type="integer">1</contact-id> <dated-on type="datetime">2006-10-01T00:00:00Z</dated-on> <depreciation-schedule>3 Years</depreciation-schedule> <due-date type="datetime">2006-10-01T00:00:00Z</due-date> <id type="integer">1</id> <manual-sales-tax-amount type="decimal">0.0</manual-sales-tax-amount> <rebill-to-project-id type="integer" nil="true"></rebill-to-project-id> <rebilled-on-invoice-item-id type="integer" nil="true"></rebilled-on-invoice-item-id> <recurring nil="true"></recurring> <recurring-end-date type="date" nil="true"></recurring-end-date> <reference>JS0243</reference> <sales-tax-rate type="decimal">17.5</sales-tax-rate> <second-sales-tax-rate type="decimal">0.0</second-sales-tax-rate> <total-value type="decimal">2050.0</total-value> </bill>
Single bills can be requested directly using GET /bills/bill_id where bill_id is the ID of the bill.
To create a bill you should POST to /bills. You only need to specify the required elements which for bills are <bill-type>, <contact-id>, <reference>, <dated-on>, <due-date>, <total-value> and <sales-tax-rate>.
If you are creating or updating a recurring bill, the value of the recurring field must be one of:
The recurring-end-date value is optional, but if specified it must be a future date.
Updating a bill doesn't require every element to be specified. To update a bills reference, you should PUT to /bills/bill_id with:
<?xml version="1.0" encoding="UTF-8"?> <bill> <reference>NEW REFERENCE</reference> </bill>
To delete a bill you should DELETE to /bills/bill_id. A bill can only be deleted if is not inside a locked period, has no payments assigned to it and hasn't been rebilled. If the DELETE is unsuccessful, the response will be 409 Conflict.
The GET /projects resource contains a list of all projects. The XML representation is formatted like this:
<?xml version="1.0" encoding="UTF-8"?>
<project>
<id type="integer">20</id>
<contact-id type="integer">26</contact-id>
<name>Website redesign</name>
<billing-basis type="decimal">1</billing-basis>
<budget type="integer">0</budget>
<budget-units>Hours</budget-units>
<invoicing-reference></invoicing-reference>
<is-ir35 type="boolean">false</is-ir35>
<normal-billing-rate type="decimal">0.0</normal-billing-rate>
<starts-on type="datetime" nil="true">2006-09-01T00:00:00Z</starts-on>
<ends-on type="datetime" nil="true">2006-12-31T00:00:00Z</ends-on>
<status>Active</status>
<uses-project-invoice-sequence type="boolean">false</uses-project-invoice-sequence>
</project>
Single projects can be requested directly using GET /projects/project_id where project_id is the ID of the project.
To create a project you should POST to /projects. You only need to specify the required elements which for projects are <contact-id>, <name>, <status>, <billing-basis>, <budget-units> and <status>, e.g.:
<?xml version="1.0" encoding="UTF-8"?>
<project>
<contact-id type="integer">26</contact-id>
<name>Website redesign</name>
<billing-basis type="decimal">1</billing-basis>
<budget type="integer">0</budget>
<budget-units>Hours</budget-units>
<status>Active</status>
</project>
Three of these fields are restricted in what values can be supplied. <billing-basis> must be one of:
<budget-units> must be one of:
<status> must be one of:
Updating a project doesn't require every element. To update a projects's status, you should PUT to /projects/project_id with:
<?xml version="1.0" encoding="UTF-8"?>
<project>
<status>Completed</status>
</project>
To delete a project you should DELETE to /projects/project_id. A project can only be deleted if it has no dependent invoices, tasks, timeslips, bank account entries and expenses. If the DELETE is unsuccessful, the response will be 409 Conflict.
Two extra resources are available for projects. The GET /projects/project_id/invoices resource returns all the invoices associated with that project. The GET /projects/project_id/timeslips resource returns all the timeslips associated with that project.
The GET /projects/project_id/tasks resource contains a list of all tasks for the specified proejct. The XML representation is formatted like this:
<?xml version="1.0" encoding="UTF-8"?>
<task>
<id type="integer">38</id>
<project-id type="integer">19</project-id>
<name>Development</name>
</task>
Single tasks can be requested directly using GET /projects/project_id/tasks/task_id.
To create a task you should POST to /projects/project_id. You only need to specify <name>, e.g.:
<?xml version="1.0" encoding="UTF-8"?>
<task>
<name>New task name</name>
</task>
Similarly, to update a task's name you should PUT to /projects/project_id/tasks with:
<?xml version="1.0" encoding="UTF-8"?>
<task>
<name>Updated task name</name>
</task>
To delete a task you should DELETE to /projects/project_id/tasks/task_id. A task can only be deleted if no timeslips are dependent upon it. If the DELETE is unsuccessful, the response will be 409 Conflict.
The GET /invoices resource contains a list of all invoices as well as their corresponding invoice items. The XML representation is formatted like this:
<?xml version="1.0" encoding="UTF-8"?>
<invoices type="array">
<invoice>
<id type="integer">85</id>
<contact-id type="integer">10</contact-id>
<project-id type="integer">16</project-id>
<dated-on type="datetime">2008-02-17T00:00:00Z</dated-on>
<reference>Abstract Web Design 001</reference>
<net-value type="decimal">1000.0</net-value>
<sales-tax-value type="decimal">0.0</sales-tax-value>
<status>Sent</status>
<comments></comments>
<discount-percent type="decimal" nil="true"></discount-percent>
<omit-header type="boolean">false</omit-header>
<payment-terms></payment-terms>
<written-off-date type="datetime" nil="true"></written-off-date>
<invoice-items type="array">
<invoice-item>
<id type="integer">607</id>
<invoice-id type="integer">85</invoice-id>
<project-id type="integer" nil="true"></project-id>
<item-type>Services</item-type>
<description>Setting up hosting</description>
<price type="decimal">160.0</price>
<quantity type="decimal">1.0</quantity>
<sales-tax-rate type="decimal">17.5</sales-tax-rate>
<sales-tax-value type="float">175.0</sales-tax-value>
</invoice-item>
<invoice-item>
<id type="integer">611</id>
<invoice-id type="integer">85</invoice-id>
<project-id type="integer" nil="true"></project-id>
<item-type>Hours</item-type>
<description>Coding the templates</description>
<price type="decimal">40</price>
<quantity type="decimal">30</quantity>
<sales-tax-rate type="decimal">17.5</sales-tax-rate>
<sales-tax-value type="float">0.0</sales-tax-value>
</invoice-item>
</invoice-items>
</invoice>
</invoices>
Single invoices can be requested directly using GET /invoices/invoice_id where invoice_id is the ID of the invoice.
To create an invoice you should POST to /invoices. You only need to specify the required elements which for invoices are <contact-id>, <project-id>, <dated-on>, <reference> and <status>, e.g.:
<invoice>
<contact-id>42</contact-id>
<project-id>21</project-id>
<dated-on>2008-02-17T00:00:00Z</dated-on>
<reference>INVOICE 2001</reference>
<status>Draft</status>
<comments>A comment</comments>
</invoice>
Updating an invoice doesn't require every element. To update a invoice date, you should PUT to /invoices/invoice_id with:
<?xml version="1.0" encoding="UTF-8"?>
<invoice>
<dated-on>2008-02-29T00:00:00Z</dated-on>
</invoice>
To delete an invoice you should DELETE to /invoices/invoice_id. An invoice can only be deleted if it is in Draft state. If the DELETE is unsuccessful, the response will be 409 Conflict.
You can select all the invoices for a given project using GET /projects/project_id/invoices where project_id is the ID of the project.
Similarly you can select all the invoices for a given contact using GET /projects/contact_id/invoices where contact_id is the ID of the contact.
Specific resources exist for changing an invoice status. To change between Draft, Sent and Cancelled state, you must PUT to:
If the state transition cannot be made (e.g. if an invoice has no invoice items it cannot be marked as Sent), a 403 Forbidden response will be returned by these resources.
Note: marking an invoice as paid is handled automatically in FreeAgent through Bank Account Entries and Bank Transactions. These are not supported in the current API.
The GET /invoices/invoice_id/invoice_items resource contains a list of all invoice items for the invoice specified by invoice_id. The XML representation is formatted like this:
<?xml version="1.0" encoding="UTF-8"?>
<invoice-item>
<id type="integer">618</id>
<invoice-id type="integer">95</invoice-id>
<project-id type="integer" nil="true"></project-id>
<item-type>Hours</item-type>
<price type="decimal">1.0</price>
<quantity type="decimal">1.0</quantity>
<description>test</description>
<sales-tax-rate type="decimal">17.5</sales-tax-rate>
</invoice-item>
Single invoice items can be requested directly using GET /invoices/invoice_id/invoice_items/invoice_item_id.
To create an invoice item you should POST to /invoices/invoice_id/invoice_items. You only need to specify the required elements which for invoice items are <item-type>, <description>, <quantity>, <price>, <sales-tax-rate> and <last-name>, e.g.:
<?xml version="1.0" encoding="UTF-8"?>
<invoice-item>
<item-type>Hours</item-type>
<price>50</price>
<quantity>12</quantity>
<sales-tax-rate>17.5</sales-tax-rate>
<description>Creating wireframe templates</description>
</invoice-item>
The value of <item-type> must be one of:
Updating an invoice item doesn't require every element. To update an invoice item's quantity, you should PUT to /invoices/invoice_id/invoice_items/invoice_item_id with:
<?xml version="1.0" encoding="UTF-8"?>
<invoice-item>
<quantity>13</quantity>
</invoice-item>
To delete an invoice item you should DELETE to /invoices/invoice_id/invoice_items/invoice_item_id.
To obtain a list of timeslips for a given period, use the GET /timeslips resource. This resource requires a view parameter which is used to specify the date range of the timeslips to retrieve. The format of this parameter is yyyy-mm-dd_yyyy-mm-dd where the first date is the 'from' date and the second date is the 'to' date.
As an example, to obtain all the timeslips created between 1st March 2008 and 15th August 2008, the resource would be: /timeslips?view=2008-03-01_2008-08-15.
The XML representation of a timeslip is:
<?xml version="1.0" encoding="UTF-8"?>
<timeslip>
<id type="integer">169</id>
<dated-on type="datetime">2008-03-03T00:00:00Z</dated-on>
<project-id type="integer">8</project-id>
<task-id type="integer">38</task-id>
<user-id type="integer">11</user-id>
<hours type="decimal">1.0</hours>
<comment></comment>
</timeslip>
The GET /projects/project_id/timeslips resource contains a list of all the timeslips for that project.
Single timeslips can be requested directly using GET /timeslips/timeslip_id where timeslip_id is the ID of the timeslip.
To create a timeslip you should POST to /timeslips. You only need to specify the required elements which for timeslips are <project-id>, <user-id>, <hours>, <dated-on> and one of <task-id> or <new-task>. To create a timeslip for an existing task, use <task-id>, e.g.:
<?xml version="1.0" encoding="UTF-8"?>
<timeslip>
<dated-on>2008-03-03T00:00:00Z</dated-on>
<project-id type="integer">8</project-id>
<task-id>38</task-id>
<user-id>11</user-id>
<hours>1</hours>
</timeslip>
To create a timeslip with a new task, use <new-task>, e.g.:
<?xml version="1.0" encoding="UTF-8"?>
<timeslip>
<dated-on>2008-03-03T00:00:00Z</dated-on>
<project-id type="integer">8</project-id>
<new-task>The new task name</new-task>
<user-id>11</user-id>
<hours>1</hours>
</timeslip>
Updating a timeslip doesn't require every element. To update a timeslip's hours, you should PUT to /timeslips/timeslip_id with:
<?xml version="1.0" encoding="UTF-8"?>
<timeslip>
<hours>10</hours>
</timeslip>
To delete a timeslip you should DELETE to /timeslips/timeslip_id. A timeslip can only be deleted if has not been rebilled on an invoice. If the DELETE is unsuccessful, the response will be 409 Conflict.
The GET /company/users resource contains a list of all users. The XML representation is formatted like this:
<?xml version="1.0" encoding="UTF-8"?>
<user>
<company-id type="integer">10</company-id>
<email>olly@lylo.co.uk</email>
<first-name>Olly</first-name>
<id type="integer">11</id>
<last-logged-in-at type="datetime">2008-03-03T21:16:09Z</last-logged-in-at>
<last-name>Headey</last-name>
<opening-director-loan-account-balance type="decimal">0.0</opening-director-loan-account-balance>
<opening-expense-balance type="decimal">0.0</opening-expense-balance>
<opening-salary-balance type="decimal">0.0</opening-salary-balance>
<opening-share-or-capital-balance type="decimal">0.0</opening-share-or-capital-balance>
<role>Director</role>
</user>
Single users can be requested directly using GET /company/users/user_id where user_id is the ID of the user.
To create a user you should POST to /company/users. You only need to specify the required elements which for users are <first-name>, <last-name>, <email>, <role>, <password> and <password-confirmation>, e.g.:
<?xml version="1.0" encoding="UTF-8"?>
<user>
<first-name>John</first-name>
<last-name>Smith</last-name>
<email>john.smith@freeagentcentral.com</email>
<role>Director</role>
<password>password</password>
<password-confirmation>password</password-confirmation>
</user>
The value of <role> must be one of:
Updating a user doesn't require every element. To update a user's first name, you should PUT to /company/users/user_id with:
<?xml version="1.0" encoding="UTF-8"?>
<user>
<first-name>Dave</first-name>
</user>
To delete a user you should DELETE to /company/users/user_id. A user can only be deleted if there are no expenses, payslips, timeslips, tax returns and bank account entries dependent upon it. A company must have at least one user, therefore the final user can never be deleted. If the DELETE is unsuccessful, the response will be 409 Conflict.
To obtain a list of expenses for a given user, for a given period, use the GET /users/user_id/expenses resource. This resource requires a view parameter which is used to filter the results by type or the date range. The valid formats of this parameter are:
So, to obtain all the expenses for user "123" created between 1st March 2008 and 15th August 2008, the resource would be: /users/123/expenses?view=2008-03-01_2008-08-15. To view all the recurring expenses for user "123" would be /users/123/expenses?view=recurring and so on.
The XML representation of an expense is formatted like this:
<?xml version="1.0" encoding="UTF-8"?>
<expense>
<id type="integer">78</id>
<user-id type="integer">11</user-id>
<dated-on type="datetime">2008-03-29T00:00:00Z</dated-on>
<description>Hard drive</description>
<engine-size-index type="integer">1</engine-size-index>
<engine-type-index type="integer">0</engine-type-index>
<expense-type>Computer Hardware</expense-type>
<gross-value type="decimal">-200.0</gross-value>
<have-vat-receipt type="boolean">false</have-vat-receipt>
<initial-rate-mileage type="integer">0</initial-rate-mileage>
<mileage type="integer" nil="true"></mileage>
<rebill-mileage-rate type="decimal">0.4</rebill-mileage-rate>
<rebill-to-project-id type="integer" nil="true"></rebill-to-project-id>
<rebilled-on-invoice-item-id type="integer" nil="true"></rebilled-on-invoice-item-id>
<receipt-reference></receipt-reference>
<reclaim-mileage-rate type="decimal">0.4</reclaim-mileage-rate>
<recurring nil="true"></recurring>
<recurring-end-date type="datetime" nil="true"></recurring-end-date>
<sales-tax-rate type="decimal">17.5</sales-tax-rate>
<vehicle-type nil="true"></vehicle-type>
</expense>
Single expenses can be requested directly using GET /users/user_id/expenses/expense_id where expense_id is the ID of the expense.
Updating an expense doesn't require every element. To update an expenses description, you should PUT to /users/user_id/expenses/expense_id with:
<?xml version="1.0" encoding="UTF-8"?>
<expense>
<description>MacBook Pro</description>
</expense>
To delete an expense you should DELETE to /users/user_id/expenses/expense_id. If the DELETE is unsuccessful, the response will be 409 Conflict.
To create an expense you should POST to /users/user_id/expenses. You only need to specify the required elements which for standard (non-mileage) expenses are <description>, <dated-on>, <expense-type> and <gross-value>, e.g.:
<?xml version="1.0" encoding="UTF-8"?>
<expense>
<dated-on>2008-03-29T00:00:00Z</dated-on>
<description>MacBook Pro</description>
<expense-type>Computer Hardware</expense-type>
<gross-value>-300</gross-value>
</expense>
Mileage expenses (i.e. an expense with an <expense-type> of Mileage) are treated slightly differently to standard expenses. The behaviour is also different depending on the company type.
No <gross-value> field is required. Instead, a new numerical value <mileage> is required.
If <rebill-to-project-id> is specified, and references a valid project, <rebill_mileage_rate> is required and must be numeric.
<vehicle-type> is required and must be one of:
<have-vat-receipt> is required and must be either true or false.
<engine-type-index> is required and must be one of the following integer values:
<engine-size-index> is required and must be one of the following integer values:
Here is an example of a mileage expense for UK companies:
<?xml version="1.0" encoding="UTF-8"?>
<expense>
<dated-on>2008-03-29T00:00:00Z</dated-on>
<description>Visit to FreeAgent Central</description>
<expense-type>Mileage</expense-type>
<mileage>100</mileage>
<vehicle-type>Car</vehicle-type>
<engine_type_index>0</engine_type_index>
<engine-size-index>0</engine-size-index>
<have-vat-receipt>true</have-vat-receipt>
</expense>
The numeric value <reclaim-mileage-rate> is required.
The Attachments API provides the ability to view, upload or delete attachments in your account. The attachments can optionally be associated to existing Expenses, Bank Account Entries and Bills.
The GET /attachments resource contains a list of all the attachments for the associated account. The XML representation is formatted as follows:
<?xml version="1.0" encoding="UTF-8"?>
<attachments type="array">
<attachment>
<content_type>image/png</content_type>
<file_name>attachment.png</file_name>
<file_size>12320</file_size>
<description>This is my attachment</description>
<attachable_id>1234</attachable_id>
<attachable_type>Expense</attachable_type>
<data><!-- this field should contain Base64-encoded binary data --></data>
</attachment>
</attachments>
Single attachments can be requested directly using GET /attachments/attachment_id where attachment_id is the ID of the attachment. A URI to the original file is specified in the Location header:
HTTP/1.1 200 OK
Location: https://s3.amazonaws.com/freeagent-prod/attachments/1234/original.pdf?AWSAccessKeyId=1O3MC21E568KDBS84B14&Expires=1222982223&Signature=LIUxaetoSliE6cr8J0XDQVE5%2FZg%3D
Date: Thu, 2 Oct 2008 23:00:00 BST
Note: For security reasons this URI is temporary and will expire 5 minutes after the response was sent.
To upload an Attachment you should POST to /attachments:
<?xml version="1.0" encoding="UTF-8"?>
<attachment>
<content_type>image/png</content_type>
<file_name>attachment.png</file_name>
<description>This is my attachment</description>
<attachable_id>1234</attachable_id>
<attachable_type>Expense</attachable_type>
<data><!-- this field should contain Base64-encoded binary data --></data>
</attachment>
content_type, file_name, description and data are all required, the other fields are optional. Note: file_size is a calculated field so should not be supplied.
content_type can only be one of:
data must contain the binary data of the file being attached, encoded as Base64.
attachable_id is the ID of the resource to which the attachment is being attached, whilst attachable_type is the name of the type of this resource. For example, if there is an Expense in your FreeAgent account which has an ID of 1234 and you want to add an attachment to this resource, you would specify an attachable_id of 1234 and an attachable_type of Expense. Not all the resource types in FreeAgent support attachments, so currently the only valid values for attachable_type are:
Uploading an attachment without a corresponding attachable_id and attachable_type is permitted.
Note: there is a 2MB file size limit on each attachment.
Updating an attachment doesn't require every element. To update just the description, you should PUT to /attachments/attachment_id with:
<?xml version="1.0" encoding="UTF-8"?>
<attachment>
<description>This is my new description</description>
</attachment>
If you are updating attachable_id or attachable_type, both these fields are required for the update to be successful.
Binary file data should be sent, Base64 encoded, in the data field.
To delete an attachment you should DELETE to /attachments/attachment_id.
FreeAgent online accounting is a product of FreeAgent Central. Copyright © 2006–2010 by FreeAgent Central. All rights reserved.