Contact Groups


Overview

URL https://api.xero.com/api.xro/2.0/ContactGroups
Methods Supported GET, PUT, POST, DELETE
Description Allows you to retrieve the ContactID and Name of all the contacts in a contact group
Allows you to create contact groups
Allows you to rename contact groups
Allows you to update the status (delete) contact groups
Allows you to add contacts to a contact group
Allows you to remove a contact from a contact group
Allows you to remove all contacts from a contact group

Elements for ContactGroups

NameThe Name of the contact group. Required when creating a new contact group
StatusThe Status of a contact group. To delete a contact group update the status to DELETED. Only contact groups with a status of ACTIVE are returned on GETs.
ContactGroupIDThe Xero generated unique identifier for contact groups
ContactsThe ContactID and Name of Contacts in a contact group. Returned on GETs when the ContactGroupID is supplied in the URL.


POST ContactGroups

Use this method to create or update contact groups.

Examples for POST ContactGroups

1. Example of creating a new contact group
<ContactGroups>
  <ContactGroup>
    <Name>VIP Customers</Name>
  </ContactGroup>
</ContactGroups>
2. Example of renaming a contact group
<ContactGroups>
  <ContactGroup>
    <ContactGroupID>679382fd-7a71-4281-b013-0ff811ca87ab</ContactGroupID>
    <Name>New Name Here</Name>
  </ContactGroup>
</ContactGroups>
3. Example of the updating the status of a contact group to DELETED. Note: Contact groups with a status of DELETED are no longer returned in GET requests or visible in the app. The status can not be restored to ACTIVE.
<ContactGroups>
  <ContactGroup>
    <ContactGroupID>679382fd-7a71-4281-b013-0ff811ca87ab</ContactGroupID>
    <Status>DELETED</Status>
  </ContactGroup>
</ContactGroups>


PUT ContactGroups

The PUT method is similar to the POST method however you can only create new contact groups. You can also use the PUT method to add contacts to a contact group.

Adding contacts to a contact group

To add contacts to a contact group use the following url /ContactGroups/ContactGroupID/Contacts

e.g PUT /ContactGroups/b05466c8-dc54-4ff8-8f17-9d7008a2e44b/Contacts
 <Contacts>
    <Contact>
      <ContactID>7f01ac80-bd2a-4aad-acaa-80b4b606ae49</ContactID>
    </Contact>
    <Contact>
      <ContactID>4bfd2f5b-f211-4240-ac6f-635543fb68e6</ContactID>
    </Contact>
  </Contacts>


DELETE ContactGroups

The DELETE method is used to remove a contact from a contact group or remove all contacts from a contact group.

1. Removing a contact from a contact group

To remove a contact from a contact use the following url /ContactGroups/ContactGroupID/Contacts/ContactID

e.g DELETE /ContactGroups/b05466c8-dc54-4ff8-8f17-9d7008a2e44b/Contacts/c7500d1a-7ff3-4099-bae3-8ecc45240a29


2. Remove all contacts from a contact group

To remove all contacts from a contact group us the following url /ContactGroups/ContactGroupID/Contacts

e.g DELETE /ContactGroups/b05466c8-dc54-4ff8-8f17-9d7008a2e44b/Contacts

GET ContactGroups

Optional parameters for GET ContactGroups

ContactGroupID The Xero identifier for an contact group - specified as a string following the endpoint name. e.g. /297c2dc5-cc47-4afd-8ec8-74990b8761e9
Where Filter by an any element (see Filters)
order Order by any element returned (see Order By)

Example response for GET ContactGroups

<ContactGroups>
    <ContactGroup>
      <ContactGroupID>97bbd0e6-ab4d-4117-9304-d90dd4779199</ContactGroupID>
      <Name>VIP Customers</Name>
      <Status>ACTIVE</Status>
    </ContactGroup>
    <ContactGroup>
      <ContactGroupID>d0c68f1a-e5dd-4a45-aa02-27d8fdbfd562</ContactGroupID>
      <Name>Preferred Suppliers</Name>
      <Status>ACTIVE</Status>
    </ContactGroup>
</ContactGroups>

Example response for GET ContactGroups/97bbd0e6-ab4d-4117-9304-d90dd4779199

(a ContactGroupID identifier following the endpoint name)

  <ContactGroups>
    <ContactGroup>
      <ContactGroupID>97bbd0e6-ab4d-4117-9304-d90dd4779199</ContactGroupID>
      <Name>Adam's Contacts</Name>
      <Status>ACTIVE</Status>
      <Contacts>
        <Contact>
          <ContactID>9ce626d2-14ea-463c-9fff-6785ab5f9bfb</ContactID>
          <Name>Boom FM</Name>
        </Contact>
        <Contact>
          <ContactID>b9d4332a-26a3-4577-8db2-6e830d4b07cd</ContactID>
          <Name>Berry Brew</Name>
        </Contact>
        <Contact>
          <ContactID>2dc0ef7c-582f-4542-963b-dbdc069e4819</ContactID>
          <Name>Bayside Wholesale</Name>
        </Contact>
      </Contacts>
    </ContactGroup>
  </ContactGroups>