Xero: Retrieves Xero organisation details

← Accounting operations · Get started

Operation xero.getorganisations

Provider route: GET /api.xro/2.0/Organisation. 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"]["getOrganisations"]>[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.getOrganisations(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_organisations(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
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 Retrieves Xero organisation details — response body

Referenced models: Retrieves Xero organisation details — response body

Schemas

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

Retrieves Xero organisation details — response body

Field	Type	Presence	Description and constraints
$	object	Root
Organisations	array	Optional
Organisations[]	Model	Each item	Expand Retrieves Xero organisation details — response body — Organisations item

Referenced models: Retrieves Xero organisation details — response body — Organisations item

Retrieves Xero organisation details — response body — Organisations item

Field	Type	Presence	Description and constraints
$	object	Root
APIKey	string	Optional	Display a unique key used for Xero-to-Xero transactions
Addresses	array	Optional	Address details for organisation – see Addresses
Addresses[]	Model	Each item	Expand Retrieves Xero organisation details — response body — Organisations item Addresses item
BaseCurrency	Model	Optional	Expand Deletes an Allocation from a Prepayment — response body — Invoice Currency Code
Class	string	Optional	Organisation Classes describe which plan the Xero organisation is on (e.g. DEMO, TRIAL, PREMIUM) Known values: DEMO, TRIAL, STARTER, STANDARD, PREMIUM, PREMIUM_20, PREMIUM_50, PREMIUM_100, LEDGER, GST_CASHBOOK, NON_GST_CASHBOOK, ULTIMATE, LITE, ULTIMATE_10, ULTIMATE_20, ULTIMATE_50, ULTIMATE_100, IGNITE, GROW, COMPREHENSIVE, SIMPLE, BASICLITE, ULTRA
CountryCode	Model	Optional	Expand Retrieves Xero organisation details — response body — Organisations item Country Code
CreatedDateUTC	string	Optional	Timestamp when the organisation was created in Xero Read only: true
DefaultPurchasesTax	string	Optional	The default for LineAmountTypes on purchase transactions
DefaultSalesTax	string	Optional	The default for LineAmountTypes on sales transactions
Edition	string	Optional	BUSINESS or PARTNER. Partner edition organisations are sold exclusively through accounting partners and have restricted functionality (e.g. no access to invoicing) Known values: BUSINESS, PARTNER
EmployerIdentificationNumber	string	Optional	Shown if set. US Only.
EndOfYearLockDate	string	Optional	Shown if set. See lock dates
ExternalLinks	array	Optional	Organisation profile links for popular services such as Facebook,Twitter, GooglePlus and LinkedIn. You can also add link to your website here. Shown if Organisation settings is updated in Xero. See ExternalLinks below
ExternalLinks[]	Model	Each item	Expand Retrieves Xero organisation details — response body — Organisations item External Links item
FinancialYearEndDay	JSON	Optional
FinancialYearEndDay (anyOf 1)	integer	Alternative	Calendar day e.g. 0-31
FinancialYearEndDay (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
FinancialYearEndMonth	JSON	Optional
FinancialYearEndMonth (anyOf 1)	integer	Alternative	Calendar Month e.g. 1-12
FinancialYearEndMonth (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
IsDemoCompany	boolean	Optional	Boolean to describe if organisation is a demo company.
LegalName	string	Optional	Organisation name shown on Reports
LineOfBusiness	string	Optional	Description of business type as defined in Organisation settings
Name	string	Optional	Display name of organisation shown in Xero
OrganisationEntityType	string	Optional	Organisation Entity Type Known values: ACCOUNTING_PRACTICE, COMPANY, CHARITY, CLUB_OR_SOCIETY, INDIVIDUAL, LOOK_THROUGH_COMPANY, NOT_FOR_PROFIT, PARTNERSHIP, S_CORPORATION, SELF_MANAGED_SUPERANNUATION_FUND, SOLE_TRADER, SUPERANNUATION_FUND, TRUST, PERSONAL, SINGLEMEMBERLLC, CCORPORATIONLLC, PARTNERSHIPLLC, SCORPORATIONLLC, LLC, NOTLLC, UNSPECIFIED
OrganisationID	string	Optional	Unique Xero identifier Format: uuid
OrganisationStatus	string	Optional	Will be set to ACTIVE if you can connect to organisation via the Xero API
OrganisationType	string	Optional	Organisation Type Known values: ACCOUNTING_PRACTICE, COMPANY, CHARITY, CLUB_OR_SOCIETY, INDIVIDUAL, LOOK_THROUGH_COMPANY, NOT_FOR_PROFIT, PARTNERSHIP, S_CORPORATION, SELF_MANAGED_SUPERANNUATION_FUND, SOLE_TRADER, SUPERANNUATION_FUND, TRUST, PERSONAL, SINGLEMEMBERLLC, CCORPORATIONLLC, PARTNERSHIPLLC, SCORPORATIONLLC, LLC, NOTLLC, UNSPECIFIED
PaymentTerms	Model	Optional	Expand Creates contacts to a specific contact group — response body — Contacts item Payment Terms
PaysTax	boolean	Optional	Boolean to describe if organisation is registered with a local tax authority i.e. true, false
PeriodLockDate	string	Optional	Shown if set. See lock dates
Phones	array	Optional	Phones details for organisation – see Phones
Phones[]	Model	Each item	Expand Creates contacts to a specific contact group — response body — Contacts item Phones item
RegistrationNumber	string	Optional	Shows for New Zealand, Australian and UK organisations
SalesTaxBasis	string	Optional	The accounting basis used for tax returns. See Sales Tax Basis Known values: PAYMENTS, INVOICE, NONE, CASH, ACCRUAL, FLATRATECASH, FLATRATEACCRUAL, ACCRUALS
SalesTaxPeriod	string	Optional	The frequency with which tax returns are processed. See Sales Tax Period Known values: MONTHLY, QUARTERLY1, QUARTERLY2, QUARTERLY3, ANNUALLY, ONEMONTHS, TWOMONTHS, SIXMONTHS, 1MONTHLY, 2MONTHLY, 3MONTHLY, 6MONTHLY, QUARTERLY, YEARLY, NONE
ShortCode	string	Optional	A unique identifier for the organisation. Potential uses.
TaxNumber	string	Optional	Shown if set. Displays in the Xero UI as Tax File Number (AU), GST Number (NZ), VAT Number (UK) and Tax ID Number (US & Global).
Timezone	Model	Optional	Expand Retrieves Xero organisation details — response body — Organisations item Timezone
Version	string	Optional	See Version Types Known values: AU, NZ, GLOBAL, UK, US, AUONRAMP, NZONRAMP, GLOBALONRAMP, UKONRAMP, USONRAMP

Referenced models: Deletes an Allocation from a Prepayment — response body — Invoice Currency Code, Retrieves Xero organisation details — response body — Organisations item Addresses item, Retrieves Xero organisation details — response body — Organisations item Country Code, Retrieves Xero organisation details — response body — Organisations item External Links 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, Retrieves Xero organisation details — response body — Organisations item Timezone

Deletes an Allocation from a Prepayment — response body — Invoice Currency Code

Field	Type	Presence	Description and constraints
$	string	Root	3 letter alpha code for the currency – see list of currency codes Known values: AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTN, BWP, BYN, BYR, BZD, CAD, CDF, CHF, CLF, CLP, CNY, COP, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EEK, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, INR, IQD, IRR, ISK, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LTL, LVL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRO, MRU, MUR, MVR, MWK, MXN, MXV, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SKK, SLE, SLL, SOS, SRD, STD, STN, SVC, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VEF, VES, VND, VUV, WST, XAF, XCD, XOF, XPF, YER, ZAR, ZMW, ZMK, ZWD

Retrieves Xero organisation details — response body — Organisations item Addresses item

Field	Type	Presence	Description and constraints
$	object	Root
AddressLine1	string	Optional	max length = 500 Maximum length: 500
AddressLine2	string	Optional	max length = 500 Maximum length: 500
AddressLine3	string	Optional	max length = 500 Maximum length: 500
AddressLine4	string	Optional	max length = 500 Maximum length: 500
AddressType	string	Optional	define the type of address Known values: POBOX, STREET, DELIVERY
AttentionTo	string	Optional	max length = 255 Maximum length: 255
City	string	Optional	max length = 255 Maximum length: 255
Country	string	Optional	max length = 50, [A-Z], [a-z] only Maximum length: 50
PostalCode	string	Optional	max length = 50 Maximum length: 50
Region	string	Optional	max length = 255 Maximum length: 255

Retrieves Xero organisation details — response body — Organisations item Country Code

Field	Type	Presence	Description and constraints
$	string	Root	Known values: AD, AE, AF, AG, AI, AL, AM, AN, AO, AQ, AR, AS, AT, AU, AW, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BR, BS, BT, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GG, GH, GI, GL, GM, GN, GQ, GR, GT, GU, GW, GY, HK, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, XK, YE, YT, ZA, ZM, ZW

Retrieves Xero organisation details — response body — Organisations item External Links item

Field	Type	Presence	Description and constraints
$	object	Root
Description	string	Optional
LinkType	string	Optional	See External link types Known values: Facebook, GooglePlus, LinkedIn, Twitter, Website
Url	string	Optional	URL for service e.g. http://twitter.com/xeroapi

Policy, approvals and errors

SDK function policy ID: xero.getorganisations. Catalog operation: getOrganisations. 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