Contacts

Minimum access level: Time, unless stated otherwise.

Attributes

Required Attribute Description Kind
url The unique identifier for the contact URI
? first_name

First name

Required if organisation_name is not specified
String
? last_name

Last name

Required if organisation_name is not specified
String
? organisation_name

Organisation name

Required if first_name and last_name are not specified
String
active_projects_count Numer of active projects belonging to the contact String
direct_debit_mandate_state

Included if the contact has a current pre-authorised GoCardless Direct Debit agreement.

  • setup: the agreement has been created in the FreeAgent UI and the email is to be sent to the customer
  • pending: the customer has been sent the mandate email
  • inactive: the customer has completed the mandate agreement and we are waiting on confirmation from GoCardless
  • active: GoCardless have confirmed the mandate and it is now usable
  • failed: agreement failed, the customer's details were rejected by GoCardless (or the Bank) as invalid
  • cancelled: agreement cancelled, through the FreeAgent UI or at GoCardless
  • expired: expired when no collection attempts have been made before a dormancy period was reached (13 months)
String
created_at Creation of the contact resource (UTC) Timestamp
updated_at When the contact resource was last updated (UTC) Timestamp
Additional attributes available to users with Contacts & Projects permission
email

Email

Max 2 addresses can be entered during free trial
String
billing_email

Billing Email

Max 2 addresses can be entered during free trial
phone_number Telephone String
mobile Mobile number String
address1 First line of the address String
address2 Second line of the address String
address3 Third line of the address String
town Town String
region Region or State String
postcode Post / Zip Code String
country Country String
uses_contact_invoice_sequence

true if using contact-level invoice sequence, false otherwise

Can be overridden by project-level sequences
Boolean
contact_name_on_invoices true if invoices should show the contact name as well as an organization name, false otherwise Boolean
charge_sales_tax One of the following:

  • Auto (default)
  • Always
  • Never

String
sales_tax_registration_number If applicable, and needing to be displayed on invoices. Also required if EC Sales of Goods or Services to this contact need to be reported. String
status One of the following:

  • Active
  • Hidden

String
locale Invoice / Estimate language String

List all contacts

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

Input

View Filters

GET https://api.freeagent.com/v2/contacts?view=active
  • all: Show all contacts.
  • active: Show only active contacts (default).
  • clients: Show all clients.
  • suppliers: Show only active suppliers.
  • active_projects: Show only clients with active projects.
  • completed_projects: Show only clients with completed invoices.
  • open_clients: Show only clients with open invoices.
  • open_suppliers: Show only suppliers with open bills.
  • hidden: Show only hidden contacts.

Sort Orders

GET https://api.freeagent.com/v2/contacts?sort=updated_at
  • name: Sort by the concatenation of organisation_name, last_name and first_name (default).
  • created_at: Sort by the time the contact was created.
  • updated_at: Sort by the time the contact was last modified.

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

GET https://api.freeagent.com/v2/contacts?sort=-updated_at

Response

Status: 200 OK
{ "contacts":[
  {
    "url":"https://api.freeagent.com/v2/contacts/2",
    "first_name":"test",
    "last_name":"me",
    "organisation_name":"Acme Ltd",
    "email":"test@example.com",
    "billing_email":"billing@example.com",
    "phone_number":"12345678",
    "mobile":"9876543210",
    "address1":"11 George Street",
    "address2": "South Court",
    "address3": "Flat 6",
    "town":"London",
    "region": "Southwark",
    "postcode":"SE1 6HA",
    "country":"United Kingdom",
    "contact_name_on_invoices":true,
    "locale":"en",
    "account_balance":"-100.0",
    "uses_contact_invoice_sequence":false,
    "charge_sales_tax":"Auto",
    "sales_tax_registration_number":"ST12345",
    "active_projects_count":1,
    "direct_debit_mandate_state":"active",
    "status":"Active",
    "created_at":"2011-09-14T16:00:41Z",
    "updated_at":"2011-09-16T09:34:41Z"
  }
]}
Show as XML
<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
  <contacts type="array">
    <contact>
      <url>https://api.freeagent.com/v2/contacts/2</url>
      <first-name>test</first-name>
      <last-name>me</last-name>
      <organisation-name>Acme Ltd</organisation-name>
      <email>test@example.com</email>
      <billing-email>billing@example.com</billing-email>
      <phone-number>12345678</phone-number>
      <mobile>9876543210</mobile>
      <address1>11 George Street</address1>
      <address2>South Court</address2>
      <address3>Flat 6</address3>
      <town>London</town>
      <region>Southwark</region>
      <postcode>SE1 6HA</postcode>
      <country>United Kingdom</country>
      <contact-name-on-invoices type="boolean">true</contact-name-on-invoices>
      <locale>en</locale>
      <account-balance type="decimal">-100.0</account-balance>
      <uses-contact-invoice-sequence type="boolean">false</uses-contact-invoice-sequence>
      <charge-sales-tax>Auto</charge-sales-tax>
      <sales-tax-registration-number>ST12345</sales-tax-registration-number>
      <active-projects-count type="integer">1</active-projects-count>
      <direct-debit-mandate-state>active</direct-debit-mandate-state>
      <status>Active</status>
      <created-at type="datetime">2011-09-14T16:00:41Z</created-at>
      <updated-at type="datetime">2011-09-16T09:34:41Z</updated-at>
    </contact>
  </contacts>
</freeagent>
Show as JSON

Get a single contact

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

Response

