Xero Finance API

Finance

getAccountingActivityAccountUsage

Get account usage

A summary of how each account is being transacted on exposing the level of detail and amounts attributable to manual adjustments.


/AccountingActivities/AccountUsage

Usage and SDK Samples

import org.openapitools.client.api.*;
import org.openapitools.client.api.client.FinanceApi;
import org.openapitools.client.models.finance.*;

import java.io.File;
import java.util.*;

public class FinanceApiExample {
    private FinanceApi apiInstance;
    
    public static void main(String[] args) {
        String accessToken = "YOUR_ACCESS_TOKEN";
        ApiClient defaultClient = new ApiClient();

        apiInstance = AccountingApi.getInstance(defaultClient);
        String xeroTenantId = 'YOUR_XERO_TENANT_ID';
        String startMonth = '2020-09';
        String endMonth = '2021-09';

        try {
            AccountUsageResponse result = apiInstance.getAccountingActivityAccountUsage(accessToken, xeroTenantId, startMonth, endMonth);
            System.out.println(result);
        } catch (XeroException e) {
            System.err.println("Exception when calling FinanceApi#getAccountingActivityAccountUsage");
            e.printStackTrace();
        }
    }
}

Scopes

finance.accountingactivity.read Grant read-only access to Xero usage activity

Parameters

Header parameters
Name Description
xero-tenant-id*
String
Xero identifier for Tenant
Required
Query parameters
Name Description
startMonth
String

date, yyyy-MM

If no parameter is provided, the month 12 months prior to the end month will be used.

Account usage for up to 12 months from this date will be returned.
endMonth
String

date, yyyy-MM

If no parameter is provided, the current month will be used.

Account usage for up to 12 months prior to this date will be returned.

getAccountingActivityLockHistory

Get lock history

Provides a history of locking of accounting books. Locking may be an indicator of good accounting practices that could reduce the risk of changes to accounting records in prior periods.


/AccountingActivities/LockHistory

Usage and SDK Samples

import org.openapitools.client.api.*;
import org.openapitools.client.api.client.FinanceApi;
import org.openapitools.client.models.finance.*;

import java.io.File;
import java.util.*;

public class FinanceApiExample {
    private FinanceApi apiInstance;
    
    public static void main(String[] args) {
        String accessToken = "YOUR_ACCESS_TOKEN";
        ApiClient defaultClient = new ApiClient();

        apiInstance = AccountingApi.getInstance(defaultClient);
        String xeroTenantId = 'YOUR_XERO_TENANT_ID';
        String endDate = '2021-09-15';

        try {
            LockHistoryResponse result = apiInstance.getAccountingActivityLockHistory(accessToken, xeroTenantId, endDate);
            System.out.println(result);
        } catch (XeroException e) {
            System.err.println("Exception when calling FinanceApi#getAccountingActivityLockHistory");
            e.printStackTrace();
        }
    }
}

Scopes

finance.accountingactivity.read Grant read-only access to Xero usage activity

Parameters

Header parameters
Name Description
xero-tenant-id*
String
Xero identifier for Tenant
Required
Query parameters
Name Description
endDate
String

date, yyyy-MM-dd

If no parameter is provided, the current date will be used.

Any changes to hard or soft lock dates that were made within the period up to 12 months before this date will be returned.

Please be aware that there may be a delay of up to 3 days before a change is visible from this API.

getAccountingActivityReportHistory

Get report history

For a specified organisation, provides a summary of all the reports published within a given period, which may be an indicator for good business management and oversight.


/AccountingActivities/ReportHistory

Usage and SDK Samples

import org.openapitools.client.api.*;
import org.openapitools.client.api.client.FinanceApi;
import org.openapitools.client.models.finance.*;

import java.io.File;
import java.util.*;

public class FinanceApiExample {
    private FinanceApi apiInstance;
    
