Client Management (CM)

This page contains information and artefacts for Software Developers who have or are interested in developing web services that enable a business or their intermediary to manage their obligation information with the ATO. The services described below are only deployed on the SBR ebMS3 platform.

The web services developed to date are:

The ATO Common Message Implementation Guide (cMIG) needs to be read in conjunction with the artefacts within each package for 2014 onward.

The ATO Service Registry provides information on the relationships between services/messages, business applicability (the year/s active), along with channel and environment deployment information.

Account List (ACCLST) - CANCELLED

The Account List (ACCLST) web service and versions has been superseded by the Client Account (CLNTACC) product suite.

Account Role (ACCROLE)

The suite of Account Role (ACCROLE) services supports the following:

  • List Account Role (accrole.list and accrolesum.list) allows an initiating party to view a list of account roles for activity statement and superannuation accounts and retrieve basic role details.
  • Get Account Role (accrole.get) allows an initiating party view activity statement role details for a specified role type.
  • Submit Account Role (accrole.submit) allows an initiating party to add an activity statement role, including roles for GST, FTC, WET, LCT, PAYGW and PAYGI.
  • Update Account Role (accrole.update) allows an initiating party to update an activity statement role, including roles for GST, FTC, WET, LCT, PAYGW and PAYGI.
  • Cancel Account Role (accrole.cancel) allows an initiating party to cancel an activity statement role, including roles for GST, FTC, WET, LCT, PAYGW and PAYGI.

The web service messages are exchanged using the ATO ebMS3 protocol with the message payload constructed using the XML format.

ACCROLE.0001 (2017)

Name Version number StatusSize Published date
ATO ACCROLE. 2017 Package v0.5 Contents.docx 0.5 Draft 244KB 21 September 2017
ATO ACCROLE 2017 Package v0.5.zip 0.5 Draft 2.56MB 21 September 2017

Assessment (ASMT)

The Assessment  (ASMT) service will allow access to outcome of assessment details for issued assessments.  Access to this information will support validation of the ATO processing of an assessment against what was lodged.

The ASMT service actions consist of the following:

  • Assessment List allows an initiating party to view a list of issued assessments for a client or account.
  • Get Assessment allows an initiating party to view the outcome of assessment details for a specified assessment.

The web service messages are exchanged using the ATO ebMS3 protocol with the message payload constructed using the XML format.

ASMT.0002 (2017)

Name Version number StatusSize Published date
ATO ASMT.0002 2017 Package v0.3 Contents.docx 0.3 Draft 256KB 17 August 2017
ATO ASMT.0002 2017 Package v0.3.zip 0.3 Draft 374KB 17 August 2017

ASMT.0001 2016 was Cancelled 02.11.2017.

Client Communication (CC)

The Client Communication (CC) service provides registered agents access to list and view client communications sent from the ATO to their clients.

The CC service consists of the following:

  • Client Communication List service allows a registered agent to request and retrieve a historical record of client communications for single or multiple clients.
  • Client Communication Get service allows a registered agent to retrieve one or more client communications item(s) from the list.

The web service messages are exchanged using the ATO ebMS3 protocol with the message payload constructed using the JSON format.

CC.0001 (2016)

Name Version number Status Size Published date
ATO CC.0001 2016 Business Implementation Guide.docx 1.0 Final 391KB 20 October 2016
ATO CC.0001 2016 Package v0.2 Contents.docx 0.2 Draft 224KB 20 October 2016
ATO CC.0001 2016 Package v0.2.zip 0.2 Draft 269KB 20 October 2016

Client Account (CLNTACC)

Client Account (CLNTACC) product suite supports the following:

  • Client account list - CLNTACC
  • Client account summary - CLNTACCSUM

The suite allows an initiating party to view a list of account types including the current balance and ANZSIC code.
The web service messages are exchanged using the ATO ebMS3 protocol with the message payload constructed using the XML format.


The Client Account (CLNTACC) product suite supersedes the Account List (ACCLST) web service and versions.

CLNTACC (2017)

Name Version number StatusSize Published date
ATO CLNTACC Package v0.1.1 Contents.docx 0.1.1 Draft 217KB 16 November 2017
ATO CLNTACC Package v0.1.zip 0.1 Draft 478KB 18 May 2017

Client Update (CU)

Client Update (CU) allows Tax Agents access to the following services:

  • Client update address - CUADDR
  • Client update details - CUDTL
  • Client update electronic contact details - CUEC
  • Client manage financial institution details - CUFI
  • Client update relationships - CUREL
  • Client update return not necessary - CURNN

