PBS API - Frequently Asked Questions

Yes, the application process for the API is different to the previous embargo application process. Once you have been granted API embargo access you will also receive access to the embargo section and Developers Discussion Board.

The API application process is now the only way to obtain embargo access.

myID and RAM are whole of Australian government services, for identification of businesses (and their representatives). Companies that do business in Australia already need this information in order to interact with other Australian government services, for example the Australian Taxation Office.

To get started, your business will need an Australian Business Number (ABN), and the principal authority of the business will need to have proof of identity to get a myID with a ‘strong’ or 'standard' identity strength. This principal authority person needs to have an Australian passport, plus other Australian identity documents. Details of principal authority are available here: https://info.authorisationmanager.gov.au/principal-authority

Other representatives of your business will only require a ‘basic’ or ‘standard’ identity strength myID to access the HPP and apply for access to the API. These people need less identity proof. For example, a ‘basic’ identity strength requires no identity evidence and could therefore be a person of any nationality.

The various levels of identity strength has requirements defined on this page: https://www.myid.gov.au/how-set-myid

Information on establishing a profile in the HPP can be found in the article on Accessing the HPP. Further information on registering an organisation in the HPP can be found in the article on Registering an organisation in the HPP and information on linking accounts can be found in the article on Managing members.

If you signed in to the developer portal using Digital Identity rather than Digital Identity and RAM or before your application was approved, please email HPP.Support@health.gov.au so that we may assist.

Lodging a request to access the API is only a requirement for access to the PBS data API for data that is under embargo (i.e. made available by the Department in advance of the data being made effective in legislation). The Public API does not have any identity requirements. This version of the API only contains data after it has been made effective in legislation.

Recordings of our webinar series on accessing the PBS Embargo Data API can be found on the PBS Data Distribution page.

You are unable to register a ‘system’ for access to the API, an individual person needs to accept the terms and conditions and be accountable for the appropriate use of the credentials.

API credentials you use in production should be associated with the person in the organisation that is accountable for the production system and its compliance with the terms and conditions.

Embargo API access credentials expire annually for organisations based on the anniversary of the first application for access.

Organisations will receive a correspondence 45 days before the upcoming expiry of the Embargo API access with a call to action to confirm which existing users need to retain access to the Embargo API (Figure 1). If the organisation responds within 15 days, their access will be renewed automatically and they will not need to re-apply for renewal via the Health Products Portal (HPP). 

The new Client Secret for Embargo API Access will be shared with organisations via another correspondence (Figure 2). The new Secret will be valid for 12 months from the old Secret expiry date and will need to be updated for all individuals. Organisations can update their system with a new Secret anytime until the old one expires. 

If the organisation does not respond within 15 days, their access will expire. They will need to reapply via the HPP. 

Figure 1: Screenshot of correspondence advising of upcoming expiry

Figure 2: Screenshot of correspondence with automatically renewed Secret

Figure 3: Example Secret renewal timeline

A revision to a schedule results in a new schedule, with a new schedule code and a new data record in the schedules endpoint. Please note: The Schedule code does not necessarily advance sequentially, so cannot be assumed that highest number will always be the most recent version.

In a given embargo period there could be more than one schedule for the coming month and you can use the revision number to identify the order in which they were released.

An email will be sent to all embargo data users (as per existing process) when a new schedule is released. Additionally, you can set up your system to periodically (e.g. daily) poll the schedules endpoint if you want to implement an automated method of identifying new data.

Changes to the Schedule table are not part of the Summary of Changes.

There has never been any intention to include the Schedule table as part of the Summary of Changes reporting as the only changes that will occur are insertions of new Schedule records, and the deletion of the schedule records more than twelve months in age.

The embargo API will be released on a monthly basis, approximately two weeks before the effective date. The Public API will be released on the effective date (first day of the month).

Where the need arises for an additional release of data, a new Schedule number will be created, and the API data will be refreshed with all relevant data for that Schedule, in much the same way as a normal release occurs currently.

The Summary of Changes endpoint will reflect the data changes between Schedules in the same way.

Like any system, changes may be required to introduce new improvements or remedy a previous error. To ensure that users are not inconvenienced by sudden changes to the API endpoints, previous (or deprecated) versions of the API endpoints will still be available for a period following a new release of updated endpoints.

Access to the current and previous versions of the API endpoints will be controlled through changes to the of URLs of the endpoints themselves.

As an example, Version 3 of an endpoint may have the URL: https://data-api.health.gov.au/pbs-embargo/api/VERSION3/<endpoint>

The URL names allocated to endpoints are specifically referenced on the relevant Swagger documentation page under the Request heading.

This variation is quite correct in terms of the data itself.

Across the brand premium values appearing in the API for the Community Pharmacy, the Public and Private Hospital dispensing rules; there is often a higher value for Brand Premium occurring in the Private Hospital dispensing rules, mostly for non-S100 drugs.

The data shown on the PBS website and appearing in the text files are the values associated with a single set of dispensing rules, typically the Community Pharmacy dispensing rule.

The PBS API endpoints have been developed to enable data to be received in either JSON (JavaScript Object Notation) or CSV (Comma Separated Values) format.

This is achieved by using the Accept parameter in the API Get statement header. For JSON use Accept = application/json (this is the default); for CSV use Accept = text/csv.

In Postman, this is achieved by setting an Accept key in the Headers tab. Once the data has been received, the file can be downloaded and saved.

Note: Some endpoints can not be downloaded in CSV due to the complexity of the endpoint. Eg Summary of changes.

The API endpoints have been created with ease of use in mind, and the amount of data that can be requested can be refined using a series of parameters specific to each endpoint.

These are documented on the Swagger page for each endpoint under the Request Parameters header.