    public static void main(String[] args) {
        String accessToken = "YOUR_ACCESS_TOKEN";
        ApiClient defaultClient = new ApiClient();

        apiInstance = AccountingApi.getInstance(defaultClient);
        String xeroTenantId = 'YOUR_XERO_TENANT_ID';
        String endDate = '2021-09-15';

        try {
            ReportHistoryResponse result = apiInstance.getAccountingActivityReportHistory(accessToken, xeroTenantId, endDate);
            System.out.println(result);
        } catch (XeroException e) {
            System.err.println("Exception when calling FinanceApi#getAccountingActivityReportHistory");
            e.printStackTrace();
        }
    }
}

Scopes

finance.accountingactivity.read Grant read-only access to Xero usage activity

Parameters

Header parameters
Name Description
xero-tenant-id*
String
Xero identifier for Tenant
Required
Query parameters
Name Description
endDate
String

date, yyyy-MM-dd

If no parameter is provided, the current date will be used.

Any reports that were published within the period up to 12 months before this date will be returned.

Please be aware that there may be a delay of up to 3 days before a published report is visible from this API.

getAccountingActivityUserActivities

Get user activities

For a specified organisation, provides a list of all the users registered, and a history of their accounting transactions. Also identifies the existence of an external accounting advisor and the level of interaction.


/AccountingActivities/UserActivities

Usage and SDK Samples

import org.openapitools.client.api.*;
import org.openapitools.client.api.client.FinanceApi;
import org.openapitools.client.models.finance.*;

import java.io.File;
import java.util.*;

public class FinanceApiExample {
    private FinanceApi apiInstance;
    
    public static void main(String[] args) {
        String accessToken = "YOUR_ACCESS_TOKEN";
        ApiClient defaultClient = new ApiClient();

        apiInstance = AccountingApi.getInstance(defaultClient);
        String xeroTenantId = 'YOUR_XERO_TENANT_ID';
        String dataMonth = '2021-09';

        try {
            UserActivitiesResponse result = apiInstance.getAccountingActivityUserActivities(accessToken, xeroTenantId, dataMonth);
            System.out.println(result);
        } catch (XeroException e) {
            System.err.println("Exception when calling FinanceApi#getAccountingActivityUserActivities");
            e.printStackTrace();
        }
    }
}

Scopes

finance.accountingactivity.read Grant read-only access to Xero usage activity

Parameters

Header parameters
Name Description
xero-tenant-id*
String
Xero identifier for Tenant
Required
Query parameters
Name Description
dataMonth
String

date, yyyy-MM

The specified month must be complete (in the past); The current month cannot be specified since it is not complete.

If no parameter is provided, the month immediately previous to the current month will be used.

Any user activities occurring within the specified month will be returned.

Please be aware that there may be a delay of up to 3 days before a user activity is visible from this API.

getBankStatementAccounting

Get Bank Statement Accounting

For lenders that prefer using bank statement data as the source of truth. We provide a data point that will allow access to customer bank statements, plus for reconciled bank transactions the matching accounting, invoice and billing data as well. As customers reconcile bank statements to invoices and bills, this transaction detail will provide valuable insight for lender's assessment measures.


/BankStatementsPlus/statements

Usage and SDK Samples

import org.openapitools.client.api.*;
import org.openapitools.client.api.client.FinanceApi;
import org.openapitools.client.models.finance.*;

import java.io.File;
import java.util.*;

public class FinanceApiExample {
    private FinanceApi apiInstance;
    
