Xero setup guide

Agents read payments, invoices and accounts. Anything that moves money is tier 4: a person always approves it.

Ways to connect

Company admins connect apps, on the Integrations page in Everdeck: open Xero, choose one of the ways below, follow its steps and fill in its fields. Everdeck checks what you enter before it saves anything, and asks you to confirm it’s you (your second factor) before you type any secret. How connecting works.

Xero can be connected 2 ways. Where there’s a key or token to paste, that’s usually the quickest.

Your Xero app (sign in)

Your OAuth app.

This way signs in with an OAuth app you create for Xero, as its steps describe: Everdeck never uses an app of its own. Register this redirect URI with your app:

https://everdeck.io/api/oauth/callback

Then save the app’s client ID and secret in Everdeck, on the connect page or under OAuth apps, and sign in.

1. Sign in at https://developer.xero.com/app/manage and click New app.
2. Enter a name (for example Everdeck), choose Web app as the integration type, enter your company website as the company or application URL and https://everdeck.io/api/oauth/callback as the redirect URI, accept the terms and click Create app.
3. On the app's Configuration page copy the Client id, click Generate a secret and copy it. Paste both into the form.
4. Click Connect, sign in as the Xero user whose access the agent should use (reports need a user with the reports permission), pick the organisation and click Allow access.
5. Optional, to start work when an invoice or contact changes: save the connection, add the Xero trigger you need (Invoice changed or Contact changed) on the Intake page and copy the address it gives you. On the app's Webhooks page in the developer portal tick Invoices or Contacts (the one the trigger watches), paste the address as the delivery URL and save. Copy the Webhooks key into the form, then click Send "Intent to receive". A Xero app sends the events of every organisation it's connected to to one address, so one app serves one trigger of one connection: make another app (and connection) for another trigger or organisation.

Field	What to enter
Webhooks key (only for Xero triggers) (optional)	A secret: Everdeck saves it encrypted and never shows it again. Needed only to start work from Xero events (step 5): the key on your app's Webhooks page. Leave it empty otherwise.
Organisation ID (filled in for you) (optional)	Text. Only needed when you connect several organisations in one sign-in: the tenant id of the one the agents should use.

The scopes Everdeck asks for:

• offline_access
• accounting.contacts
• accounting.invoices
• accounting.payments
• accounting.settings.read
• accounting.reports.profitandloss.read
• accounting.reports.balancesheet.read
• accounting.reports.trialbalance.read
• accounting.reports.banksummary.read
• accounting.reports.aged.read

When you disconnect, Everdeck asks Xero to revoke the sign-in, then deletes the tokens it saved.

Xero custom connection (paid; AU, NZ, UK and US only)

Your OAuth app.

This way uses the client ID and secret of an OAuth app you create for Xero. There’s no sign-in page: Everdeck asks Xero for a token with them.

1. Custom connections are a monthly add-on for organisations in Australia, New Zealand, the UK and the US. Buy one for your organisation at https://connect.xero.com/custom.
2. At https://developer.xero.com/app/manage click New app, enter a name and choose Custom connection.
3. Select the scopes listed below and choose yourself (or the person who will approve it) as the authorising user, then save. Xero emails that user a Connect link.
4. Open the link, review the access, pick the organisation and click Connect.
5. Back on the app page copy the Client id, click Generate a secret, and paste both into the form. No sign-in is needed after this; the connection acts as the authorising user.
6. Optional, to start work when an invoice or contact changes: save the connection, add the Xero trigger you need (Invoice changed or Contact changed) on the Intake page and copy the address it gives you. On the app's Webhooks page tick Invoices or Contacts (the one the trigger watches), paste the address as the delivery URL and save. Copy the Webhooks key into the form, then click Send "Intent to receive". One app sends all its events to one address, so it serves one trigger.

Field	What to enter
Webhooks key (only for Xero triggers) (optional)	A secret: Everdeck saves it encrypted and never shows it again. Needed only to start work from Xero events (step 6): the key on your app's Webhooks page. Leave it empty otherwise.

The scopes Everdeck asks for:

• accounting.contacts
• accounting.invoices
• accounting.payments
• accounting.settings.read
• accounting.reports.profitandloss.read
• accounting.reports.balancesheet.read
• accounting.reports.trialbalance.read
• accounting.reports.banksummary.read
• accounting.reports.aged.read

Disconnecting deletes the access token Everdeck saved for this connection. The OAuth app's client ID and secret stay saved under OAuth apps in Everdeck and keep working at Xero until you delete the app or rotate its secret there.

What agents can do

An agent uses an action only when its charter grants it, on the agent’s Tools tab, where you choose whether each one runs by itself (Auto), asks first or never runs. Each action has a risk tier: tier 3 actions, which customers or the public see, ask first unless you choose otherwise, and tier 4 actions (money, deleting things, access) always need a person. How tools and tiers work.

