Clients


Clients comprise the businesses and people that use the services provided by an accounting firm.

Overview

URL https://api.xero.com/xero.hq/1.0/clients
https://api.xero.com/xero.hq/1.0/clients/events
Methods Supported GET, POST
Description Allows you to retrieve and create clients
Allows you to retrieve client events

GET Clients

The following elements are returned in the clients response

id The client id.
organisationId The xero organisation id. This field is readonly. Its value gets set when a client is connected to a Xero Organisation.
externalIdentifiers Collection of identifiers representing the client in other systems. See externalIdentifiers.
name The name of the client. Max chars: 255.
firstName The first name of the client. Max chars: 255. Person Client only.
lastName The last name of the client. Max chars: 255. Person Client only.
gender The client’s gender. Person Client only. See person gender.
prefix The prefix of a client’s name before their first name. Person Client only.
dateOfBirth The client’s date of birth in ISO 8601 format. Person Client only e.g. 1983-02-20.
placeOfBirth Client’s place of birth. Person Client only. See placeOfBirth.
balanceDate Balance date of the client. Business Client only. See balanceDate.
annualReturnFilingMonth Annual return filing month of the client. Business Client only. e.g. JANUARY.
status The status of the client. See statuses.
businessStructure The structure of the business. Business Client only. See business structures.
avatarUri Signed URL to the client avatar image. This will be valid for 10 minutes.
avatarThumbUri Signed URL to the client thumbnail, This will be valid for 10 minutes.
businessIndentifiers Collection of region specific business identifiers. Business Client only. See businessIdentifiers.
phoneNumbers Collection of client phone numbers. See phoneNumbers.
Elements for externalIdentifiers
id Identifier id
type e.g. WFM_CLIENT_UUID
Elements for placeOfBirth
city The city of birth. Max chars: 255.
country The ISO 3166-1 alpha-2 code and country name.
Elements for balanceDate
day Day of month
month e.g. JUNE
Elements for businessIdentifiers
type See businsess identifier types.
value The business identifier. Max chars: 50.
Elements for phoneNumbers
type See phone number types.
country Country code. Max chars: 20.
area Area code. Max chars: 10.
number The phone number. Max chars: 50.
label The full phone number. This field is read-only.
Elements for Addresses
type See address types.
streetAddress Max chars: 1000.
city Max chars: 255.
region Max chars: 255.
postalCode Max chars: 100.
country The ISO 3166-1 alpha-2 code and country name
emailAddresses Collection of client emails. Each email max chars: 500.
websites Collection of client website links. Each link max chars: 500.

Optional parameters for GET Clients

ids A comma separated list of client ids for clients to return in the collection. Max id's: 30.
organisationID The Xero organisation ID of the client
searchTerm The search term to use to look for in client names. Example: Jo.
page The page number to return, starting from 1. Default: 1.
pagesize The number of items to return per page. Default: 20.
summary Controls the amount of information returned for each client. Default: true.

Example retrieving a summarised collection of clients

GET https://api.xero.com/xero.hq/1.0/clients?page=1&pageSize=20&summary=true
	
{
  "pagination": {
    "page": 1,
    "pageSize": 2,
    "hasMore": true,
    "total": 12
  },
  "items": [
    {
      "id": "1642e064-d3f3-e611-b283-e4a7a0da8cf1",
      "organisationId": "74aff03f-f784-446f-9c8d-5fc079e31bb8",
      "externalidentifiers": [
        {
          "id": "3e39d836-818e-4572-b11b-d91e17d11dca",
          "type": "WFM_CLIENT_UUID"
        }
      ],
      "firstName": "Joe",
      "lastName": "Bloggs",
      "email": "test@test.com",
      "phone": "642212121212",
      "businessStructure": "SOLE_TRADER",
      "status": "ACTIVE"
    },
    {
      "id": "9d575ba1-2861-42c5-842c-37f112161835",
      "organisationId": "594681e0-38dd-4dab-b12a-fc57e246c7d3",
      "externalidentifiers": [
        {
          "id": "f2e45d7c-9bf8-e611-8e10-005056ac7de2",
          "type": "WFM_CLIENT_UUID"
        }
      ],
      "name": "joe's gardening supplies",
      "email": "test@test.com",
      "phone": "642212121212",
      "businessStructure": "COMPANY",
      "status": "ACTIVE"
    }
  ]
}
	