    public static void main(String[] args) {
        String accessToken = "YOUR_ACCESS_TOKEN";
        ApiClient defaultClient = new ApiClient();

        apiInstance = AccountingApi.getInstance(defaultClient);
        String xeroTenantId = 'YOUR_XERO_TENANT_ID';
        UUID bankAccountID = UUID.fromString("38400000-8cf0-11bd-b23e-10b96e4ef00d");
        UUID bankAccountID = '38400000-8cf0-11bd-b23e-10b96e4ef00d';
        String fromDate = '2020-07-01';
        String toDate = '2021-06-30';
        Boolean summaryOnly = true;

        try {
            BankStatementAccountingResponse result = apiInstance.getBankStatementAccounting(accessToken, xeroTenantId, bankAccountID, fromDate, toDate, summaryOnly);
            System.out.println(result);
        } catch (XeroException e) {
            System.err.println("Exception when calling FinanceApi#getBankStatementAccounting");
            e.printStackTrace();
        }
    }
}

Scopes

finance.bankstatementsplus.read Grant read-only access to bank statements accounting data

Parameters

Header parameters
Name Description
xero-tenant-id*
String
Xero identifier for Tenant
Required
Query parameters
Name Description
BankAccountID*
UUID (uuid)

string, GUID

Bank account Id

Required
FromDate*
String

date, yyyy-MM-dd

Specifies the start date of the query period. The maximum range of the query period is 12 months. If the specified query period is more than 12 months the request will be rejected.

Required
ToDate*
String

date, yyyy-MM-dd

Specifies the end date of the query period. If the end date is a future date, the request will be rejected.

Required
SummaryOnly
Boolean

boolean, true/false

The default value is true if no parameter is provided.

In summary mode, the response will exclude the computation-heavy LineItems fields from bank transaction, invoice, credit note, prepayment and overpayment data, making the API calls quicker and more efficient.

getCashValidation

Get cash validation

Summarizes the total cash position for each account for an org


/CashValidation

Usage and SDK Samples

import org.openapitools.client.api.*;
import org.openapitools.client.api.client.FinanceApi;
import org.openapitools.client.models.finance.*;

import java.io.File;
import java.util.*;

public class FinanceApiExample {
    private FinanceApi apiInstance;
    
    public static void main(String[] args) {
        String accessToken = "YOUR_ACCESS_TOKEN";
        ApiClient defaultClient = new ApiClient();

        apiInstance = AccountingApi.getInstance(defaultClient);
        String xeroTenantId = 'YOUR_XERO_TENANT_ID';
        String balanceDate = '2021-09-15';
        String asAtSystemDate = '2021-09-15';
        String beginDate = '2021-09-15';

        try {
            array[CashValidationResponse] result = apiInstance.getCashValidation(accessToken, xeroTenantId, balanceDate, asAtSystemDate, beginDate);
            System.out.println(result);
        } catch (XeroException e) {
            System.err.println("Exception when calling FinanceApi#getCashValidation");
            e.printStackTrace();
        }
    }
}

Scopes

finance.cashvalidation.read Grant read-only access to bank statement and reconcilation data

Parameters

Header parameters
Name Description
xero-tenant-id*
String
Xero identifier for Tenant
Required
Query parameters
Name Description
balanceDate
String

date, yyyy-MM-dd

If no parameter is provided, the current date will be used.

The ‘balance date’ will return transactions based on the accounting date entered by the user. Transactions before the balanceDate will be included. The user has discretion as to which accounting period the transaction relates to.

The ‘balance date’ will control the latest maximum date of transactions included in the aggregate numbers. Balance date does not affect the CurrentStatement object, as this will always return the most recent statement before asAtSystemDate (if specified)
asAtSystemDate
String

date, yyyy-MM-dd

If no parameter is provided, the current date will be used.

The ‘as at’ date will return transactions based on the creation date. It reflects the date the transactions were entered into Xero, not the accounting date. The ‘as at’ date can not be overridden by the user. This can be used to estimate a ‘historical frequency of reconciliation’.

The ‘as at’ date will affect the current statement in the response, as any candidate statements created after this date will be filtered out. Thus the current statement returned will be the most recent statement prior to the specified ‘as at’ date. Be aware that neither the begin date, nor the balance date, will affect the current statement.