Actions marked Reads outside content return things people outside your company may have written. Agents treat what they read as information, never as instructions, and their riskier actions later in the same session need approval.

• Search contactsTier 0 · ReadReads outside contentxero_search_contacts

  Find customers and suppliers by text (matches name, first and last name, contact number, company number and email) or an exact where filter such as EmailAddress=="[email protected]". Returns ids, email, account number, status and outstanding balances.

• Create a contactTier 2 · ReversibleReads outside contentxero_create_contact

  Add a customer or supplier. Name is what appears on invoices and currently has to be unique, so search first. Customer or supplier status is set automatically by the first sales invoice or bill.

• List invoices and billsTier 0 · ReadReads outside contentxero_list_invoices

  List sales invoices (Type ACCREC) and bills (ACCPAY), up to 1,000 per page, with totals, amount due and dates. Filter by statuses, contact ids, a where expression or text in invoice number and reference. Line items are left out; use get_invoice for them.

• Read an invoice or billTier 0 · ReadReads outside contentxero_get_invoice

  Read one invoice or bill by InvoiceID or invoice number, with line items, tax, totals and payments.

• Draft an invoice or billTier 2 · ReversibleReads outside contentxero_create_invoice

  Create a sales invoice (ACCREC) or a supplier bill (ACCPAY) as a draft, or as SUBMITTED to put it in Xero's awaiting-approval list. Drafts do not touch the accounts or reports. Sales invoice numbers come from the organisation's settings; for bills put the supplier's invoice number in invoice_number.

• Approve an invoice or billTier 4 · Money or irreversibleReads outside contentxero_approve_invoice

  Approve a draft or submitted invoice or bill (status AUTHORISED). It is then posted to the accounts, included in reports and tax returns, and can be paid or emailed. An approved invoice can no longer be deleted, only voided.

• Email a sales invoiceTier 4 · Money or irreversibleReads outside contentxero_email_invoice

  Email a submitted, approved or paid sales invoice (ACCREC) to the contact's primary email and to contact people marked for invoices, using the organisation's default template. It comes from the Xero user who connected Everdeck and marks the invoice as sent.

• Get the online invoice linkTier 0 · ReadReads outside contentxero_get_online_invoice_url

  Get the link to an approved sales invoice on Xero's online invoice page, where the customer can view, download and (if set up) pay it. Not available for drafts. Use it in your own emails.

• Record a paymentTier 4 · Money or irreversibleReads outside contentxero_record_payment

  Record money received for a sales invoice, or paid for a bill, against a bank account (or an account that allows payments). The invoice must be approved; the amount is in the invoice's currency and cannot exceed the amount due. This does not move money; it updates the books.

• Add a note to an invoiceTier 2 · ReversibleReads outside contentxero_add_invoice_note

  Add a note to an invoice's or bill's History and notes, for example what a customer said about payment. Notes are internal (shown as System Generated) and cannot be edited.

• List accountsTier 0 · ReadReads outside contentxero_list_accounts

  List the chart of accounts with code, name, type and tax type. Use codes on invoice lines and bank accounts (Type BANK, or EnablePaymentsToAccount true) for record_payment.

• Run a reportTier 0 · ReadReads outside contentxero_get_report

  Run a standard report: ProfitAndLoss (fromDate, toDate; defaults to this month), BalanceSheet and TrialBalance (date), BankSummary (fromDate, toDate), or aged receivables or payables for one contact (contact_id required). Results are rows and cells as laid out in Xero.

What can start work

These events from Xero can become tasks for your agents through Intake. How Intake works.

A sales invoice or bill was created or changed, including approval, payment, voiding and archiving (Xero INVOICE events). The event names the InvoiceID only; read it with get_invoice.

Connect Xero first. Then, on the Intake page, open Webhooks and sources, find the connection under Connections without an address yet and select Get its URL. Give that address to Xero as the setup steps above describe: Everdeck shows it only once. Then, on the Rules tab, select New rule to say which requests become tasks and who gets them.

A contact was created or updated, including archiving (Xero CONTACT events).

Connect Xero first. Then, on the Intake page, open Webhooks and sources, find the connection under Connections without an address yet and select Get its URL. Give that address to Xero as the setup steps above describe: Everdeck shows it only once. Then, on the Rules tab, select New rule to say which requests become tasks and who gets them.

Testing, problems and disconnecting

Everdeck checks the connection when you save it. On the connection’s page in Integrations, Test checks it again at any time.

If Xero later refuses the connection, for example because a key was deleted or a sign-in expired, the connection shows Needs attention on the Integrations page and the people who manage connections are told. Agents can’t use it until a company admin fixes it with Edit or Reconnect.

To stop agents using Xero, open the connection and select Disconnect. Agents stop using it at once and its saved credentials are deleted. What else happens depends on how it was connected: each way above says.