Example retrieving a single business client by id

GET https://api.xero.com/xero.hq/1.0/clients/9d575ba1-2861-42c5-842c-37f112161835
{
  "id": "9d575ba1-2861-42c5-842c-37f112161835",
  "organisationId": "594681e0-38dd-4dab-b12a-fc57e246c7d3",
  "externalidentifiers": [
    {
      "id": "f2e45d7c-9bf8-e611-8e10-005056ac7de2",
      "type": "WFM_CLIENT_UUID"
    }
  ],
  "name": "joe's gardening supplies",
  "balanceDate": {
    "day": 1,
    "month": "JUNE"
  },
  "annualReturnFilingMonth": "JANUARY",
  "status": "ACTIVE",
  "businessStructure": "COMPANY",
  "avatarUri": "https://image-bucket.s3.amazonaws.com/xero.png?AWSAccessKeyId=XXXXXXXXXXTC3DWQ&Expires=1470443460&Signature=TVHMHmP344pt2AS5i4ylXskF7P4%3D",
  "avatarThumbUri": "https://image-bucket.s3.amazonaws.com/xero_thumb.png?AWSAccessKeyId=XXXXXXXXXXTC3DWQ&Expires=1470443460&Signature=TVHMHmP344pt2AS5i4ylXskF7P4%3D",
  "businessIdentifiers": [
    {
      "type": "NZBN",
      "value": "9429034042984"
    }
  ],
  "phoneNumbers": [
    {
      "type": "MOBILE",
      "country": "64",
      "area": "22",
      "number": "12121212",
      "label": "+64 22 12121212"
    }
  ],
  "addresses": [
    {
      "type": "STREET",
      "streetAddress": "12 Main Street",
      "city": "Auckland",
      "region": "Auckland",
      "postalCode": "1234",
      "country": {
        "code": "NZ",
        "name": "New Zealand"
      }
    }
  ],
  "emailAddresses": [
    {
      "email": "test@test.com"
    }
  ],
  "websites": [
    {
      "link": "http://www.xero.com"
    }
  ]
}

Example retrieving a single person client by id

GET https://api.xero.com/xero.hq/1.0/clients/1642e064-d3f3-e611-b283-e4a7a0da8cf1
{
  "id": "1642e064-d3f3-e611-b283-e4a7a0da8cf1",
  "organisationId": "74aff03f-f784-446f-9c8d-5fc079e31bb8",
  "externalidentifiers": [
    {
      "id": "3e39d836-818e-4572-b11b-d91e17d11dca",
      "type": "WFM_CLIENT_UUID"
    }
  ],
  "firstName": "Joe",
  "lastName": "Bloggs",
  "gender": "MALE",
  "prefix": "Mr",
  "dateOfBirth": "1983-02-20",
  "placeOfBirth": {
    "city": "Auckland",
    "country": {
      "code": "NZ",
      "name": "New Zealand"
    }
  },
  "status": "ACTIVE",
  "businessStructure": "SOLE_TRADER",
  "businessIdentifiers": [],
  "avatarUri": "https://image-bucket.s3.amazonaws.com/xero.png?AWSAccessKeyId=XXXXXXXXXXTC3DWQ&Expires=1470443460&Signature=TVHMHmP344pt2AS5i4ylXskF7P4%3D",
  "avatarThumbUri": "https://image-bucket.s3.amazonaws.com/xero_thumb.png?AWSAccessKeyId=XXXXXXXXXXTC3DWQ&Expires=1470443460&Signature=TVHMHmP344pt2AS5i4ylXskF7P4%3D",
  "phoneNumbers": [
    {
      "type": "MOBILE",
      "country": "64",
      "area": "22",
      "number": "12121212",
      "label": "+64 22 12121212"
    }
  ],
  "addresses": [
    {
      "type": "STREET",
      "streetAddress": "12 Main Street",
      "city": "Auckland",
      "region": "Auckland",
      "postalCode": "1234",
      "country": {
        "code": "NZ",
        "name": "New Zealand"
      }
    }
  ],
  "emailAddresses": [
    {
      "email": "test@test.com"
    }
  ],
  "websites": [
    {
      "link": "http://www.xero.com"
    }
  ]
}