The web service messages are exchanged using the ATO ebMS3 protocol with the message payload constructed using the XBRL format.

CUMASADD and CUMASCANCEL was Deactivated 01.07.2017

CU (2016)

Name Version number Status Size Published date
ATO CUADDR.0001 CUDTL.0001 CUFI.0001 CURNN.0001 CUEC.0001 CUMAS.0001 2016 Business Implementation Guide.docx 1.0 Final 249KB 8 December 2016
ATO CU 2016 Package v1.7 Contents.docx 1.7 Final 395KB 17 August 2017
ATO CU 2016 Package v1.7.zip 1.7 Final 1.0MB 17 August 2017

CU (2014) SUITE DEPRECATED

  • The CU 2014 suite of versions are deprecated and are no longer available to build against - product whitelisting is closed.
  • The actual deactivation dates can be found in the Service Registry.
  • For those in the build phase that are about to enter in to or have starting testing in EVTE, please contact your account manager for guidance.

Client Update Demographics (CUDEMOGR)

Client Update Demographics (CUDEMOGR) product suite allows Tax Agents access to the following services:

  • Client update address - CUADDR
    Note: the Client update electronic contact details (CUEC) has been incorporated into CUADDR
  • Client update details - CUDTL
  • Client update financial institution details - CUFI
  • Client update authorised contact - CUAUTHDCNTCT
  • Client update associates - CUASSOC

The web service messages are exchanged using the ATO ebMS3 protocol with the message payload constructed using the XML format.

CUDEMOGR (2016)

Name Version number StatusSize Published date
ATO CUDEMOGR 2016 Package v0.4 Contents.docx 0.4 Draft 251KB 21 September 2017
ATO CUDEMOGR 2016 Package v0.4.zip 0.4 Draft 3.28MB 21 September 2017

Client Update Relationships (CUREL)

Client Update Relationships (CUREL) suite allows Tax Agents access to the following services:

  • Client update relationships - CUREL
  • Client update search - CUSRCH

The web service messages are exchanged using the ATO ebMS3 protocol with the message payload constructed using the XML format.

CUREL (2016)

Name Version number StatusSize Published date
ATO CUREL 2016 Package v0.3 Contents.docx 0.3 Draft 235KB 18 May 2017
ATO CUREL 2016 Package v0.3.zip 0.3 Draft 1.02MB 18 May 2017

Client Update Manage Activity Statement roles (CUMAS)

This service allows a tax practitioner, Business or Intermediary to remove the following lodgment obligations against an existing AS role:

  • Goods and services tax (GST);
  • Luxury car tax (LCT);
  • Wine equalisation tax (WET);
  • Pay as you go – withholding (PAYG-W);
  • Fuel tax credit (FTC).

The web service messages are exchanged using the ATO ebMS3 protocol with the message payload constructed using the XBRL format.

CUMAS (2017)

NameVersion numberStatusSizePublished date
ATO CUMAS.0003 2017 Package v1.2 Contents.docx1.2Final240KB17 August 2017
ATO CUMAS.0003 2017 Package v1.2.zip1.2Final19.8MB17 August 2017

Direct Debit (DD)

Direct Debit (DD) service allows authorised parties to perform the following two functions:

1. DD Request

The request direct debit service provides the ability for a client's Tax Agent, a Business or their Business Intermediary to request the ATO to initiate a single direct debit of the client's nominated bank account. A Direct Debit Authority must already be in place with the ATO in order to use this service.

2. DD Cancel

The cancel Direct Debit service provides the ability for a Tax Agent, Business Intermediary or Business to cancel a previously requested single Direct Debit, but does not cancel the Direct Debit Authority.

DD.0002 (2016)

Name Version number Status Size Published date
ATO DD.0002 2016 Package v1.0 Contents.docx 1.0 Final 228KB 11 May 2017
ATO DD.0002 2016 Package v1.0.zip 1.0 Final 448KB 11 May 2017

DD.0001 (2015) DEPRECATED

  • The DD.0001 2015 version is deprecated and is no longer available to build against - product whitelisting is closed.
  • The actual deactivation date can be found in the Service Registry.
  • For those in the build phase that are about to enter in to or have starting testing in EVTE, please contact your account manager for guidance.

Deferral (DFRL)