Note; information is only presented when system architecture allows, meaning historical cash validation information will be an estimate. In addition, delete events are not aware of the ‘as at’ functionality in this endpoint, meaning that transactions deleted at the time the API is accessed will be considered to always have been deleted.
beginDate
String

date, yyyy-MM-dd

If no parameter is provided, the aggregate results will be drawn from the user’s total history.

The ‘begin date’ will return transactions based on the accounting date entered by the user. Transactions after the beginDate will be included. The user has discretion as to which accounting period the transaction relates to.

getFinancialStatementBalanceSheet

Get Balance Sheet report

The balance sheet report is a standard financial report which describes the financial position of an organisation at a point in time.


/FinancialStatements/BalanceSheet

Usage and SDK Samples

import org.openapitools.client.api.*;
import org.openapitools.client.api.client.FinanceApi;
import org.openapitools.client.models.finance.*;

import java.io.File;
import java.util.*;

public class FinanceApiExample {
    private FinanceApi apiInstance;
    
    public static void main(String[] args) {
        String accessToken = "YOUR_ACCESS_TOKEN";
        ApiClient defaultClient = new ApiClient();

        apiInstance = AccountingApi.getInstance(defaultClient);
        String xeroTenantId = 'YOUR_XERO_TENANT_ID';
        String balanceDate = '2020-06-30';

        try {
            BalanceSheetResponse result = apiInstance.getFinancialStatementBalanceSheet(accessToken, xeroTenantId, balanceDate);
            System.out.println(result);
        } catch (XeroException e) {
            System.err.println("Exception when calling FinanceApi#getFinancialStatementBalanceSheet");
            e.printStackTrace();
        }
    }
}

Scopes

finance.statements.read Grant read-only access to finacial statements

Parameters

Header parameters
Name Description
xero-tenant-id*
String
Xero identifier for Tenant
Required
Query parameters
Name Description
balanceDate
String

Specifies the date for balance sheet report.

Format yyyy-MM-dd. If no parameter is provided, the current date will be used.

getFinancialStatementCashflow

Get Cash flow report

The statement of cash flows - direct method, provides the year to date changes in operating, financing and investing cash flow activities for an organisation. Cashflow statement is not available in US region at this stage.


/FinancialStatements/Cashflow

Usage and SDK Samples

import org.openapitools.client.api.*;
import org.openapitools.client.api.client.FinanceApi;
import org.openapitools.client.models.finance.*;

import java.io.File;
import java.util.*;

public class FinanceApiExample {
    private FinanceApi apiInstance;
    
    public static void main(String[] args) {
        String accessToken = "YOUR_ACCESS_TOKEN";
        ApiClient defaultClient = new ApiClient();

        apiInstance = AccountingApi.getInstance(defaultClient);
        String xeroTenantId = 'YOUR_XERO_TENANT_ID';
        String startDate = '2020-09-15';
        String endDate = '2021-09-15';

        try {
            CashflowResponse result = apiInstance.getFinancialStatementCashflow(accessToken, xeroTenantId, startDate, endDate);
            System.out.println(result);
        } catch (XeroException e) {
            System.err.println("Exception when calling FinanceApi#getFinancialStatementCashflow");
            e.printStackTrace();
        }
    }
}

Scopes

finance.statements.read Grant read-only access to finacial statements

Parameters

Header parameters
Name Description
xero-tenant-id*
String
Xero identifier for Tenant
Required
Query parameters
Name Description
startDate
String

Date e.g. yyyy-MM-dd

Specifies the start date for cash flow report.

If no parameter is provided, the date of 12 months before the end date will be used.
endDate
String

Date e.g. yyyy-MM-dd

Specifies the end date for cash flow report.

If no parameter is provided, the current date will be used.

getFinancialStatementContactsExpense

Get expense by contacts report

The expense by contact report provides a year to date profit and loss for customers and suppliers for a given organisation, including detailed contact information.


/FinancialStatements/contacts/expense

Usage and SDK Samples