GET Client Events

Use this endpoint to retrieve client events.

ids The event id
title The event title
summary The event summary
published Event published datetime (ISO 8601)
updated Datetime for the underlying change (ISO 8601)
category See event categories.
content Event details. See content.
Elements for content
clientId Identifier of the client affected by the change.
organisationId Xero Organisation Id of the organisation connected to the client.
externalIdentifiers Collection of identifiers representing the client in other systems. See externalIdentifiers.

Optional parameters for GET Client Events

afterEvent The event number of the first event in the response. Example: 1. Default: 1.
category Restricts events to the specified category. Example: CLIENT_UPDATED.
clientId Restricts events to those associated with the specified client.
pageSize The page size, max is 1000. Example: 2. Default: 100.

Example response retrieving events

GET https://api.xero.com/xero.hq/1.0/clients/events?afterEvent=1&category=CLIENT_UPDATED&clientId=9d575ba1-2861-42c5-842c-37f112161835&pageSize=2
Content-Type:application/atom+xml

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
    <title type="text">Client Events</title>
    <id>uuid:e57d920d-74ed-47c9-b9cb-e33e4b26acee;id=1</id>
    <updated>2017-05-18T23:13:33Z</updated>
    <author>
        <name>Client Service</name>
    </author>
    <entry>
        <id>1</id>
        <title type="text">``</title>
        <summary type="text">``</summary>
        <published>2017-01-19 23:03:02Z</published>
        <updated>2017-01-19 23:03:02Z</updated>
        <category term="CLIENT_UPDATED" />
        <content type="text">
            {
                "clientId":"9d575ba1-2861-42c5-842c-37f112161835"
            }
        </content>
    </entry>
    <entry>
        <id>2</id>
        <title type="text">``</title>
        <summary type="text">``</summary>
        <published>2017-01-19 23:14:29Z</published>
        <updated>2017-01-19 23:14:29Z</updated>
        <category term="ORGANISATION_CONNECTED" />
        <content type="text">
            {
                "clientId":"9d575ba1-2861-42c5-842c-37f112161835",
                "organisationId":"594681e0-38dd-4dab-b12a-fc57e246c7d3"
            }
        </content>
    </entry>
    <entry>
        <id>3</id>
        <title type="text">``</title>
        <summary type="text">``</summary>
        <published>2017-01-19 23:42:33Z</published>
        <updated>2017-01-19 23:42:33Z</updated>
        <category term="CLIENT_EXTERNALID_UPDATED" />
        <content type="text">
            {
                "clientId":"9d575ba1-2861-42c5-842c-37f112161835",
                "organisationId":"594681e0-38dd-4dab-b12a-fc57e246c7d3",
                "externalidentifiers": [
                    {
                        "id": "f2e45d7c-9bf8-e611-8e10-005056ac7de2",
                        "type": "WFM_CLIENT_UUID"
                    }
                ]
            }
        </content>
    </entry>
    <entry>
        <id>4</id>
        <title type="text">``</title>
        <summary type="text">``</summary>
        <published>2017-01-19 23:55:10Z</published>
        <updated>2017-01-19 23:55:10Z</updated>
        <category term="ORGANISATION_DISCONNECTED" />
        <content type="text">
            {
                "clientId":"9d575ba1-2861-42c5-842c-37f112161835"
            }
        </content>
    </entry>
</feed>