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

To use the FreeAgent API for accountancy practices, with the Google OAuth 2.0 Playground, you must do the following:

  1. Contact the integrations team (integrationsrequests@freeagent.com) for a free temporary FreeAgent Practice Dashboard account on our sandbox. We'll link the OAuth Playground to this FreeAgent account.
  2. Sign into the practice and complete the setup stages, including creating a new client to test against.
  3. Create an App at the FreeAgent Developer Dashboard, checking the "Enable Accountancy Practice API" option. You can do this when creating the app in the first place or otherwise from the edit app page.
  4. Once created, take note of the OAuth identifier and OAuth secret.
  5. Finally, it's time to get an Access Token which can then be used with the OAuth Playground, curl or your own apps during development. You can follow the steps in the company quick start.

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

Input

View Filters

GET https://api.freeagent.com/v2/clients?view=active
  • all: Show all clients accessible to the authenticated account manager (default).
  • active: Show only active practice clients.
  • inactive: Show only inactive practice clients.
  • closed: Show only closed practice clients.
  • practice: Show all practice-managed clients, regardless of their status. Exclude linked and CoPilot clients.
  • linked: Show only linked clients.
  • copilot: Show only CoPilot clients.
  • demo: Show only demo clients.

Sort Orders

GET https://api.freeagent.com/v2/clients?sort=created_at
  • created_at: Sort by the time the client was created (default).
  • updated_at: Sort by the time the client was last updated.

To sort in descending order, the sort parameter can be prefixed with a hyphen.

GET https://api.freeagent.com/v2/clients?sort=-created_at

Date Filters

GET https://api.freeagent.com/v2/clients?from_date=2020-01-01&to_date=2021-03-31

GET https://api.freeagent.com/v2/clients?updated_since=2021-05-22T09:00:00.000Z
  • from_date
  • to_date
  • updated_since

Response

Status: 200 OK

{
  "clients": [
    {
      "account_manager": "https://api.freeagent.com/v2/account_managers/123",
      "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": "",
      "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",
      "url": "https://api.freeagent.com/v2/company",
      "country": "United Kingdom",
      "region": "Anywhere",
      "sales_tax_registration_status": "Registered",
      "created_at": "2015-01-12T11:45:32.000+00:00",
      "freeagent_start_date": "2008-02-01",
      "status": "Active Licence",
      "account_owner": {
                "first_name": "Jane",
                "last_name": "Smith",
                "last_logged_in_at": "2023-09-21T10:32:02.000+01:00"
                }
    },
    {
      "account_manager": "https://api.freeagent.com/v2/account_managers/123",
      ...
    }
  ]
}
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>
      <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>
      <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-is-value-added type="boolean">true</sales-tax-is-value-added>
      <initial-vat-basis>Cash</initial-vat-basis>
      <cis-enabled type="boolean">true</cis-enabled>
      <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>
      <status>Active Licence</status>
      <account-owner>
        <first-name>Jane</first-name>
        <last-name>Smith</last-name>
        <last-logged-in-at type="dateTime">2023-09-21T10:32:02+01:00</last-logged-on-at>
      </account-owner>
    </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

Get details of accountancy practice

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

{
    "name": "My Practice",
    "subdomain": "mypracticesubdomain"
}
Show as XML
<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
    <name>My Practice</name>
    <subdomain>mypracticesubdomain</subdomain>
</freeagent>
Show as JSON