Filtering of the data can be achieved by adjusting the Get statement to include the relevant parameter.

e.g. for the Items endpoint, requesting a specific Schedule would look similar to this:

https://data-api.health.gov.au/pbs-embargo/api/VERSION3/items?schedule_code=1234

Using a tool, such as Postman, this can be achieved by adding an entry to the Query Params list. The tool will then automatically add the parameter to the Get statement executed.

To make the transition of receiving systems as simple as possible, the PBS API system has been designed to effectively emulate the previous embargo data file download system as closely as possible.

The intended operation is for end users to access the API endpoints and retrieve all data associated with a Schedule in one request and download that file to local storage ready for upload into their own systems/databases.

To ensure a higher level of stability of the API system, a limit of one request per second has been implemented for the embargo API. The Public API is rate-limited to one request per twenty seconds. This limit is shared amongst all concurrent users of the PBS public API. The system has not been designed as a high-volume real-time system, but rather as a data storage and retrieval system to enable software vendors and users the ability to download and store local copies of the data.

A resource is available to assist with piecing together restriction fragments. Please note the attachments are subject to updates, the latest version is available via in the Resources section of the PBS API page. 

The database model that the API is based on is the same as the diagram and data dictionary that are provided on the HPP website. We do not provide the schema scripts (e.g. DDL) as unfortunately each database technology (and sometimes version of the database) uses slightly different syntax. Therefore, the Department has decided to not provide schema scripts, given the effort required in producing (and supporting) so many variations.

The PBS API has been built in concert with a Physical Data Model that represents a de-normalised view of the PBS to assist with easier consumption of the data. Each endpoint represents one of the tables displayed on the data model.

A complete set of data is pushed into the API system when a new monthly Schedule is released. The Schedule API contains the records associated with all available data in the API system. The Schedule number appears on every endpoint and is used to link all relevant data records together. Please note: The Schedule code does not necessarily advance sequentially, so cannot be assumed that highest number will always be the most recent version.

The Summary of Changes endpoint contains the records relating to the events for specific pieces of data (i.e. endpoint/field) relating to any changes that have occurred between the current and previous schedules. For instance, if an Item’s Claimed_Price has been updated then a record will appear in the current Schedule’s data that shows the change and includes the actual SQL statement that can be applied to the previous Schedule’s data to create the current version of that field.

By applying all changes held in the Summary of Changes endpoint for the current schedule against the data from the previous schedule, a User can recreate the current schedule’s data.

The SQL statements contained in the Summary of Changes are produced in SQL Server syntax and can be applied to the data using the following process:

Data for the previous Schedule is loaded into a database. (Can be achieved by downloading all endpoint data for the previous Schedule and uploading into an empty database)

All values of the Schedule_Code are updated to reflect the current Schedule_Code.

The SQL statements for the current Schedule can then be applied. (Though care must be taken to apply changes in the most logical sequence to ensure primary key/foreign key constraints are maintained).

The PDF versions of the PBS Schedule will not be impacted by the API and will continue to be made available in their current locations.

This PBS Publication API and API Offline that have been available since 2015 will soon be decommissioned, users will need to migrate to the new PBS API as soon as possible.

The process of accessing this information is not changing at this time.

The restrictions in the API are in 2 formats:

1. The HTML versions. If you don’t need the HTML tags, you can strip them out in your code. Information can be found on the known issues page. 
2. The restriction fragments, which store each restriction in its individual phrases (without HTML), including data attributes required to piece the phrases together in the right order. There’s a guide on how to do this in the Resources section.

You will need to join the ATC table to the ITEM table via ITEM_ATC_RLTD_T.

1. This ITEM_ATC_RLTD_T table is necessary as there is actually a many:many relationship between ITEM and ATC in the PBS. The conversion of the PBS data to text files simplified this relationship – it is one of the examples why the text files are no longer fit for purpose and are being replaced with the API.
2. The column ATC_PRIORITY_PCT in ITEM_ATC_RLTD_T is important to understand the multiple ATC values. This column shows the percentage to which each PBS item is associated with an ATC code. And for each PBS item, the values will add up to 100.
3. If you want to select just the primary ATC code for an item, you could select the one with the largest ATC_PRIORITY_PCT value. Note, depending on your use-case for the data, this may (or may not) be an acceptable generalisation.

CTPP information isn’t available directly. There is AMT information down to the TPP level in the API which could be used to look-up the TPP parent for a CTPP. However, the subsidy for an item on the PBS is for a combination of a Program with a TPP (drug, form, strength, pack size). The PBS is indifferent to the container (if the medicine is packaged as a blister pack or bottle of tablets, the subsidy is the same).

This is not currently available. Please reach out to HPP support with any questions.

There is not a 1 for 1 association between individual text files and API endpoints.

In the Resources section you will find a Data Dictionary, ER diagram and an explanatory document that describes the mapping from the API to the text files.

Broadly (there are significant differences), the ‘drug’ text file is similar to the ‘items’ API endpoint.

Please be aware that the Department does not endorse the current text files​​

• The current text files are no longer fit for purpose, they have become an over-simplification of the PBS. ​
• The API has been developed with a view that different end users can seek to obtain only the data they specifically need (e.g. prescribers might not need pricing information but need to access other information for the purpose of prescribing). ​
• New documentation with better SQL matching outputs to the current text files will be published soon. Please note that these SQL queries are for reference purposes only to help identify relationships between text files and the API data. Not designed to be use as your end product solution. ​
• Some show differences due to extra white spaces in the middle or at the end of sentences. This issue is consistent with the PBS data, where spaces or returns are displayed as spaces.​

Information can be found on the known issues page. 

TPUU and PBS non AMT information will be added to the API in a future release.