Accountancy Practice API

If you are an Accountancy Practice with a FreeAgent dashboard you can use the API to securely access your clients’ data.

Setup Instructions

Set up an application as normal by following the instructions in the Quick start guide.

Once you have created an application, you will need to share the application OAuth identifier with your FreeAgent Account Manager. They will arrange for Practice API access to be enabled for your application. Once enabled, your account managers will be able to authorise the application using OAuth and make requests to the Practice API to access data and perform actions on behalf of their clients.

Making API requests on behalf of clients

To make requests for a specific client of the authenticated account manager, include an additional X-Subdomain HTTP header in the request that specifies the client's subdomain:

X-Subdomain: companysubdomain

All the standard FreeAgent API endpoints can be accessed in this way. See the FreeAgent API Documentation for more details.

Practice-specific endpoints

In addition to the standard FreeAgent API endpoints, the following practice-specific endpoints are available.

List clients

You can use this API endpoint to get a list of the clients for the currently authenticated account manager. If they are a senior account manager, all clients for the practice will be returned.

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

Response

Status: 200 OK
{
  "clients": [
    {
      "locked_attributes": [
        "company_start_date",
        "freeagent_start_date",
        "trading_start_date",
        "currency",
        "sales_tax_registration_number",
        "sales_tax_effective_date",
        "vat_first_return_period_ends_on",
        "initial_vat_basis",
        "initially_on_frs",
        "initial_vat_frs_type"
      ],
      "sales_tax_rates": [
        "20.0",
        "5.0",
        "0.0"
      ],
      "account_manager": "https://api.freeagent.com/v2/account_managers/123",
      "mileage_units": "miles",
      "currency": "GBP",
      "postcode": "EH3 9QG",
      "type": "UkLimitedCompany",
      "sales_tax_is_value_added": true,
      "first_accounting_year_end": "2014-12-31",
      "cis_enabled": true,
      "sales_tax_registration_number": "5555555555",
      "company_start_date": "2008-01-01",
      "vat_frs_type": "Not on Flat Rate Scheme",
      "initial_vat_basis": "Cash",
      "subdomain": "testcompany",
      "contact_phone": "",
      "sales_tax_name": "VAT",
      "website": "",
      "vat_first_return_period_ends_on": "2014-04-30",
      "address1": "One Edinburgh Quay",
      "address2": "133 Fountainbridge",
      "updated_at": "2018-03-06T16:16:33.000+00:00",
      "contact_email": "maemail@email.com",
      "ec_vat_reporting_enabled": true,
      "company_registration_number": "",
      "town": "Edinburgh",
      "sales_tax_effective_date": "2013-11-01",
      "name": "Test Company",
      "supports_auto_sales_tax_on_purchases": true,
      "url": "https://api.freeagent.com/v2/company",
      "country": "United Kingdom",
      "region": "Anywhere",
      "sales_tax_registration_status": "Registered",
      "initially_on_frs": false,
      "short_date_format": "dd mmm yy",
      "created_at": "2015-01-12T11:45:32.000+00:00",
      "freeagent_start_date": "2008-02-01"
    },
    {
      "locked_attributes": [
        "currency"
      ],
      "sales_tax_rates": [
        "20.0",
        "5.0",
        "0.0"
      ],
      "account_manager": "https://api.freeagent.com/v2/account_managers/123",
      "mileage_units": "miles",
      ...
    }
  ]
}
Show as XML
<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
  <clients type="array">
    <client>
      <url>https://api.freeagent.com/v2/company</url>
      <name>Test Company</name>
      <subdomain>testcompany</subdomain>
      <type>UkLimitedCompany</type>
      <currency>GBP</currency>
      <mileage-units>miles</mileage-units>
      <company-start-date type="date">2008-01-01</company-start-date>
      <freeagent-start-date type="date">2008-02-01</freeagent-start-date>
      <first-accounting-year-end type="date">2014-12-31</first-accounting-year-end>
      <company-registration-number></company-registration-number>
      <sales-tax-registration-status>Registered</sales-tax-registration-status>
      <address1>One Edinburgh Quay</address1>
      <address2>133 Fountainbridge</address2>
      <town>Edinburgh</town>
      <region>Anywhere</region>
      <postcode>EH3 9QG</postcode>
      <country>United Kingdom</country>
      <contact-email>maemail@email.com</contact-email>
      <contact-phone></contact-phone>
      <website></website>
      <short-date-format>dd mmm yy</short-date-format>
      <ec-vat-reporting-enabled type="boolean">true</ec-vat-reporting-enabled>
      <sales-tax-name>VAT</sales-tax-name>
      <sales-tax-registration-number>5555555555</sales-tax-registration-number>
      <sales-tax-effective-date type="date">2013-11-01</sales-tax-effective-date>
      <sales-tax-rates type="array">
        <sales-tax-rate type="decimal">20.0</sales-tax-rate>
        <sales-tax-rate type="decimal">5.0</sales-tax-rate>
        <sales-tax-rate type="decimal">0.0</sales-tax-rate>
      </sales-tax-rates>
      <sales-tax-is-value-added type="boolean">true</sales-tax-is-value-added>
      <supports-auto-sales-tax-on-purchases type="boolean">true</supports-auto-sales-tax-on-purchases>
      <vat-first-return-period-ends-on type="date">2014-04-30</vat-first-return-period-ends-on>
      <initial-vat-basis>Cash</initial-vat-basis>
      <initially-on-frs type="boolean">false</initially-on-frs>
      <cis-enabled type="boolean">true</cis-enabled>
      <locked-attributes type="array">
        <locked-attribute>company_start_date</locked-attribute>
        <locked-attribute>freeagent_start_date</locked-attribute>
        <locked-attribute>trading_start_date</locked-attribute>
        <locked-attribute>currency</locked-attribute>
        <locked-attribute>sales_tax_registration_number</locked-attribute>
        <locked-attribute>sales_tax_effective_date</locked-attribute>
        <locked-attribute>vat_first_return_period_ends_on</locked-attribute>
        <locked-attribute>initial_vat_basis</locked-attribute>
        <locked-attribute>initially_on_frs</locked-attribute>
        <locked-attribute>initial_vat_frs_type</locked-attribute>
      </locked-attributes>
      <created-at type="dateTime">2015-01-12T11:45:32+00:00</created-at>
      <updated-at type="dateTime">2018-03-06T16:16:33+00:00</updated-at>
      <vat-frs-type>Not on Flat Rate Scheme</vat-frs-type>
      <account-manager>https://api.freeagent.com/v2/account_managers/123</account-manager>
    </client>
    <client>
      <url>https://api.freeagent.com/v2/company</url>
      ...
    </company>
