Accounts


Overview

URL https://api.xero.com/api.xro/2.0/Accounts
Methods Supported GET, PUT, POST, DELETE
Description Allows you to create individual accounts in a Xero organisation
Allows you to retrieve the full chart of accounts
Allows you to attach files to an account
Allows you to archive an account
Allows you to update details on an account (except bank accounts)
Allows you to delete an account

Elements for Accounts

The following elements are required for creates and optional for updates
Code Customer defined alpha numeric account code e.g 200 or SALES (max length = 10)
Name Name of account (max length = 150)
Type See Account Types
BankAccountNumber For bank accounts only (Account Type BANK)
The following elements are optional for creates and updates
Status Accounts with a status of ACTIVE can be updated to ARCHIVED. See Account Status Codes
Description Description of the Account. Valid for all types of accounts except bank accounts (max length = 4000)
Tax Type See Tax Types
EnablePaymentsToAccount Boolean – describes whether account can have payments applied to it
ShowInExpenseClaims Boolean – describes whether account code is available for use with expense claims
Elements returned on a GET request only
AccountID Xero identifier
Class See Account Class Types
SystemAccount If this is a system account then this element is returned. See System Account types. Note that non-system accounts may have this element set as either “” or null.
BankAccountType Shown for bank accounts only. See Bank Account types
CurrencyCode Shown for bank accounts only
ReportingCode Shown if set
ReportingCodeName Shown if set
HasAttachments boolean to indicate if an account has an attachment (read only)
UpdatedDateUTC Last modified date UTC format

PUT Accounts

Use this method to create new accounts

Limitations

  • You can only add accounts one at a time (i.e. you’ll need to do multiple API calls to add many accounts)
  • Replacing the entire chart of accounts is not currently supported. See our guide for conversion partners.
  • Creating credit card or Paypal accounts is not currently supported (vote here)

Example for PUT Accounts

1. Below is an example of creating a new sales account with the minimum elements required

<Account>
<Code>201</Code>
<Name>Sales - clearance lines</Name>
<Type>SALES</Type> 
</Account>

2. Below is an example of creating a new asset account with the minimum elements required

<Account>
<Code>304</Code>
<Name>Clearing - EFTPOS</Name>
<Type>ASSET</Type> 
</Account>

3. Below is an example of creating a new bank account with the minimum elements required. (Note the bank account below is an AU account. )

<Account>
<Name>Cheque Account</Name>
<Type>BANK</Type>
<BankAccountNumber>121-121-1234567</BankAccountNumber>
</Account>

Uploading an Attachment

You can upload up to 10 attachments(each up to 3mb in size) per account, once the account has been created in Xero. To do this you’ll need to know the ID of the account which you’ll use to construct the URL when POST/PUTing a byte stream containing the attachment file. e.g. https://api.xero.com/api.xro/2.0/Accounts/f0ec0d8c-6fce-4330-bb3b-8306278c6fd8/Attachments/image.png. See the Attachments page for more details.

e.g.

POST /api.xro/2.0/Accounts/f0ec0d8c-4330-bb3b-83062c6fd8/Attachments/Image002932.png
Authorization: OAuth...
Content Type: image/png
Content-Length: 10293

{RAW-IMAGE-CONTENT}

POST Accounts

Update Accounts

Use this method to update account details.

Limitations

  • Accounts of type ‘BANK’ cannot be updated (vote here)
  • You can only update accounts one at a time (i.e. you’ll need to do multiple API calls to update many accounts)
  • You cannot update the status to archived (see below) when also updating other values

Example request for updating an Account

<Accounts>
 	<Account>
 	 	<AccountID>297c2dc5-cc47-4afd-8ec8-74990b8761e9</AccountID>
 	 	<Code>200</Code>
 	 	<Name>Sales account</Name>
 	 	<Type>REVENUE</Type>
 	 	<TaxType>OUTPUT2</TaxType>
 	 	<Description>Income from any normal business trading activity</Description>
 	 	<EnablePaymentsToAccount>false</EnablePaymentsToAccount>
 	 	<ShowInExpenseClaims>false</ShowInExpenseClaims>
 	</Account>
</Accounts>

Archive Accounts

Use this method to archive accounts.

Example request for archiving an Account

<Accounts>
 	<Account>
 	 	<AccountID>297c2dc5-cc47-4afd-8ec8-74990b8761e9</AccountID>
 	 	<Status>ARCHIVED</Status>
 	</Account>
</Accounts>

GET Accounts

Optional parameters for GET Accounts

AccountID The Xero identifier for an account – specified as a string following the endpoint name
e.g. /297c2dc5-cc47-4afd-8ec8-74990b8761e9
Modified After The ModifiedAfter filter is actually an HTTP header: ‘If-Modified-Since‘.
A UTC timestamp (yyyy-mm-ddThh:mm:ss) . Only accounts created or modified since this timestamp will be returned e.g. 2009-11-12T00:00:00
Where Filter by an any element (see Filters)
order Order by any element returned (see Order By)

Example response for GET Accounts

<Accounts>
 	<Account>
 	 	<AccountID>297c2dc5-cc47-4afd-8ec8-74990b8761e9</AccountID>
 	 	<Code/>
 	 	<Name>BNZ Cheque Account</Name>
 	 	<Type>BANK</Type>
 	 	<TaxType>NONE</TaxType>
  		<EnablePaymentsToAccount>false</EnablePaymentsToAccount>
                <BankAccountNumber>3809087654321500</BankAccountNumber>
                <BankAccountType>BANK</BankAccountType>
                <CurrencyCode>NZD</CurrencyCode>
 	</Account>
 	<Account>
  		<AccountID>5040915e-8ce7-4177-8d08-fde416232f18</AccountID>
 	 	<Code>200</Code>
 	 	<Name>Sales</Name>
 	 	<Type>REVENUE</Type>
  	        <TaxType>OUTPUT</TaxType>
 	 	<Description>Income from any normal business activity</Description>
 	 	<EnablePaymentsToAccount>false</EnablePaymentsToAccount>
 	</Account>
</Accounts>

Example response for GET Accounts/297c2dc5-cc47-4afd-8ec8-74990b8761e9

(an AccountID identifier following the endpoint name)

<Accounts>
    <Account>
        <AccountID>297c2dc5-cc47-4afd-8ec8-74990b8761e9</AccountID>
        <Code/>
        <Name>BNZ Cheque Account</Name>
        <Type>BANK</Type>
        <TaxType>NONE</TaxType>
        <EnablePaymentsToAccount>false</EnablePaymentsToAccount>
                <BankAccountNumber>3809087654321500</BankAccountNumber>
                <BankAccountType>BANK</BankAccountType>
                <CurrencyCode>NZD</CurrencyCode>
    </Account>
</Accounts>

DELETE Accounts

Non-system accounts and accounts not used on transactions can be deleted using the delete method. If an account is not able to be deleted you can update the status to ARCHIVED

DELETE /Accounts/{AccountID}