The Deferral (DFRL) service allows Tax Agents and BAS Agents to submit a request for a deferral in relation to their client's lodgment and/or payment obligations.
The web service messages are exchanged using the ATO ebMS3 protocol with the message payload constructed using the XML format

DFRL.0002 (2018) - PENDING

DFRL.0001 (2016) was Cancelled 02.11.2017.

Income Tax Lodgment Status (ITLDGSTS)

The Income Tax Lodgment Status (ITLDGSTS) service will allow a Tax Agent to enquire into the status of a single client's income tax lodgment history. The income tax history returned will show the  lodgment status for the current tax year and previous three years history, the last year lodged, plus up to 16 years history where the status is not lodged.
The web service messages are exchanged using the ATO ebMS3 protocol with the message payload constructed using the XBRL format.

ITLDGSTS.0001 (2014)

Name Version number Type Size Published date
ATO ITLDGSTS.0001 2014 Business Implementation Guide.docx 1.0 Final 689KB 30 July 2015
ATO ITLDGSTS.0001 2014 Package v1.3 Contents.docx 1.3 Final 220KB 15 December 2016
ATO ITLDGSTS.0001 2014 Package v1.3.zip 1.3 Final 332KB 15 December 2016

Lodgment List (LDGLST)

The Lodgment List (LDGLST) service allows a consumer access to an account listing that includes:

  • list of expected due/overdue forms and payment dates
  • lodgment history

The web service messages are exchanged using the ATO ebMS3 protocol with the message payload constructed using the XML format.

LDGLST.0002 (2016)

Name Version number Status Size Published date
ATO LDGLST.0002 2016 Package v1.1 Contents.docx 1.1 Final 270KB 11 May 2017
ATO LDGLST.0002 2016 Package v1.1.zip 1.1 Final 141KB 11 May 2017

LDGLST.0001 (2014) was Cancelled 02.11.2017.

Payment Plan (PMTPLN)

The suite of Payment Plan (PMTPLN) services supports the following:

  • List Eligible Accounts allows an initiating party to a view list of accounts (or specified account) with their eligibility to payment plans, and to retrieve an active payment plan ID where one already exists.
  • Get Payment Plan allows an initiating party to request to view a payment plan for a specified payment plan ID.
  • Calculate Payment Plan allows an initiating party to calculate a payment plan for a specified account.
  • Submit Payment Plan allows an initiating party to submit a payment plan for a specified account.

The web service messages are exchanged using the ATO ebMS3 protocol with the message payload constructed using the XML format.

PMTPLN (2017)

Name Version number Status Size Published date
ATO PMTPLN.0002 2017 Package v0.1 Contents.docx               0.1 Final 238KB16 November 2017
ATO PMTPLN.0002 2017 Package v0.1.zip               0.1 Final 4.3MB16 November 2017

PMTPLN (2018) - PENDING

PMTPLN (2015) was Cancelled 19.10.2017. New service actions with additional features will replace this one at a future date. The new service will carry more accounts - Integrated Client Account, Income Tax Account, Fringe Benefits Tax Account, Superannuation Guarantee Employer & SGC Director Penalty Account.

Payment Reference Number (PRN)

The Payment Reference Number (PRN) service allows users to proactively manage their debt by providing the ability to generate a Payment Reference Number (PRN) details for available accounts and roles.

PRN

Name Version number Status Size Published date
ATO PRN.0001 2016 Package v1.0 Contents.docx          1.0        Final 214KB 16 November 2017
ATO PRN.0001 2016 Package v1.0.zip           1.0        Final 404KB16 November 2017
ATO PRN 2016 Business Implementation Guide.docx  1.0Final 224KB 16 November 2017

Private Ruling (PR)

The Private Ruling (PR) service provides Tax Practitioners, BAS Agents, Business and Business Intermediaries the function to submit a request for a Private Ruling to the ATO on behalf of a client or  a group of clients.

The pr.0001 service includes the capability to allow for  up to six unstructured attachments (each up to 10MB in size) to be sent with the message to support the application for private ruling.

PR

Name Version number Status Size Published date
ATO PR.0001 2015 Package v1.2 Contents.docx         1.2       Final   16 November 2017
ATO PR.0001 2015 Package v1.2.zip          1.2       Final   16 November 2017
ATO PR.0001 2015 Business Implementation Guide.docx   1.1Final  16 November 2017

Role List (ROLEST) - CANCELLED

ROLELST.0001 (2014) was Cancelled 02.11.2017. New service actions with additional features will replace this one at a future date.

