Xero

Xero

Available in the finance hub

Element Information Details
Provider API Documentation
Authentication OAuth 2.0
Events Polling
Bulk Not supported
Virtual Data Resources and Transformations Supported

Xero Element

On this page:

Authentication Prerequisites

The Xero element uses the OAuth 2.0 authentication workflow. Before you can authenticate an instance of the Xero element, you need the following:

Provider sandbox

A trial or paid Xero account and sandbox are required.

Generate OAuth credentials

To generate or retrieve OAuth credentials for your Xero account, follow these steps:

  1. In a web browser, navigate to https://developer.xero.com/myapps/ and sign in.
  2. In the top-right corner of the My Apps page, click New App. The Add a New App window appears.
  3. On the Add a New App window, do the following:
    • In the App name field, add a name for your app.
    • In the Company or application URL, add a URL for your organization's or offering's web page.
    • In the Privacy policy URL (optional) field, you can add a link to your organization's privacy policy.
    • In the OAuth 2.0 redirect URI field, add https://auth.cloudelements.io/oauth
    • Review and agree to the terms and conditions, then click Create app. After your app is created, you will be redirected to the Details page.
  4. From the OAuth 2.0 credentials section of your app's Detail page, click Generate a secret.
  5. When you have both a Client ID and Client secret, copy and paste the values, which you will use when you authenticate an element instance. 

Record Tenant ID

To retrieve your Tenant ID, do the following:

  1. After creating a new app and generating OAuth credentials, navigate to the Referral Id section of your app's Details page.
  2. Copy and paste the value in XTID, which you will use as your Tenant ID when you authenticate an element instance.

Required Authentication Parameters

You can authenticate an element instance using the UI or via API calls. For detailed information on how to authenticate an instance, see our related documentation:

To authenticate an instance of the Xero element, you will need the following parameters:

Parameter Name/UI ValueAPI ValueDescriptionSource
OAuth API Keyoauth.api.keyGenerated before authenticationGenerate OAuth Creds
OAuth API Secretoauth.api.secretGenerated before authenticationGenerate OAuth Creds
Xero tenant idxero.tenant.idGenerated before authenticationRecord Tenant ID
OAuth Callback URLoauth.callback.urlDefault value is https://auth.cloudelements.io/oauthAuthenticate an Element Instance (API)

Sample Configuration JSON

"configuration": {
    "oauth.api.key": "[myApiKey]",
    "oauth.api.secret": "[myApiSecret]",
    "xero.tenant.id": "[myTenantId]",
    "oauth.callback.url": "https://auth.cloudelements.io/oauth"
  }

Element Fact Sheet and Reference

Authentication and Configuration Parameters

To see all authentication parameters for the Xero element, follow these steps:

  1. Sign in to Cloud Elements and navigate to Elements.
  2. Hover over the card for an element, and then click My Resources. 
  3. In the top navigation toolbar, click Setup.
  4. From the Setup page, you can view a complete list of the element's authentication and configuration parameters.

Note: Xero has set a limitation of retrieving maximum of 100 records in any API call, especially with "journals" endpoint. Hence, the Cloud Elements pagination doesn’t work in the same way as it works for other endpoints. 

If the pageSize is not equal to 100, elements header error is encountered and the default 100 records are retrieved for the journals endpoint. However, using 'offset' parameter Xero allows you to retrieve more than 100 records. The Pagination logic for this 'journals' endpoints uses this offset parameter and makes multiple API calls to retrieve the next set of record via elements-next-page-token. Xero sorts the journal records from the oldest to the newest. Using this and the offset functionality, the last record Journal number is passed to the the field ‘providerNextPage’ of the ‘elements-next-page-token’ instead of ‘Done’. For more information, please refer to journals.

Events and Supported Resources

The Xero element supports events via polling. For detailed information about our Events framework and how to configure an element instance with events, see our documentation:

You can set up polling events for the following resources of the Xero element:

  • accounts
  • contacts
  • employees
  • items
  • invoices
  • payments
  • purchaseOrders
  • journals

In Xero, the resources, events that can be subscribed using Webhooks are limited to ‘contact’ and ‘invoice’. There is a unique payload, that returns an array of events that are encountered from the beginning until the latest event. In the provider response,  the sequential numbers of the first and last events in the array of events are also retrieved.

In order to find a particular correct event from the array of events, note down the ‘eventDateUtc’ while the event is triggered and search using it after the Webhook response is retrieved. For more information, refer to Webhooks overview https://developer.xero.com/documentation/webhooks/overview

Queryable Endpoints

You can use CEQL to query the following endpoints of the Xero element:

  • GET /contacts
  • GET /credit-notes
  • GET /employees
  • GET /invoices
  • GET /items
  • GET /journals
  • GET /payments
  • GET /purchase-orders
  • GET /tax-rates

Xero Element API Documentation

Base URL

The base URL for all API requests is https://api.cloud-elements.com/elements/api-v2.