Allows for the querying, insertion, updating, and deletion of contact groups. Contact groups enable the categorization of contacts into different segments for easier management and reporting.

Table Specific Information

The ContactGroups table allows you to manage both contact groups as well as the members of those contact groups.

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

When inserting with a contact group, you can either insert a new contact group or add contacts into an existing group.

To insert a new contact group, only the Name field should be given:

INSERT INTO ContactGroups (Name) VALUES ('Contractors')

To add a contact into an existing group, both the ContactGroupId and the Contact_ContactId must be provided. The value for the Contact_ContactId field can be retrieved by querying the Contacts table.

INSERT INTO ContactGroups (ContactGroupId, Contact_ContactId) VALUES ('11111-11111-11111-11111', '22222-22222-22222-22222')

Multiple contacts may be provided using the ContactAggregate:

INSERT INTO ContactGroups (ContactGroupId, ContactAggregate) VALUES (
  '11111-11111-11111-11111', 
  '<Contact>
	<ContactID>22222-22222-22222-22222</ContactID>
   </Contact>
   <Contact>
	<ContactID>33333-33333-33333-33333</ContactID>
   </Contact>')

UPDATE

When updating a contact group, the only fields that can be changed are the Name and Status field. Changing the Status field to DELETED will delete the contact group.

-- Renaming the group
UPDATE ContactGroup SET Name = 'External Contractors' WHERE ContactGroupId = '11111-11111-11111-1111'


-- Deleting the group
UPDATE ContactGroup SET Status = 'DELETED' WHERE ContactGroupId = '11111-11111-11111-1111'

DELETE

Deleting entries from a contact group will remove individual contacts from the group.

DELETE FROM ContactGroups WHERE Id = '3|11111-11111-11111-11111'

Columns

Name	Type	ReadOnly	Description
Id [KEY]	String	True	A unique identifier for the line item, combining the index of the line item with the ID of the Contact Group. This identifier helps reference a specific entry in the Contact Group.
ContactGroupId	String	False	The unique Xero identifier for the contact group. This ID links the group to its corresponding record in the system, making it distinguishable from other groups.
Name	String	False	The name of the contact group. This label is used to identify and differentiate the group of contacts within the system.
Status	String	False	The current status of the contact group, such as 'Active' or 'Inactive', reflecting whether the group is currently in use or archived.
ContactAggregate	String	False	Used to define multiple contact rows for the group using XML values. This field is only allowed when performing an 'INSERT' operation into an existing Contact Group to add contacts.
Contact_ContactId	String	False	The unique identifier of a contact group member. This ID links the contact to a specific person or entity within the contact group.
Contact_Name	String	True	The name of the contact group member. This provides a human-readable label for the contact, used for identification purposes within the group.
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, especially useful in multi-tenant systems.