Tax Practitioner Client Management Reports (TPCMR)

Tax Practitioner Client Management Reports (TPCMR) is a suite of services based on those currently available through the Electronic Lodgment Service (ELS) and provides the following:

1. Manage Report Subscription - allows for the addition or deletion of a subscription to the following report:

  • Electronic Funds Transfer Subscription (which enables the tax practitioner to receive the EFT reconciliation report which provides details of each EFT refund sent to the tax agent's or BAS agent's nominated trust account).

2. On Demand Report - allows for the request of a specific report to be generated. The following reports can be requested On Demand/ad-hoc basis:

  • Activity Statement Client - provides tax practitioners with information about their client's Activity Statement lodgments.
  • Activity Statement Lodgment - provides tax practitioners with information about their client's Activity Statement lodgments and relevant Document Identification number [DIN] information.
  • List Income Tax Return - provides tax practitioners with information about their client's income tax lodgments.

3. Get Report - allows the tax practitioner to retrieve a generated report that can include either a subscribed, compulsory or on demand report. In addition to the subscribed and on demand reports, the following compulsory report can be retrieved:

  • Income Tax Lodgment Performance Report - provides tax practitioners with statistical information regarding the status and number of tax lodgments lodged during a lodgment period. The generation of these reports to tax practitioners will be initiated by the ATO periodically or at specific points in time when required. Tax practitioners do not have the choice to opt-out from receiving compulsory reports.

The web service messages are exchanged using the ATO ebMS3 protocol with the message payload constructed using the XBRL format.

TPCMR (2017)

Name Version number StatusSize Published date
ATO TPCMR 2017 Package v0.1 Contents.docx 0.1 Draft 232KB 16 March 2017
ATO TPCMR 2017 Package v0.1.zip 0.1 Draft 851KB 16 March 2017

TPCMR (2014)

Name Version number Status Size Published date
ATO TPCMR 2014 Business Implementation Guide.docx 1.1 Final 509KB 17 March 2016
ATO TPCMR 2014 Package v1.3 Contents.docx 1.3 Final 242KB 21 September 2017
ATO TPCMR 2014 Package v1.3.zip 1.3 Final 805KB 21 September 2017

Transaction List (TXLST)

The Transaction List (TXLST) service will allow an initiating party to request the complete list of financial transactions based on the statement account view.  Transactions can also be requested based on normal or aggregate mode, account identifier, processed date, effective date and sort order.
The web service messages are exchanged using the ATO ebMS3 protocol with the message payload constructed using the JSON format.

TXLST.0002 (2016)

Name Version number Status Size Published date
ATO TXLST.0002 2016 Package v2.0 Contents.docx 2.0 Final 232KB 16 November 2017
ATO TXLST.0002 2016 Package v2.0.zip 2.0 Final 388KB 16 November 2017

TXLST.0001 (2014) was Cancelled 02.11.2017.

ATO Common Information Artefacts

The ATO has a number of documents that are common across all services and need to be read with any service specific artefacts.

Common artefacts are: 

  • ATO Service Registry (SR)
    The Service Registry lists all services and related messages offered over SBR Core Services and ebMS3 platforms. It also has dates when services are expected to be deployed into the External Vendor Test Environment (EVTE) and Production (PROD).
  • ATO Service Characteristics Risk Chart
    The Characteristics Risk Chart describes the way in which the ATO classifies APIs. This artefact needs to be read in conjunction with the Service Registry in order to understand how Risk Profiles have been allocated against Service Actions.
  • ATO Service Support Versioning Strategy
    The ATO Service Support Versioning Support PowerPoint outlines key concepts, life cycle states of a service, principles for supporting versions and the decommissioning process.
  • SBR ATO Site and Document Maps (SDMPS)
    The SBR ATO Site and Document Maps (SDMPS) spreadsheet contains site maps for ATO content on sbr.gov.au and SBR Share File (with links where possible),  ATO Acronyms/Initialisms with their full form name and the ATO High Level Document Map.
  • ATO Taxonomy Architecture and Naming Conventions
    The ATO Taxonomy Architecture and Naming Conventions document outlines the differences between ATO and SBR generated taxonomies, along with naming conventions for files.
  • ATO Common Business Implementation Guide (cBIG)
    The ATO Common Business Implementation Guide (cBIG) forms part of the broader suite of documents used by the ATO to describe the business context and client usage of the web services offered by the ATO through the SBR platform. The document also provides high level guidance and reference to additional documentation to assist software developers understand what is required at key points throughout the development lifecycle.
  • ATO Common Message Implementation Guide (cMIG)
    The ATO Common MIG (cMIG) forms part of the broader suite of documents used by the ATO to describe the way in which software developers must implement messages. In particular, it describes the ATO specific requirements to ensure those messages are both SBR and ATO compliant.
  • ATO Message Repository (MR)
    The ATO message repository (MR) contains the majority of ATO response messages. Some services have response messages packaged separately and these can be found within the service zip package.
  • ATO Taxpayer Declaration Guide (TPDec)
    This document provides guidance regarding the provision of taxpayer declarations in association with approved forms lodged to the ATO via SBR. It addresses the declaration to be given by the taxpayer to their tax agent prior to the Tax agents' submission of the approved form to the ATO. For further information about the declaration and signing statement made by a tax agent lodging via SBR refer to the ATO cMIG.
  • ATO XML Schema Generation Algorithm
    This document describes the algorithm used to generate XML Schemas from the Message Structure Table (MST) spreadsheet/s.  This algorithm will be applied to services produced from May 2017 onwards.
  • ATO Common Record Delimiter Validation Rules
    This document describes the validation that is applied to any message received in the eCommerce Bulk format.  These rules apply to messages received via the SBR2 platform or the ATO’s Bulk Data Exchange.  The format is covered in the ATO Common Message Implementation Guide.