Status: 200 OK
{"contact":
  {
    "url":"https://api.freeagent.com/v2/contacts/2",
    "first_name":"test",
    "last_name":"me",
    "organisation_name":"Acme Ltd",
    "email":"test@example.com",
    "billing_email":"billing@example.com",
    "phone_number":"12345678",
    "mobile":"9876543210",
    "address1":"11 George Street",
    "address2": "South Court",
    "address3": "Flat 6",
    "town":"London",
    "region": "Southwark",
    "postcode":"SE1 6HA",
    "country":"United Kingdom",
    "contact_name_on_invoices":true,
    "locale":"en",
    "account_balance":"-100.0",
    "uses_contact_invoice_sequence":false,
    "charge_sales_tax":"Auto",
    "sales_tax_registration_number":"ST12345",
    "active_projects_count":1,
    "direct_debit_mandate_state":"active",
    "status":"Active",
    "created_at":"2011-09-14T16:00:41Z",
    "updated_at":"2011-09-16T09:34:41Z"
  }
}
Show as XML
<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
  <contact>
    <url>https://api.freeagent.com/v2/contacts/2</url>
    <first-name>test</first-name>
    <last-name>me</last-name>
    <organisation-name>Acme Ltd</organisation-name>
    <email>test@example.com</email>
    <billing-email>billing@example.com</billing-email>
    <phone-number>12345678</phone-number>
    <mobile>9876543210</mobile>
    <address1>11 George Street</address1>
    <address2>South Court</address2>
    <address3>Flat 6</address3>
    <town>London</town>
    <region>Southwark</region>
    <postcode>SE1 6HA</postcode>
    <country>United Kingdom</country>
    <contact-name-on-invoices type="boolean">true</contact-name-on-invoices>
    <locale>en</locale>
    <account-balance type="decimal">-100.0</account-balance>
    <uses-contact-invoice-sequence type="boolean">false</uses-contact-invoice-sequence>
    <charge-sales-tax>Auto</charge-sales-tax>
    <sales-tax-registration-number>ST12345</sales-tax-registration-number>
    <active-projects-count type="integer">1</active-projects-count>
    <direct-debit-mandate-state>active</direct-debit-mandate-state>
    <direct-debit-mandate>
      <currency>GBP</currency>
      <max-amount type="decimal">5000.0</max-amount>
      <remaining-amount type="decimal">5000.0</remaining-amount>
      <next-interval-starts-on type="date">2017-06-30</next-interval-starts-on>
    </direct-debit-mandate>
    <status>Active</status>
    <created-at type="datetime">2011-09-14T16:00:41Z</created-at>
    <updated-at type="datetime">2011-09-16T09:34:41Z</updated-at>
  </contact>
</freeagent>
Show as JSON

Create a contact

POST https://api.freeagent.com/v2/contacts

Payload should have a root contact element, containing elements listed under Attributes.

Response

Status: 201 Created
Location: https://api.freeagent.com/v2/contacts/70
{ "contact":
  {
    "url":"https://api.freeagent.com/v2/contacts/70",
    "first_name":"test",
    "last_name":"me",
    "organisation_name":"Acme Ltd",
    "email":"test@example.com",
    "billing_email":"billing@example.com",
    "phone_number":"12345678",
    "mobile":"9876543210",
    "address1":"11 George Street",
    "address2": "Kings Court",
    "address3": "Flat 6",
    "town":"London",
    "region": "Southwark",
    "postcode":"SE1 6HA",
    "country":"United Kingdom",
    "contact_name_on_invoices":true,
    "locale":"en",
    "account_balance":"-100.0",
    "uses_contact_invoice_sequence":false,
    "charge_sales_tax":"Auto",
    "sales_tax_registration_number":"ST12345",
    "active_projects_count":0,
    "status":"Active",
    "created_at":"2011-09-14T16:00:41Z",
    "updated_at":"2011-09-16T09:34:41Z"
  }
}
Show as XML
<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
  <contact>
    <url>https://api.freeagent.com/v2/contacts/70</url>
    <first-name>test</first-name>
    <last-name>me</last-name>
    <organisation-name>Acme Ltd</organisation-name>
    <email>test@example.com</email>
    <billing-email>billing@example.com</billing-email>
    <phone-number>12345678</phone-number>
    <mobile>9876543210</mobile>
    <address1>11 George Street</address1>
    <address2>South Court</address2>
    <address3>Flat 6</address3>
    <town>London</town>
    <region>Southwark</region>
    <postcode>SE1 6HA</postcode>
    <country>United Kingdom</country>
    <contact-name-on-invoices type="boolean">true</contact-name-on-invoices>
    <locale>en</locale>
    <account-balance type="decimal">-100.0</account-balance>
    <uses-contact-invoice-sequence type="boolean">false</uses-contact-invoice-sequence>
    <charge-sales-tax>Auto</charge-sales-tax>
    <sales-tax-registration-number>ST12345</sales-tax-registration-number>
    <active-projects-count type="integer">0</active-projects-count>
    <status>Active</status>
    <created-at type="datetime">2011-09-14T16:00:41Z</created-at>
    <updated-at type="datetime">2011-09-16T09:34:41Z</updated-at>
  </contact>
</freeagent>
Show as JSON

Update a contact

PUT https://api.freeagent.com/v2/contacts/:id

Payload should have a root contact element, containing elements listed under Attributes that should be updated.

Response

Status: 200 OK

Delete a contact

DELETE https://api.freeagent.com/v2/contacts/:id

Response

Status: 200 OK