</freeagent>
Show as JSON

List account managers

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

Response

Status: 200 OK
{
  "account_managers": [
    {
      "url": "https://api.freeagent.com/v2/account_managers/123",
      "name": "Bobson Dugnutt",
      "email": "bobson@some-accounting-firm.com"
    },
    {
      "url": "https://api.freeagent.com/v2/account_managers/456",
      "name": "Sleve McDichael",
      "email": "sleve@some-accounting-firm.com"
    },
    {
      "url": "https://api.freeagent.com/v2/account_managers/789",
      "name": "Todd Bonzalez",
      "email": "todd@some-accounting-firm.com"
    }
  ]
}
Show as XML
<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
  <account-managers type="array">
    <account-manager>
      <url>https://api.freeagent.com/v2/account_managers/123</url>
      <name>Bobson Dugnutt</name>
      <email>bobson@some-accounting-firm.com</email>
    </account-manager>
    <account-manager>
      <url>https://api.freeagent.com/v2/account_managers/456</url>
      <name>Sleve McDichael</name>
      <email>sleve@some-accounting-firm.com</email>
    </account-manager>
    <account-manager>
      <url>https://api.freeagent.com/v2/account_managers/789</url>
      <name>Todd Bonzalez</name>
      <email>todd@some-accounting-firm.com</email>
    </account-manager>
  </account-managers>
</freeagent>
Show as JSON

Get details of a single account manager

GET https://api.freeagent.com/v2/account_managers/:id

Response

Status: 200 OK
{
  "account_manager": {
    "url": "https://api.freeagent.com/v2/account_managers/123",
    "name": "Bobson Dugnutt",
    "email": "bobson@some-accounting-firm.com"
  }
}
Show as XML
<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
  <account-manager>
    <url>https://api.freeagent.com/v2/account_managers/123</url>
    <name>Bobson Dugnutt</name>
    <email>bobson@some-accounting-firm.com</email>
  </account-manager>
</freeagent>
Show as JSON