Contacts

Used for querying, inserting, and updating contact records within a Xero organization. Contacts include customers, suppliers, and other entities that the organization interacts with for business transactions.

Table Specific Information

The Contacts table allows you to SELECT, INSERT, and UPDATE contacts for a Xero organization.

Optimized Filters and High Volume Thresholds

The Xero API defines a list of optimized filters for certain tables and views. If any query filter not included in this list is applied to any such table or view, and the number of records available in that table or view exceeds a certain value (what Xero calls a "high volume threshold"), the Xero API will block the query.

To avoid the rejection of your queries by the Xero API, if the the number of records in your table or view exceed the high volume threshold, make sure to use filters from the list of optimized filters.

Note that the high volume threshold, as well as the exact list of optimized filters, is subject to change as Xero updates its API.

The Xero API does not list a high volume threshold for the Contacts table. The Xero API lists the following optimized filters for this table:

Optimized columns (when used in WHERE clauses):
- Name
- EmailAddress
- AccountNumber
Optimized ORDER BY columns:
- ContactID
- UpdatedDateUTC
- Name

SELECT

The Xero API allows extensive filtering and ordering. You can define WHERE and ORDER BY clauses in a query to filter and order the results using any non-line-item column.

Note: The Xero API does not support filtering on line items or journal lines.

INSERT

To insert a single row, set the required fields. A new table object is created as a single entry. The Name field is required to add a new contact.

INSERT INTO Contacts (Name) VALUES ('John Doe')

The Contacts table also supports bulk inserts, simply specify multiple records to be added in the VALUES clause:

INSERT INTO Contacts (Name) VALUES ('John Doe'), ('Johnny')

UPDATE

You can update any field that is not read-only.

Note: UPDATE operations will count as two operations against the Xero API. One is required to retrieve the existing record, and another to update the record with new data.

Columns