import org.openapitools.client.api.*;
import org.openapitools.client.api.client.FinanceApi;
import org.openapitools.client.models.finance.*;

import java.io.File;
import java.util.*;

public class FinanceApiExample {
    private FinanceApi apiInstance;
    
    public static void main(String[] args) {
        String accessToken = "YOUR_ACCESS_TOKEN";
        ApiClient defaultClient = new ApiClient();

        apiInstance = AccountingApi.getInstance(defaultClient);
        String xeroTenantId = 'YOUR_XERO_TENANT_ID';
        array[UUID] contactIds = ["00000000-0000-0000-0000-000000000000","00000000-0000-0000-0000-000000000000"];
        Boolean includeManualJournals = true;
        String startDate = '2020-09-15';
        String endDate = '2020-09-15';

        try {
            IncomeByContactResponse result = apiInstance.getFinancialStatementContactsExpense(accessToken, xeroTenantId, contactIds, includeManualJournals, startDate, endDate);
            System.out.println(result);
        } catch (XeroException e) {
            System.err.println("Exception when calling FinanceApi#getFinancialStatementContactsExpense");
            e.printStackTrace();
        }
    }
}

Scopes

finance.statements.read Grant read-only access to finacial statements

Parameters

Header parameters
Name Description
xero-tenant-id*
String
Xero identifier for Tenant
Required
Query parameters
Name Description
contactIds
array[UUID] (uuid)

Specifies the customer contacts to be included in the report.

If no parameter is provided, all customer contacts will be included
includeManualJournals
Boolean

Specifies whether to include the manual journals in the report.

If no parameter is provided, manual journals will not be included.
startDate
String

Date yyyy-MM-dd

Specifies the start date for the report.

If no parameter is provided, the date of 12 months before the end date will be used.

It is recommended to always specify both a start date and end date; While the initial range may be set to 12 months, this may need to be reduced for high volume organisations in order to improve latency.
endDate
String

Date yyyy-MM-dd

Specifies the end date for the report.

If no parameter is provided, the current date will be used.

It is recommended to always specify both a start date and end date; While the initial range may be set to 12 months, this may need to be reduced for high volume organisations in order to improve latency.

getFinancialStatementContactsRevenue

Get revenue by contacts report

The revenue by contact report provides a year to date profit and loss for customers and suppliers for a given organisation, including detailed contact information.


/FinancialStatements/contacts/revenue

Usage and SDK Samples

import org.openapitools.client.api.*;
import org.openapitools.client.api.client.FinanceApi;
import org.openapitools.client.models.finance.*;

import java.io.File;
import java.util.*;

public class FinanceApiExample {
    private FinanceApi apiInstance;
    
    public static void main(String[] args) {
        String accessToken = "YOUR_ACCESS_TOKEN";
        ApiClient defaultClient = new ApiClient();

        apiInstance = AccountingApi.getInstance(defaultClient);
        String xeroTenantId = 'YOUR_XERO_TENANT_ID';
        array[UUID] contactIds = ["00000000-0000-0000-0000-000000000000","00000000-0000-0000-0000-000000000000"];
        Boolean includeManualJournals = true;
        String startDate = '2020-09-15';
        String endDate = '2020-09-15';

        try {
            IncomeByContactResponse result = apiInstance.getFinancialStatementContactsRevenue(accessToken, xeroTenantId, contactIds, includeManualJournals, startDate, endDate);
            System.out.println(result);
        } catch (XeroException e) {
            System.err.println("Exception when calling FinanceApi#getFinancialStatementContactsRevenue");
            e.printStackTrace();
        }
    }
}

Scopes

finance.statements.read Grant read-only access to finacial statements

Parameters

Header parameters
Name Description
xero-tenant-id*
String
Xero identifier for Tenant
Required
Query parameters
Name Description
contactIds
array[UUID] (uuid)

Specifies the customer contacts to be included in the report.

