> For the complete documentation index, see [llms.txt](https://docs.planetcrust.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.planetcrust.com/human-connections/xero/xero.md).

# Xero

<p align="center"><a class="button primary" data-icon="circle-caret-right">Try @Human</a><a class="button primary" data-icon="check">Buy @Human Subscription</a><a class="button primary" data-icon="comments">Join @Human Community</a></p>

<figure><img src="/files/0Fm4FaCwTmC3s9GNCk6z" alt=""><figcaption></figcaption></figure>

<h3 align="center">Put Xero to Work with @Human Automations and @Human Agents</h3>

<p align="center">The Xero Connection documents all Triggers, Actions and Query Operations available for creating automations via the Xero API.</p>

{% embed url="<https://www.youtube.com/watch?v=CyuUuaBSZzA>" %}

#### 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 <a href="#obtaining-access-credentials" id="obtaining-access-credentials"></a>

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](https://login.xero.com/) 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](https://developer.xero.com/) 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
          }
        ]
      }
    ]
  }
]
```

<p align="center"><a class="button primary" data-icon="square-caret-right">Try @Human</a><a class="button primary" data-icon="check">Buy @Human Subscription</a><a class="button primary" data-icon="comments">Join @Human Community</a></p>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.planetcrust.com/human-connections/xero/xero.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.