Name	Type	ReadOnly	Description
ContactId [KEY]	String	True	The unique identifier assigned by Xero to the contact. This ID links the contact to their corresponding record in the system, ensuring it is distinct from other contacts.
Name	String	False	The name of the contact. This is used to identify the contact in the system and may be the full name of a person or the name of an organization.
AccountNumber	String	False	The account number associated with the contact, used for referencing the specific account in transactions or financial records.
ContactNumber	String	False	An identifier from an external system for the contact. This field can be updated via the API, although it is read-only on the Xero contact screen.
CompanyNumber	String	False	The company registration number for the contact, typically used for official identification purposes. The maximum length for this field is 50 characters.
ContactStatus	String	False	The current status of the contact, indicating whether they are active or archived. 'ACTIVE' means the contact is in use, while 'ARCHIVED' means the contact is no longer active.
FirstName	String	False	The first name of the contact, applicable to individual contacts. The maximum length for this field is 255 characters.
LastName	String	False	The last name of the contact, applicable to individual contacts. The maximum length for this field is 255 characters.
EmailAddress	String	False	The email address associated with the contact. This allows for communication and invoicing. The maximum length for this field is 500 characters.
SkypeUserName	String	False	The Skype username of the contact, which can be used for communication through Skype.
ContactPerson1_FirstName	String	False	The first name of the primary contact person for this contact.
ContactPerson1_LastName	String	False	The last name of the primary contact person for this contact.
ContactPerson1_EmailAddress	String	False	The email address of the primary contact person for this contact.
ContactPerson1_IncludeInEmails	Boolean	False	Indicates whether the primary contact person should be included in email communications.
ContactPerson2_FirstName	String	False	The first name of the second contact person for this contact.
ContactPerson2_LastName	String	False	The last name of the second contact person for this contact.
ContactPerson2_EmailAddress	String	False	The email address of the second contact person for this contact.
ContactPerson2_IncludeInEmails	Boolean	False	Indicates whether the second contact person should be included in email communications.
ContactPerson3_FirstName	String	False	The first name of the third contact person for this contact.
ContactPerson3_LastName	String	False	The last name of the third contact person for this contact.
ContactPerson3_EmailAddress	String	False	The email address of the third contact person for this contact.
ContactPerson3_IncludeInEmails	Boolean	False	Indicates whether the third contact person should be included in email communications.
ContactPerson4_FirstName	String	False	The first name of the fourth contact person for this contact.
ContactPerson4_LastName	String	False	The last name of the fourth contact person for this contact.
ContactPerson4_EmailAddress	String	False	The email address of the fourth contact person for this contact.
ContactPerson4_IncludeInEmails	Boolean	False	Indicates whether the fourth contact person should be included in email communications.
BankAccountDetails	String	False	The bank account number associated with the contact. This is used for processing payments or transactions involving the contact.
TaxNumber	String	False	The region-specific tax number of the contact, such as the ABN (Australia), GST (New Zealand), VAT (UK), or Tax ID Number (US and global). This is required for tax reporting.
AccountsReceivableTaxType	String	False	The default tax type applied to accounts-receivable invoices for this contact. It specifies the tax rules for sales made to the contact.
AccountsPayableTaxType	String	False	The default tax type applied to accounts-payable invoices for this contact. It specifies the tax rules for purchases made from the contact.
Street_AddressLine1	String	False	The first line of the contact's street address. This is the main address for the contact, often including the street name and building number.
Street_AddressLine2	String	False	The second line of the contact's street address. This is used for additional address details like apartment or suite numbers.
Street_AddressLine3	String	False	The third line of the contact's street address, used if further address details are needed.
Street_AddressLine4	String	False	The fourth line of the contact's street address, used for further address information if applicable.
Street_City	String	False	The city of the contact's street address. This helps to geographically locate the contact.
Street_Region	String	False	The region or state of the contact's street address.
Street_PostalCode	String	False	The postal code of the contact's street address. This code is used for mail sorting and location identification.
Street_Country	String	False	The country of the contact's street address.
Street_AttentionTo	String	False	The attention-to line of the contact's street address, used to specify the recipient for mail or packages.
POBox_AddressLine1	String	False	The first line of the contact's PO Box address.
POBox_AddressLine2	String	False	The second line of the contact's PO Box address.
POBox_AddressLine3	String	False	The third line of the contact's PO Box address.
POBox_AddressLine4	String	False	The fourth line of the contact's PO Box address.
POBox_City	String	False	The city of the contact's PO Box address.
POBox_Region	String	False	The region or state of the contact's PO Box address.
POBox_PostalCode	String	False	The postal code of the contact's PO Box address.
POBox_Country	String	False	The country of the contact's PO Box address.
POBox_AttentionTo	String	False	The attention-to line for the contact's PO Box address, indicating the recipient for mail or packages.
DDI_PhoneNumber	String	False	The phone number for the contact, excluding the area or country code.
DDI_PhoneAreaCode	String	False	The area code for the contact's phone number, indicating the geographical region of the phone.
DDI_PhoneCountryCode	String	False	The country code for the contact's phone number, used for international dialing.
Default_PhoneNumber	String	False	The default phone number for the contact, excluding the area or country code.
Default_PhoneAreaCode	String	False	The area code for the contact's default phone number.
Default_PhoneCountryCode	String	False	The country code for the contact's default phone number.
Fax_PhoneNumber	String	False	The fax number for the contact, excluding the area or country code.
Fax_PhoneAreaCode	String	False	The area code for the contact's fax number.
Fax_PhoneCountryCode	String	False	The country code for the contact's fax number.
Mobile_PhoneNumber	String	False	The mobile phone number for the contact, excluding the area or country code.
Mobile_PhoneAreaCode	String	False	The area code for the contact's mobile phone number.
Mobile_PhoneCountryCode	String	False	The country code for the contact's mobile phone number.
UpdatedDateUTC	Datetime	True	The timestamp indicating when the contact information was last updated in the system.
ContactGroupId	String	True	The unique identifier of the contact group that the contact is part of. This field indicates which group the contact belongs to.
MergedToContactID	String	True	The ID of the contact that this contact has been merged into. This field shows the destination contact after the merge process.
IsSupplier	Boolean	True	Indicates whether the contact is marked as a supplier. If the value is 'true', the contact has accounts-payable (AP) invoices, meaning they are a vendor in the system.
IsCustomer	Boolean	True	Indicates whether the contact is marked as a customer. If the value is 'true', the contact has accounts-receivable (AR) invoices, meaning they are a customer in the system.
DefaultCurrency	String	False	The default currency used for transactions with the contact. This currency is applied to invoices and payments unless otherwise specified.
Website	String	True	The website URL associated with the contact. This could be the contact's business or personal website.
BrandingThemeId	String	True	The unique identifier for the branding theme applied to the contact's invoices or documents.
BrandingThemeName	String	True	The name of the branding theme applied to the contact's invoices or documents.
PurchasesDefaultAccountCode	String	False	The default account code used for purchases from this contact. This helps categorize expenses related to purchases from the contact.
PurchasesDefaultLineAmountType	String	True	The default line amount type for purchases from this contact. Valid values are 'INCLUSIVE', 'EXCLUSIVE', or 'NONE', indicating how tax is applied to purchases.
SalesDefaultAccountCode	String	False	The default account code used for sales to this contact. This helps categorize revenue from sales to the contact.
SalesDefaultLineAmountType	String	True	The default line amount type for sales to this contact. Valid values are 'INCLUSIVE', 'EXCLUSIVE', or 'NONE', indicating how tax is applied to sales.
BatchPayments_BankAccountNumber	String	True	The bank account number for batch payments associated with this contact.
BatchPayments_BankAccountName	String	True	The bank account name for batch payments associated with this contact.
BatchPayments_Details	String	True	The details associated with batch payments for this contact.
Discount	Decimal	True	The default discount rate applied to transactions with this contact. This rate reduces the total amount due on invoices.
Balances_AccountsReceivable_Outstanding	Decimal	True	The outstanding balance for accounts-receivable (AR) invoices for this contact, indicating the amount owed by the contact.
Balances_AccountsReceivable_Overdue	Decimal	True	The overdue balance for accounts-receivable (AR) invoices for this contact, representing the amount that is past due.
Balances_AccountsPayable_Outstanding	Decimal	True	The outstanding balance for accounts-payable (AP) invoices for this contact, indicating the amount owed to the contact.
Balances_AccountsPayable_Overdue	Decimal	True	The overdue balance for accounts-payable (AP) invoices for this contact, representing the amount that is past due.
PaymentTerms_Bills_Day	Int	True	The default payment terms for bills associated with this contact. This value specifies the number of days within which the bill should be paid.
PaymentTerms_Bills_Type	String	True	The default payment terms type for bills associated with this contact, such as 'Net 30' or 'Due on Receipt'.
PaymentTerms_Sales_Day	Int	True	The default payment terms for sales associated with this contact. This value specifies the number of days within which the sales invoice should be paid.
PaymentTerms_Sales_Type	String	True	The default payment terms type for sales associated with this contact, such as 'Net 30' or 'Due on Receipt'.
SalesTrackingCategory1_Name	String	False	The default sales tracking category name for this contact, used for categorizing sales transactions.
SalesTrackingOption1_Name	String	False	The default sales tracking option name for this contact, providing more specific categorization for sales transactions.
SalesTrackingCategory2_Name	String	False	The default sales tracking category name for this contact, providing a second level of categorization for sales transactions.
SalesTrackingOption2_Name	String	False	The default sales tracking option name for this contact, providing a second level of categorization for sales transactions.
PurchaseTrackingCategory1_Name	String	False	The default purchase tracking category name for this contact, used for categorizing purchase transactions.
PurchaseTrackingOption1_Name	String	False	The default purchase tracking option name for this contact, providing more specific categorization for purchase transactions.
PurchaseTrackingCategory2_Name	String	False	The default purchase tracking category name for this contact, providing a second level of categorization for purchase transactions.
PurchaseTrackingOption2_Name	String	False	The default purchase tracking option name for this contact, providing a second level of categorization for purchase transactions.
HasAttachments	Boolean	True	Indicates whether the contact has any attachments, such as documents or receipts, associated with their record.
TenantId	String	False	The unique identifier for the tenant, allowing queries to access data specific to a particular tenant rather than using the default connection tenant.