If no parameter is provided, all customer contacts will be included
includeManualJournals
Boolean

Specifies whether to include the manual journals in the report.

If no parameter is provided, manual journals will not be included.
startDate
String

Date yyyy-MM-dd

Specifies the start date for the report.

If no parameter is provided, the date of 12 months before the end date will be used.

It is recommended to always specify both a start date and end date; While the initial range may be set to 12 months, this may need to be reduced for high volume organisations in order to improve latency.
endDate
String

Date yyyy-MM-dd

Specifies the end date for the report.

If no parameter is provided, the current date will be used.

It is recommended to always specify both a start date and end date; While the initial range may be set to 12 months, this may need to be reduced for high volume organisations in order to improve latency.

getFinancialStatementProfitAndLoss

Get Profit & Loss report

The profit and loss statement is a standard financial report providing detailed year to date income and expense detail for an organisation.


/FinancialStatements/ProfitAndLoss

Usage and SDK Samples

import org.openapitools.client.api.*;
import org.openapitools.client.api.client.FinanceApi;
import org.openapitools.client.models.finance.*;

import java.io.File;
import java.util.*;

public class FinanceApiExample {
    private FinanceApi apiInstance;
    
    public static void main(String[] args) {
        String accessToken = "YOUR_ACCESS_TOKEN";
        ApiClient defaultClient = new ApiClient();

        apiInstance = AccountingApi.getInstance(defaultClient);
        String xeroTenantId = 'YOUR_XERO_TENANT_ID';
        String startDate = '2020-09-15';
        String endDate = '2021-09-15';

        try {
            ProfitAndLossResponse result = apiInstance.getFinancialStatementProfitAndLoss(accessToken, xeroTenantId, startDate, endDate);
            System.out.println(result);
        } catch (XeroException e) {
            System.err.println("Exception when calling FinanceApi#getFinancialStatementProfitAndLoss");
            e.printStackTrace();
        }
    }
}

Scopes

finance.statements.read Grant read-only access to finacial statements

Parameters

Header parameters
Name Description
xero-tenant-id*
String
Xero identifier for Tenant
Required
Query parameters
Name Description
startDate
String

Date e.g. yyyy-MM-dd

Specifies the start date for profit and loss report

If no parameter is provided, the date of 12 months before the end date will be used.
endDate
String

Date e.g. yyyy-MM-dd

Specifies the end date for profit and loss report

If no parameter is provided, the current date will be used.

getFinancialStatementTrialBalance

Get Trial Balance report

The trial balance provides a detailed list of all accounts of an organisation at a point in time, with revenue and expense items being year to date.


/FinancialStatements/TrialBalance

Usage and SDK Samples

import org.openapitools.client.api.*;
import org.openapitools.client.api.client.FinanceApi;
import org.openapitools.client.models.finance.*;

import java.io.File;
import java.util.*;

public class FinanceApiExample {
    private FinanceApi apiInstance;
    
    public static void main(String[] args) {
        String accessToken = "YOUR_ACCESS_TOKEN";
        ApiClient defaultClient = new ApiClient();

        apiInstance = AccountingApi.getInstance(defaultClient);
        String xeroTenantId = 'YOUR_XERO_TENANT_ID';
        String endDate = '2021-09-15';

        try {
            TrialBalanceResponse result = apiInstance.getFinancialStatementTrialBalance(accessToken, xeroTenantId, endDate);
            System.out.println(result);
        } catch (XeroException e) {
            System.err.println("Exception when calling FinanceApi#getFinancialStatementTrialBalance");
            e.printStackTrace();
        }
    }
}

Scopes

finance.statements.read Grant read-only access to finacial statements

Parameters

Header parameters
Name Description
xero-tenant-id*
String
Xero identifier for Tenant
Required
Query parameters
Name Description
endDate
String

Date e.g. yyyy-MM-dd

Specifies the end date for trial balance report

If no parameter is provided, the current date will be used.