NameVersion numberStatusSizePublished date
ATO Service Registry.xlsx2.05Living502KB2 November 2017
ATO Service Characteristic Risk Chart.ppt1.0Final144KB19 October 2017
ATO Service Support Versioning Strategy.docx1.1Final486KB31 August 2017
ATO Taxonomy Architecture and Naming Conventions.docx1.0Final233KB 31 August 2017
SBR ATO Site and Document Maps.xlsx2.0Final484KB31 August 2017
ATO Common Business Implementation Guide.docx0.1Draft766KB10 December 2015
ATO Common Message Implementation Guide.docx3.0Final2.48MB15 September 2016
ATO Message Repository.zip2.68Living305KB16 November 2017
ATO Taxpayer Declaration Guide.docx3.0Final290KB21 September 2017
ATO XML Schema Generation Algorithm.docx1.0Final261KB31 August 2017
ATO Common Record Delimiter Validation Rules.xlsx1.0Final56KB15 June 2017


SBR ebMS3 webservices artefacts

The Australian Taxation Office has developed an ebMS/AS4 implementation extending on the SBR initiative to simplify Business to Government reporting obligations and aligning with the messaging standards chosen for Superannuation Reform. While this implementation replaces the existing SBR message wrapping, it does not replace the eXtensible Business Reporting Language (XBRL) body provided in SBR web services, in fact the ATO implementation of the new system reuses the existing SBR XBRL message body for the majority of the services provided in the new format.

The following information describes how to implement web services consuming the ebMS3/AS4 messaging standard (SBR ebMS3). 

  • SBR ebMS3 web service implementation guide
    The SBR ebMS3 web service implementation guide (WIG) describes common technical components and services that are re-used by all business services. The common services include whole of government gateways that expose services and supports the protocol for message exchange, standard message types, standard response time service levels, standard message structures, a security token service, and a standardised approach to handling business error conditions and transport exceptions.

    There is a separate SBR Core Services WIG. 
  • SBR ebMS3 software developer kit guide
    The SBR ebMS3 software developer kit (SDK) guide identifies the key components and functionality that comprise the SDK solution. Some of these components are re-used from the previously released SBR Core Services SDK and hence the reader is pointed to the reference for existing documentation. For the new components, this document will outline the usage details and the API specification (where applicable).
NameVersion numberStatusSizePublished date
SBR ebMS3 Web Services Implementation Guide.docx1.5Final2.06MB16 March 2017
SBR ebMS3 SDK Developer Guide.docx1.3Final1.80MB18 June 2015


SBR Core Service webservice

The web services components that are available online include:

  • Web Services Description Language (WSDL) files
  • Web Services Implementation Guide (WIG) 
  • Web services policy files
  • Security token message samples
NameVersion numberTypeSizePublished date
SBR web services implementation guide (WIG)2.2dPDF1.5MB18 February 2016
SBR web services description language (Java)  12.1 KB28 March 2013
SBR web services description language (dotnet)  10.2 KB28 March 2013

Last updated: 16 Nov 2017
Page ID: 40951