Contacts
Query, insert and update contacts for a Xero organisation.
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 Xero identifier for the contact. |
Name | String | False |
The contact name. |
AccountNumber | String | False |
The account number associated with the contact. |
ContactNumber | String | False |
An identifier from an external system. Although this field is read-only on the Xero contact screen, it can be updated via the API. |
CompanyNumber | String | False |
The registration number of the company. The maximum length of this field is 50 characters. |
ContactStatus | String | False |
The status of the contact. Available status types are ACTIVE or ARCHIVED. |
FirstName | String | False |
The first name of the contact. The maximum length of this field is 255 characters. |
LastName | String | False |
The last name of the contact. The maximum length of this field is 255 characters. |
EmailAddress | String | False |
The email address of the contact. The maximum length of this field is 500 characters. |
SkypeUserName | String | False |
The Skype username of the contact. |
ContactPerson1_FirstName | String | False |
First name of contact person. |
ContactPerson1_LastName | String | False |
Last name of contact person. |
ContactPerson1_EmailAddress | String | False |
Email address name of contact person. |
ContactPerson1_IncludeInEmails | Boolean | False |
Whether to include contact person in emails. |
ContactPerson2_FirstName | String | False |
First name of contact person. |
ContactPerson2_LastName | String | False |
Last name of contact person. |
ContactPerson2_EmailAddress | String | False |
Email address name of contact person. |
ContactPerson2_IncludeInEmails | Boolean | False |
Whether to include contact person in emails. |
ContactPerson3_FirstName | String | False |
First name of contact person. |
ContactPerson3_LastName | String | False |
Last name of contact person. |
ContactPerson3_EmailAddress | String | False |
Email address name of contact person. |
ContactPerson3_IncludeInEmails | Boolean | False |
Whether to include contact person in emails. |
ContactPerson4_FirstName | String | False |
First name of contact person. |
ContactPerson4_LastName | String | False |
Last name of contact person. |
ContactPerson4_EmailAddress | String | False |
Email address name of contact person. |
ContactPerson4_IncludeInEmails | Boolean | False |
Whether to include contact person in emails. |
BankAccountDetails | String | False |
The bank account number of the contact. |
TaxNumber | String | False |
The region-specific tax number of the contact: the ABN (Australia), GST (New Zealand), VAT (UK), or Tax Id Number (US and global). |
AccountsReceivableTaxType | String | False |
The default tax type used for the contact on accounts-receivable invoices. |
AccountsPayableTaxType | String | False |
The default tax type used for the contact on accounts-payable invoices. |
Street_AddressLine1 | String | False |
Line 1 of the address. |
Street_AddressLine2 | String | False |
Line 2 of the address. |
Street_AddressLine3 | String | False |
Line 3 of the address. |
Street_AddressLine4 | String | False |
Line 4 of the address. |
Street_City | String | False |
The city. |
Street_Region | String | False |
The region. |
Street_PostalCode | String | False |
The postal code. |
Street_Country | String | False |
The country. |
Street_AttentionTo | String | False |
The attention-to line of the address. |
POBox_AddressLine1 | String | False |
Line 1 of the address. |
POBox_AddressLine2 | String | False |
Line 2 of the address. |
POBox_AddressLine3 | String | False |
Line 3 of the address. |
POBox_AddressLine4 | String | False |
Line 4 of the address. |
POBox_City | String | False |
The city. |
POBox_Region | String | False |
The region. |
POBox_PostalCode | String | False |
The postal code. |
POBox_Country | String | False |
The country. |
POBox_AttentionTo | String | False |
The attention-to line of the address. |
DDI_PhoneNumber | String | False |
The phone number without area or country code. |
DDI_PhoneAreaCode | String | False |
The area code. |
DDI_PhoneCountryCode | String | False |
The country code. |
Default_PhoneNumber | String | False |
The phone number without area or country code. |
Default_PhoneAreaCode | String | False |
The area code. |
Default_PhoneCountryCode | String | False |
The country code. |
Fax_PhoneNumber | String | False |
The phone number without area or country code. |
Fax_PhoneAreaCode | String | False |
The area code. |
Fax_PhoneCountryCode | String | False |
The country code. |
Mobile_PhoneNumber | String | False |
The phone number without area or country code. |
Mobile_PhoneAreaCode | String | False |
The area code. |
Mobile_PhoneCountryCode | String | False |
The country code. |
UpdatedDateUTC | Datetime | True |
The timestamp of when the contact was last updated. |
ContactGroupId | String | True |
Displays which contact groups a contact is included in. |
MergedToContactID | String | True |
This field displays the destination ID of a contact that has been merged. |
IsSupplier | Boolean | True |
This field shows whether a contact has any accounts-payable (AP) invoices. This field is set automatically when an AP invoice is generated for a contact. |
IsCustomer | Boolean | True |
This field shows whether a contact has any accounts-receivable (AR) invoices. This field is set automatically when an AR invoice is generated for a contact. |
DefaultCurrency | String | False |
The default currency for the contact. |
Website | String | True |
The website of the contact. |
BrandingThemeId | String | True |
The Id of the branding theme. |
BrandingThemeName | String | True |
The Name of the branding theme. |
PurchasesDefaultAccountCode | String | False |
The default purchases account code for contacts. |
PurchasesDefaultLineAmountType | String | True |
The default purchases line amount type for contacts. Possible values are: INCLUSIVE, EXCLUSIVE, or NONE. |
SalesDefaultAccountCode | String | False |
The default sales account code for contacts. |
SalesDefaultLineAmountType | String | True |
The default sales line amount type for contacts. Possible values are: INCLUSIVE, EXCLUSIVE, or NONE. |
BatchPayments_BankAccountNumber | String | True |
Batch payment bank account number for the contact. |
BatchPayments_BankAccountName | String | True |
Batch payment bank account name for the contact. |
BatchPayments_Details | String | True |
Batch payment details for the contact. |
Discount | Decimal | True |
The default discount rate for the contact. |
Balances_AccountsReceivable_Outstanding | Decimal | True |
The outstanding and overdue amounts for sales invoices (accounts receivable). |
Balances_AccountsReceivable_Overdue | Decimal | True |
The outstanding and overdue amounts for bills (accounts payable). |
Balances_AccountsPayable_Outstanding | Decimal | True |
The outstanding and overdue amounts for sales invoices (accounts receivable). |
Balances_AccountsPayable_Overdue | Decimal | True |
The outstanding and overdue amounts for bills (accounts payable). |
PaymentTerms_Bills_Day | Int | True |
The default payment terms for the contact. |
PaymentTerms_Bills_Type | String | True |
The default payment terms for the contact. |
PaymentTerms_Sales_Day | Int | True |
The default payment terms for the contact. |
PaymentTerms_Sales_Type | String | True |
The default payment terms for the contact. |
SalesTrackingCategory1_Name | String | False |
The default sales tracking category name for contacts. |
SalesTrackingOption1_Name | String | False |
The default sales tracking option name for contacts. |
SalesTrackingCategory2_Name | String | False |
The default sales tracking category name for contacts. |
SalesTrackingOption2_Name | String | False |
The default sales tracking option name for contacts. |
PurchaseTrackingCategory1_Name | String | False |
The default purchase tracking category name for contacts. |
PurchaseTrackingOption1_Name | String | False |
The default purchase tracking option name for contacts. |
PurchaseTrackingCategory2_Name | String | False |
The default purchase tracking category name for contacts. |
PurchaseTrackingOption2_Name | String | False |
The default purchase tracking option name for contacts. |
HasAttachments | Boolean | True |
This field indicates whether the invoice has an attachment. |
TenantId | String | False |
The ID of the tenant to query instead of the connection tenant |