Skip to main content

APIs for Online Digital Services

FAQs

You can find frequently asked questions for the APIs for Online Digital Services below.

What is the difference between Deprecation and Decommission?

Deprecation occurs when an API is superseded and it becomes the ‘n-1’ version. Decommission occurs when an API version is not operational and is no longer supported. Existing consumers of the deprecated version will have up to 24 months from the date of deprecation to upgrade to the newer version of the API. During that period, the deprecated API version will continue to be supported with minor enhancements.

When will Online DA v1 API get deprecated and decommissioned?

The Online DA V2 was released in March 2021, thus the Online DA V1 became deprecated from that date. The Online DA V1 decommissioning date will be revisited based on the councils’ readiness to switch to Online DA V2 and the date will be published by the Department soon.

What is the deprecation cycle?

The original deprecation cycle was 12 months, however the Department has updated it to 24 months following the feedback that we received from some councils and vendors. 

How do I consume the Online Digital Service APIs in the User Acceptance Testing (UAT) environment?

Email us at [email protected] with the organisation name to configure and then we will share the API key for that organisation. This key is specific to that organisation and has to be passed as part of the header to authorise an organisation’s access.

How do I receive the newly created application requests to an organisation in UAT?

We need to enable the corresponding Organisation (e.g. Council, Private Certifier or State Agencies) and then set up the organisation's endpoint in the system. The dedicated team ([email protected]) has to be notified with the endpoint and basic authentication details.

How do I set up a council user for any particular council in the NSW Planning Portal?

Register as a council user in the NSW Planning Portal and then share the approval from the council to enable the particular account as a council user to the dedicated team ([email protected]).

How do council systems receive updates to an Online DA application?

For V1, any updates to the application, the team pushes the updates to councils via the CreateDA method, and it is up to the council on what to do with the updates. In V2, the team pushes the updates to councils through the UpdateDA method.

Can councils provide the department with separate endpoints to receive the Online DA payload and for supplying the documents to the department?

No, all three Online DA API methods exposed by the Council system: CreateDA, UpdateAdditionalInfo and Documents, must be exposed from a single endpoint.

How do I report an API bug? 

Please report the bug with the details into our JIRA system. Please click here to access the Jira.

If you require access to JIRA board, please send an email to  [email protected] 

How do I get a status on the logged bug?

Please access our JIRA portal to view the bug status. Only registered users can access the JIRA portal. Please click here to access the JIRA.

What can be done when an applicant provides additional information and it results in duplicate documents being sent? 

For applicant-attached documents, please differentiate based on the document name and the uploadedTimeStamp for each document category.

For council-attached documents, please differentiate based on the document name for each document category.

Please note: If an applicant attaches the same document name as the existing council document name, then our application automatically recognises the existing name and differentiates the new file by appending '_V1' for each document category. For example, if the council document name is 'document1.pdf', then, in this scenario, the new applicant document name will be 'document1_V1.pdf'.

What is the information required for setting up a private certifier organisation account with the department?

Please provide the following information in an email to [email protected]:

  • Registered Address
  • Postal Address
  • Email of Organisation
  • Phone Number
  • Organisation Name
  • ABN Details

What information does the department need from stakeholders to enable the flow of data from the NSW Planning Portal into their IT systems?

The Planning Portal supports Basic and OAuth authentication mechanisms.

Depending on your preferred approach, you can provide either of the following to DPE at [email protected].

(1) Basic Authentication

  • Username and password
  • Endpoint URL

(2) OAuth 2.0 (Grant Type: Client Credentials, Password Credentials only)

Client Credentials

  • Client ID
  • Client Secret
  • Access Token URL
  • Endpoint URL

Password Credentials

  • Username
  • Password
  • Client ID
  • Client Secret
  • Access Token URL
  • Endpoint URL

What is the API throttling limit?

The throttling limit is 150 calls per 60 seconds.

What happens when the throttling limit is exceeded?

When the throttling limit is exceeded an HTTP 429 status code is returned to the API consumer.  They will then need to retry after 60 seconds.

What is the Integration retry mechanism?

In the event of server-related errors, like 5XX error codes that represent server outages or maintenance, retries will be triggered.

The current retry count and intervals are:

Scenario Retry Count
API connectivity fails for the first time 1
After 30 minutes of first retry 1
And then every 2 hours until 24 hours 1

However, the retries will not be triggered for any client-side data errors except for time out errors (Error code – 408).

What is the process for handling retry failures for the APIs?

If, after 24 hours, the retry process is unsuccessful it will be moved to the dead letter queue. The following options can be used if the user wants to re-attempt the process for the same case:      

1.    Approach the API team to manually retrigger the same event.

2.    In the case of ‘create event’ failures, login to the user interface to trigger a resend option. Alternatively, by triggering the Getcaseinfo API, create details can be resent to the Planner’s IT system.

How can the documentation site be best used for a given service?

For any digital service, you can access the below artefacts from the NSW Planning Portal site by navigating to the API Reference Documents page.

  1. Workflow diagram – This is a visual layout of the business process indicating the relevant APIs involved in each of the business processes.
  2. Common APIs – List of APIs that can be leveraged across multiple digital services to achieve any type of common administrative functions e.g. requesting additional information. The Common API Dependency matrix is available for all applicable operations.
  3. Operations List for digital services - To get the overview of any specific operation related to any specific digital service.
  4. Payload samples - Request and Response samples for all the operations.
  5. API Versioning policy - To get the API versioning policy details.
  6. Release notes – The release notes document the changes/enhancements made to APIs.
  7. Schema changes - For every release, schema changes are updated in a spreadsheet that represent the changes.

Where can I fetch the values for attributes like development and document types that are used in digital services?

We are currently developing API reference documents that will be used to access all the reference data.

Until then, please reach out to our support team: email [email protected] for the latest reference data.

Further assistance 

If you require assistance using the NSW Planning Portal APIs, and you were unable to find the answer on this page, please contact the ePlanning Integration Team.

Last updated: 13/03/2024