Xero: Retrieves the contact Id and name of each contact group

← Accounting operations · Get started

Operation xero.getcontactgroups

Provider route: GET /api.xro/2.0/ContactGroups. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/xero with npm, or alter-sdk-xero with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { XeroIntegration } from "@alter-ai/xero";

async function execute(input: Parameters<XeroIntegration["accounting"]["getContactGroups"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new XeroIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.accounting.getContactGroups(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_xero import XeroIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = XeroIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.accounting.get_contact_groups(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
query	object	Optional	Additional keys: not allowed
query.where	string	Optional
query.order	string	Optional
headers	object	Required within parent	Additional keys: not allowed
headers.xero-tenant-id	string	Required within parent

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	Model	Root	Expand Creates a contact group — response body

Referenced models: Creates a contact group — response body

Schemas

13 more schemas are linked from the tables above, on the schema pages.

Creates a contact group — response body

Field	Type	Presence	Description and constraints
$	object	Root
ContactGroups	array	Optional
ContactGroups[]	Model	Each item	Expand Creates a contact group — response body — Contact Groups item

Referenced models: Creates a contact group — response body — Contact Groups item

Creates a contact group — response body — Contact Groups item

Field	Type	Presence	Description and constraints
$	object	Root
ContactGroupID	string	Optional	The Xero identifier for an contact group – specified as a string following the endpoint name. e.g. /297c2dc5-cc47-4afd-8ec8-74990b8761e9 Format: uuid
Contacts	array	Optional	The ContactID and Name of Contacts in a contact group. Returned on GETs when the ContactGroupID is supplied in the URL.
Contacts[]	Model	Each item	Expand Creates contacts to a specific contact group — response body — Contacts item
Name	string	Optional	The Name of the contact group. Required when creating a new contact group
Status	string	Optional	The 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. Known values: ACTIVE, DELETED

Referenced models: Creates contacts to a specific contact group — response body — Contacts item

Creates contacts to a specific contact group — response body — Contacts item

Field	Type	Presence	Description and constraints
$	object	Root
AccountNumber	string	Optional	A user defined account number. This can be updated via the API and the Xero UI (max length = 50) Maximum length: 50
AccountsPayableTaxType	string	Optional	The tax type from TaxRates
AccountsReceivableTaxType	string	Optional	The tax type from TaxRates
Addresses	array	Optional	Store certain address types for a contact – see address types
Addresses[]	Model	Each item	Expand Creates contacts to a specific contact group — response body — Contacts item Addresses item
Attachments	array	Optional	Displays array of attachments from the API
Attachments[]	Model	Each item	Expand create Contact Attachment By File Name — response body — Attachments item
Balances	Model	Optional	Expand Creates contacts to a specific contact group — response body — Contacts item Balances
BankAccountDetails	string	Optional	Bank account number of contact
BatchPayments	Model	Optional	Expand Creates contacts to a specific contact group — response body — Contacts item Batch Payments
BrandingTheme	Model	Optional	Expand Retrieves all the branding themes — response body — Branding Themes item
CompanyNumber	string	Optional	Company registration number (max length = 50) Maximum length: 50
ContactGroups	array	Optional	Displays which contact groups a contact is included in
ContactGroups[]	Model	Each item	Expand Creates a contact group — response body — Contact Groups item
ContactID	string	Optional	Xero identifier Format: uuid
ContactNumber	string	Optional	This can be updated via the API only i.e. This field is read only on the Xero contact screen, used to identify contacts in external systems (max length = 50). If the Contact Number is used, this is displayed as Contact Code in the Contacts UI in Xero. Maximum length: 50
ContactPersons	array	Optional	See contact persons
ContactPersons[]	Model	Each item	Expand Creates contacts to a specific contact group — response body — Contacts item Contact Persons item
ContactStatus	string	Optional	Current status of a contact – see contact status types Known values: ACTIVE, ARCHIVED, GDPRREQUEST
DefaultCurrency	Model	Optional	Expand Deletes an Allocation from a Prepayment — response body — Invoice Currency Code
Discount	JSON	Optional
Discount (anyOf 1)	number	Alternative	The default discount rate for the contact (read only) Format: double Read only: true
Discount (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
EmailAddress	string	Optional	Email address of contact person (umlauts not supported) (max length = 255) Maximum length: 255
FirstName	string	Optional	First name of contact person (max length = 255) Maximum length: 255
HasAttachments	boolean	Optional	A boolean to indicate if a contact has an attachment Default: false
HasValidationErrors	boolean	Optional	A boolean to indicate if a contact has an validation errors Default: false
IsCustomer	boolean	Optional	true or false – Boolean that describes if a contact has any AR invoices entered against them. Cannot be set via PUT or POST – it is automatically set when an accounts receivable invoice is generated against this contact.
IsSupplier	boolean	Optional	true or false – Boolean that describes if a contact that has any AP invoices entered against them. Cannot be set via PUT or POST – it is automatically set when an accounts payable invoice is generated against this contact.
LastName	string	Optional	Last name of contact person (max length = 255) Maximum length: 255
MergedToContactID	string	Optional	ID for the destination of a merged contact. Only returned when using paging or when fetching a contact by ContactId or ContactNumber. Format: uuid
Name	string	Optional	Full name of contact/organisation (max length = 255) Maximum length: 255
PaymentTerms	Model	Optional	Expand Creates contacts to a specific contact group — response body — Contacts item Payment Terms
Phones	array	Optional	Store certain phone types for a contact – see phone types
Phones[]	Model	Each item	Expand Creates contacts to a specific contact group — response body — Contacts item Phones item
PurchasesDefaultAccountCode	string	Optional	The default purchases account code for contacts
PurchasesDefaultLineAmountType	string	Optional	The default purchases line amount type for a contact Only available when summaryOnly parameter or paging is used, or when fetch by ContactId or ContactNumber. Known values: INCLUSIVE, EXCLUSIVE, NONE
PurchasesTrackingCategories	array	Optional	The default purchases tracking categories for contacts
PurchasesTrackingCategories[]	Model	Each item	Expand Creates contacts to a specific contact group — response body — Contacts item Sales Tracking Categories item
SalesDefaultAccountCode	string	Optional	The default sales account code for contacts
SalesDefaultLineAmountType	string	Optional	The default sales line amount type for a contact. Only available when summaryOnly parameter or paging is used, or when fetch by ContactId or ContactNumber. Known values: INCLUSIVE, EXCLUSIVE, NONE
SalesTrackingCategories	array	Optional	The default sales tracking categories for contacts
SalesTrackingCategories[]	Model	Each item	Expand Creates contacts to a specific contact group — response body — Contacts item Sales Tracking Categories item
StatusAttributeString	string	Optional	Status of object
TaxNumber	string	Optional	Tax number of contact – this is also known as the ABN (Australia), GST Number (New Zealand), VAT Number (UK) or Tax ID Number (US and global) in the Xero UI depending on which regionalized version of Xero you are using (max length = 50) Maximum length: 50
TaxNumberType	string	Optional	Identifier of the regional type of tax number, such as US, UK, or other regional tax identifiers Known values: SSN, EIN, ITIN, ATIN
TrackingCategoryName	string	Optional	The name of the Tracking Category assigned to the contact under SalesTrackingCategories and PurchasesTrackingCategories
TrackingCategoryOption	string	Optional	The name of the Tracking Option assigned to the contact under SalesTrackingCategories and PurchasesTrackingCategories
UpdatedDateUTC	string	Optional	UTC timestamp of last update to contact Read only: true
ValidationErrors	array	Optional	Displays validation errors returned from the API
ValidationErrors[]	Model	Each item	Expand Retrieves journals — response body — Warnings item
Website	string	Optional	Website address for contact (read only) Read only: true
XeroNetworkKey	string	Optional	Store XeroNetworkKey for contacts.

Referenced models: Creates contacts to a specific contact group — response body — Contacts item Batch Payments, Creates contacts to a specific contact group — response body — Contacts item Contact Persons item, Deletes an Allocation from a Prepayment — response body — Invoice Currency Code, Creates contacts to a specific contact group — response body — Contacts item Addresses item, create Contact Attachment By File Name — response body — Attachments item, Creates contacts to a specific contact group — response body — Contacts item Balances, Retrieves all the branding themes — response body — Branding Themes item, Creates a contact group — response body — Contact Groups item, Creates contacts to a specific contact group — response body — Contacts item Payment Terms, Creates contacts to a specific contact group — response body — Contacts item Phones item, Creates contacts to a specific contact group — response body — Contacts item Sales Tracking Categories item, Retrieves journals — response body — Warnings item

Policy, approvals and errors

SDK function policy ID: xero.getcontactgroups. Catalog operation: getContactGroups. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Official provider source