Xero

Xero Connection

Put Xero to Work with @Human Automations and @Human Agents

The Xero Connection documents all Triggers, Actions and Query Operations available for creating automations via the Xero API.

What can you do with the Xero Connection?

• Connect to the Xero API in a few clicks

• Use the related Xero Operations (see below) in @Human Automations or @Human Agents

Related Operations

Trigger Operations

Contact Created

Triggers on: contacts/contact_created

Triggered when a new contact is created in Xero.

Contact Updated

Triggers on: contacts/contact_updated

Triggered when an existing contact is updated in Xero.

Invoice Created

Triggers on: invoices/invoice_created

Triggered when a new invoice is created in Xero.

Invoice Updated

Triggers on: invoices/invoice_updated

Triggered when an existing invoice is updated in Xero.

Action Operations

Query Operations

Example link

Related Automations

Example link

Obtaining Access Credentials

To obtain a System-to-System Personal Access Token (PAT) for Xero, follow these steps:

Prerequisites

• A Xero user account with admin privileges (required to generate PATs).

• 2FA (Two-Factor Authentication) enabled on the account (mandatory for PAT generation).

Steps to Generate a Personal Access Token (PAT) in Xero

1. Log in to Xero

   • Go to Xero’s login page and sign in with your admin credentials.

2. Navigate to Developer Portal

   • Click on your profile icon (top-right) → Select "Developer".

3. Go to "Personal Access Tokens"

   • In the left sidebar, click "Personal Access Tokens" under "My Apps".

4. Generate a New Token

   • Click "Generate a new token".

   • Provide a name/description (e.g., "API Integration - [Your App Name]").

   • Select the expiry period (max 6 months).

   • Choose the required scopes (permissions) for your integration (e.g., accounting.contacts, accounting.transactions).

5. Confirm & Copy the Token

   • Click "Generate Token".

   • Copy the token immediately (it will not be shown again).

   • Store it securely (treat it like a password).

Configuring Webhooks

1. Log in to Xero Developer Portal

   • Go to the Xero Developer Portal and navigate to "My Apps".

2. Select Your App

   • Click on the application you want to configure for webhooks.

3. Navigate to Webhooks Section

   • In the left-hand menu, click on the "Webhooks" tab.

4. Add Webhook Details

   • Enter your endpoint URL in the "Delivery URL" field.

5. Choose Event Subscriptions

   • Select the events you want to listen for (e.g., Invoices, Contacts, Payments).

6. Save and Generate Key

   • Click "Save". This will generate your unique Webhook Key.

7. Complete Intent to Receive

   • Click "Send 'Intent to Receive'". Your server must verify the test request to change the status to "Intent to receive".

8. Copy Webhook Key

   • Copy the Webhook Key for use in your application's signature verification logic.

Code (Apache v2.0): Service Connectivity and Metadata

{
  "handle": "xero-api-v2",
  "status": "active",
  "meta": {
    "short": "Xero API",
    "description": "Connect to Xero's accounting software API for managing invoices, contacts, and other financial data.",
    "icon": "xero",
    "tags": ["accounting", "finance", "invoicing"]
  },
  "service": {
    "baseURL": {
      "value": "https://api.xero.com/api.xro/2.0"
    },
    "protocol": "https",
    "contentType": "application/json",
    "headers": {
      "Accept": {
        "value": "application/json"
      },
      "Xero-Tenant-Id": {
        "value": "{{tenantId}}",
        "placeholders": [
          {
            "name": "tenantId",
            "type": "String",
            "description": "Xero tenant ID",
            "required": true
          }
        ]
      }
    },
    "auth": {
      "method": "system_to_system",
      "params": {}
    }
  }
}

Code (Apache v2.0): List of External Resources and Internal Mapping

[
  {
    "handle": "contacts",
    "meta": {
      "short": "Contacts",
      "description": "Manage contact information for customers and suppliers."
    },
    "endpoint": {
      "value": "/Contacts",
      "placeholders": []
    },
    "fields": [
      {
        "name": "ContactID",
        "type": "String",
        "selector": [
          "ContactID"
        ],
        "meta": {
          "description": "Unique identifier for the contact."
        }
      },
      {
        "name": "Name",
        "type": "String",
        "selector": [
          "Name"
        ],
        "meta": {
          "description": "Name of the contact."
        }
      },
      {
        "name": "EmailAddress",
        "type": "String",
        "selector": [
          "EmailAddress"
        ],
        "meta": {
          "description": "Email address of the contact."
        }
      },
      {
        "name": "IsCustomer",
        "type": "Boolean",
        "selector": [
          "IsCustomer"
        ],
        "meta": {
          "description": "Indicates if the contact is a customer."
        }
      },
      {
        "name": "IsSupplier",
        "type": "Boolean",
        "selector": [
          "IsSupplier"
        ],
        "meta": {
          "description": "Indicates if the contact is a supplier."
        }
      }
    ],
    "operations": {
      "list": {
        "method": "GET",
        "path": {
          "value": "",
          "placeholders": []
        },
        "headers": {},
        "queryParams": {},
        "bodyTemplate": null
      },
      "read": {
        "method": "GET",
        "path": {
          "value": "/{{ContactID}}",
          "placeholders": [
            {
              "name": "ContactID",
              "type": "String",
              "description": "Unique identifier for the contact.",
              "required": true
            }
          ]
        },
        "headers": {},
        "queryParams": {},
        "bodyTemplate": null
      },
      "create": {
        "method": "POST",
        "path": {
          "value": "",
          "placeholders": []
        },
        "headers": {
          "Content-Type": "application/json"
        },
        "queryParams": {},
        "bodyTemplate": {
          "value": "{\"Name\": \"{{Name}}\", \"EmailAddress\": \"{{EmailAddress}}\", \"IsCustomer\": {{IsCustomer}}, \"IsSupplier\": {{IsSupplier}}}",
          "placeholders": [
            {
              "name": "Name",
              "type": "String",
              "description": "Name of the contact.",
              "required": true
            },
            {
              "name": "EmailAddress",
              "type": "String",
              "description": "Email address of the contact.",
              "required": false
            },
            {
              "name": "IsCustomer",
              "type": "Boolean",
              "description": "Indicates if the contact is a customer.",
              "required": false,
              "default": "false"
            },
            {
              "name": "IsSupplier",
              "type": "Boolean",
              "description": "Indicates if the contact is a supplier.",
              "required": false,
              "default": "false"
            }
          ]
        }
      },
      "update": {
        "method": "POST",
        "path": {
          "value": "/{{ContactID}}",
          "placeholders": [
            {
              "name": "ContactID",
              "type": "String",
              "description": "Unique identifier for the contact.",
              "required": true
            }
          ]
        },
        "headers": {
          "Content-Type": "application/json"
        },
        "queryParams": {},
        "bodyTemplate": {
          "value": "{\"Name\": \"{{Name}}\", \"EmailAddress\": \"{{EmailAddress}}\", \"IsCustomer\": {{IsCustomer}}, \"IsSupplier\": {{IsSupplier}}}",
          "placeholders": [
            {
              "name": "Name",
              "type": "String",
              "description": "Name of the contact.",
              "required": false
            },
            {
              "name": "EmailAddress",
              "type": "String",
              "description": "Email address of the contact.",
              "required": false
            },
            {
              "name": "IsCustomer",
              "type": "Boolean",
              "description": "Indicates if the contact is a customer.",
              "required": false
            },
            {
              "name": "IsSupplier",
              "type": "Boolean",
              "description": "Indicates if the contact is a supplier.",
              "required": false
            }
          ]
        }
      },
      "delete": {
        "method": "POST",
        "path": {
          "value": "/{{ContactID}}?summarizeErrors=false",
          "placeholders": [
            {
              "name": "ContactID",
              "type": "String",
              "description": "Unique identifier for the contact.",
              "required": true
            }
          ]
        },
        "headers": {
          "Content-Type": "application/json"
        },
        "queryParams": {},
        "bodyTemplate": {
          "value": "{\"Status\": \"ARCHIVED\"}",
          "placeholders": []
        }
      }
    },
    "webhooks": [
      {
        "event": "contact_created",
        "path": "/webhooks/xero/contacts",
        "payload": [
          {
            "name": "ContactID",
            "type": "String",
            "selector": [
              "events",
              0,
              "payload",
              "contact",
              "ContactID"
            ],
            "meta": {
              "description": "Unique identifier for the contact."
            },
            "multivalue": true
          },
          {
            "name": "Name",
            "type": "String",
            "selector": [
              "events",
              0,
              "payload",
              "contact",
              "Name"
            ],
            "meta": {
              "description": "Name of the contact."
            },
            "multivalue": true
          }
        ]
      },
      {
        "event": "contact_updated",
        "path": "/webhooks/xero/contacts",
        "payload": [
          {
            "name": "ContactID",
            "type": "String",
            "selector": [
              "events",
              0,
              "payload",
              "contact",
              "ContactID"
            ],
            "meta": {
              "description": "Unique identifier for the contact."
            },
            "multivalue": true
          },
          {
            "name": "Name",
            "type": "String",
            "selector": [
              "events",
              0,
              "payload",
              "contact",
              "Name"
            ],
            "meta": {
              "description": "Name of the contact."
            },
            "multivalue": true
          }
        ]
      }
    ]
  },
  {
    "handle": "invoices",
    "meta": {
      "short": "Invoices",
      "description": "Manage sales invoices and purchase bills."
    },
    "endpoint": {
      "value": "/Invoices",
      "placeholders": []
    },
    "fields": [
      {
        "name": "InvoiceID",
        "type": "String",
        "selector": [
          "InvoiceID"
        ],
        "meta": {
          "description": "Unique identifier for the invoice."
        }
      },
      {
        "name": "Type",
        "type": "String",
        "selector": [
          "Type"
        ],
        "meta": {
          "description": "Type of the invoice (e.g., ACCREC for sales invoices, ACCPAY for purchase bills)."
        }
      },
      {
        "name": "ContactID",
        "type": "String",
        "selector": [
          "Contact",
          "ContactID"
        ],
        "meta": {
          "description": "Unique identifier of the contact associated with the invoice."
        }
      },
      {
        "name": "ContactName",
        "type": "String",
        "selector": [
          "Contact",
          "Name"
        ],
        "meta": {
          "description": "Name of the contact associated with the invoice."
        }
      },
      {
        "name": "Date",
        "type": "String",
        "selector": [
          "Date"
        ],
        "meta": {
          "description": "Date of the invoice."
        }
      },
      {
        "name": "DueDate",
        "type": "String",
        "selector": [
          "DueDate"
        ],
        "meta": {
          "description": "Due date of the invoice."
        }
      },
      {
        "name": "Status",
        "type": "String",
        "selector": [
          "Status"
        ],
        "meta": {
          "description": "Status of the invoice (e.g., DRAFT, SUBMITTED, PAID)."
        }
      },
      {
        "name": "LineAmountTypes",
        "type": "String",
        "selector": [
          "LineAmountTypes"
        ],
        "meta": {
          "description": "Type of line amounts (e.g., Exclusive, Inclusive, NoTax)."
        }
      },
      {
        "name": "LineItem0Description",
        "type": "String",
        "selector": [
          "LineItems",
          0,
          "Description"
        ],
        "meta": {
          "description": "Description of the first line item."
        },
        "multivalue": true
      },
      {
        "name": "LineItem0Quantity",
        "type": "Number",
        "selector": [
          "LineItems",
          0,
          "Quantity"
        ],
        "meta": {
          "description": "Quantity of the first line item."
        },
        "multivalue": true
      },
      {
        "name": "LineItem0UnitAmount",
        "type": "Number",
        "selector": [
          "LineItems",
          0,
          "UnitAmount"
        ],
        "meta": {
          "description": "Unit price of the first line item."
        },
        "multivalue": true
      },
      {
        "name": "LineItem0AccountCode",
        "type": "String",
        "selector": [
          "LineItems",
          0,
          "AccountCode"
        ],
        "meta": {
          "description": "Account code for the first line item."
        },
        "multivalue": true
      },
      {
        "name": "LineItem0TaxType",
        "type": "String",
        "selector": [
          "LineItems",
          0,
          "TaxType"
        ],
        "meta": {
          "description": "Tax type applied to the first line item."
        },
        "multivalue": true
      },
      {
        "name": "SubTotal",
        "type": "Number",
        "selector": [
          "SubTotal"
        ],
        "meta": {
          "description": "Subtotal amount of the invoice."
        }
      },
      {
        "name": "TotalTax",
        "type": "Number",
        "selector": [
          "TotalTax"
        ],
        "meta": {
          "description": "Total tax amount of the invoice."
        }
      },
      {
        "name": "Total",
        "type": "Number",
        "selector": [
          "Total"
        ],
        "meta": {
          "description": "Total amount of the invoice."
        }
      },
      {
        "name": "AmountDue",
        "type": "Number",
        "selector": [
          "AmountDue"
        ],
        "meta": {
          "description": "Amount due of the invoice."
        }
      },
      {
        "name": "AmountPaid",
        "type": "Number",
        "selector": [
          "AmountPaid"
        ],
        "meta": {
          "description": "Amount paid of the invoice."
        }
      },
      {
        "name": "AmountCredited",
        "type": "Number",
        "selector": [
          "AmountCredited"
        ],
        "meta": {
          "description": "Amount credited of the invoice."
        }
      }
    ],
    "operations": {
      "list": {
        "method": "GET",
        "path": {
          "value": "",
          "placeholders": []
        },
        "headers": {},
        "queryParams": {
          "where": "Status==\"{{Status}}\"",
          "order": "{{Order}}"
        },
        "bodyTemplate": null
      },
      "read": {
        "method": "GET",
        "path": {
          "value": "/{{InvoiceID}}",
          "placeholders": [
            {
              "name": "InvoiceID",
              "type": "String",
              "description": "Unique identifier for the invoice.",
              "required": true
            }
          ]
        },
        "headers": {},
        "queryParams": {},
        "bodyTemplate": null
      },
      "create": {
        "method": "PUT",
        "path": {
          "value": "",
          "placeholders": []
        },
        "headers": {
          "Content-Type": "application/json"
        },
        "queryParams": {},
        "bodyTemplate": {
          "value": "{\"Type\": \"{{Type}}\", \"Contact\": {\"ContactID\": \"{{ContactID}}\"}, \"Date\": \"{{Date}}\", \"DueDate\": \"{{DueDate}}\", \"LineAmountTypes\": \"{{LineAmountTypes}}\", \"LineItems\": {{LineItems}}, \"Status\": \"{{Status}}\"}",
          "placeholders": [
            {
              "name": "Type",
              "type": "String",
              "description": "Type of the invoice.",
              "required": true,
              "options": [
                "ACCREC",
                "ACCPAY"
              ]
            },
            {
              "name": "ContactID",
              "type": "String",
              "description": "Unique identifier for the contact.",
              "required": true
            },
            {
              "name": "Date",
              "type": "String",
              "description": "Date of the invoice.",
              "required": true
            },
            {
              "name": "DueDate",
              "type": "String",
              "description": "Due date of the invoice.",
              "required": true
            },
            {
              "name": "LineAmountTypes",
              "type": "String",
              "description": "Type of line amounts.",
              "required": true,
              "options": [
                "Exclusive",
                "Inclusive",
                "NoTax"
              ]
            },
            {
              "name": "LineItems",
              "type": "Array",
              "description": "Line items of the invoice.",
              "required": true
            },
            {
              "name": "Status",
              "type": "String",
              "description": "Status of the invoice.",
              "required": true,
              "options": [
                "DRAFT",
                "SUBMITTED",
                "AUTHORISED"
              ]
            }
          ]
        }
      },
      "update": {
        "method": "POST",
        "path": {
          "value": "/{{InvoiceID}}",
          "placeholders": [
            {
              "name": "InvoiceID",
              "type": "String",
              "description": "Unique identifier for the invoice.",
              "required": true
            }
          ]
        },
        "headers": {
          "Content-Type": "application/json"
        },
        "queryParams": {},
        "bodyTemplate": {
          "value": "{\"Status\": \"{{Status}}\"}",
          "placeholders": [
            {
              "name": "Status",
              "type": "String",
              "description": "Status of the invoice.",
              "required": true,
              "options": [
                "VOIDED"
              ]
            }
          ]
        }
      },
      "delete": {
        "method": "POST",
        "path": {
          "value": "/{{InvoiceID}}?summarizeErrors=false",
          "placeholders": [
            {
              "name": "InvoiceID",
              "type": "String",
              "description": "Unique identifier for the invoice.",
              "required": true
            }
          ]
        },
        "headers": {
          "Content-Type": "application/json"
        },
        "queryParams": {},
        "bodyTemplate": {
          "value": "{\"Status\": \"DELETED\"}",
          "placeholders": []
        }
      }
    },
    "webhooks": [
      {
        "event": "invoice_created",
        "path": "/webhooks/xero/invoices",
        "payload": [
          {
            "name": "InvoiceID",
            "type": "String",
            "selector": [
              "events",
              0,
              "payload",
              "invoice",
              "InvoiceID"
            ],
            "meta": {
              "description": "Unique identifier for the invoice."
            },
            "multivalue": true
          },
          {
            "name": "Type",
            "type": "String",
            "selector": [
              "events",
              0,
              "payload",
              "invoice",
              "Type"
            ],
            "meta": {
              "description": "Type of the invoice."
            },
            "multivalue": true
          }
        ]
      },
      {
        "event": "invoice_updated",
        "path": "/webhooks/xero/invoices",
        "payload": [
          {
            "name": "InvoiceID",
            "type": "String",
            "selector": [
              "events",
              0,
              "payload",
              "invoice",
              "InvoiceID"
            ],
            "meta": {
              "description": "Unique identifier for the invoice."
            },
            "multivalue": true
          },
          {
            "name": "Status",
            "type": "String",
            "selector": [
              "events",
              0,
              "payload",
              "invoice",
              "Status"
            ],
            "meta": {
              "description": "Status of the invoice."
            },
            "multivalue": true
          }
        ]
      }
    ]
  }
]