Guidance for users wishing to access the public version of the API can be found in our article on Accessing PBS public data from the API.
Release notes for API updates can be found here.
On this page:
Accessing PBS Embargo data
Lodging an application via the HPP
Log into the HPP and navigate to the Applications tab from the Services page. For information on how to access the HPP, please view our article on Accessing the HPP.
Create an application by selecting 'New application' > 'Medicinal Products and vaccines' > 'Request access to PBS embargo data API'. Follow the prompts within the application to lodge the request.
Once your application has been approved, you will receive correspondence with the category Embargo API access details which can be accessed via the Correspondences tab on the Services page of the HPP. Your correspondence will include the following information:
Client ID
Client secret
Tenant ID
Scope
Access token endpoint URL
An example of the correspondence is shown in Figure 1.
Figure 1: Screenshot of the Embargo API access details correspondence
Accessing the Developer Portal
Navigate to the API catalogue and log into your Developer Portal account. When logging in, please ensure that you select the following options in the order indicated below. You must use the same digital identity that you used to access the HPP.
Important: Those who log into the developer portal before their access is approved will need to contact HPP.Support@health.gov.au to resolve issues with logging in caused by accessing the developer portal before having their access approved.
- Login with myGovID (Figure 2)
- Digital Identity and RAM (Figure 3) - Please ensure you select Digital Identity and RAM when accessing the developer portal. If you select Digital Identity only, you will need to contact HPP.Support@health.gov.au to resolve issues with logging in.
- Select myGovID (Figure 4)
Figure 2. Screenshot of Developer Portal sign in options with 'Login with mygovID' highlighted
Figure 3: Screenshot of Health Authentication Gateway with Digital Identity and RAM selection highlighted
Figure 4: Screenshot of Digital Identity page showing 'Select myGovID' option
To view all available embargo APIs, including deprecated versions, navigate to the API catalogue and select 'View APIs' while logged in. This page will display the current and previous versions of the API. Select the latest version of the API to view the endpoints. From this page you can:
Set the version
Select the relevant table
Retrieve the API endpoint
Figure 5 shows the API page in the Developer Portal, with guidance on actions that can be performed on this page.
Figure 5: Screenshot of the Developer Portal 'API' page
Note: This process presumes you have access to Postman which is a separate application.
Within the desktop or browser version of Postman, open a new tab by clicking '+' at the top of the window shown in Figure 6.
Figure 6: Screenshot of the ‘+’ button
This will bring up a blank request as shown in Figure 7.
Figure 7: Screenshot of a blank request in Postman with ‘Enter request URL’ highlighted
Within this page, paste your Access token endpoint URL (item 5 in Figure 1) into the 'Enter request URL' field as shown in Figure 7.
Navigate to the 'Body' tab and select the radio button for ‘form-data’ as shown in Figure 8. This will display the KEY and VALUE columns.
Figure 8: Screenshot of Body tab with ‘form-data’ radio button highlighted
In the KEY column, type in 'client_id', 'client_secret', 'scope' and 'grant_type' as shown in Figure 9.
Figure 9: Screenshot of Body tab with KEY column highlighted
- In the corresponding rows within the VALUE column, enter your Client ID, Client secret and Scope from your correspondence (shown as items 1, 2 and 4 in Figure 1) into the VALUE column as shown in Figure 10.
- Manually enter 'client_credentials' into the VALUE column for 'grant_type' as shown in Figure 10.
Figure 10: Screenshot of Postman with credentials entered
- Once input, hit 'Send'. This will generate the Access token as shown in Figure 10.
- Select and copy this as indicated in Figure 10. Please note that your access token will only last an hour once it has been generated.
Using an access token to access the API
Open a new tab in Postman once more (Figure 6) and enter the request URL for the API. This can be obtained from the Developer Portal in the API tab. Refer to item 4 as shown in Figure 6 to locate the URL. Please note that you should exclude everything from ‘[‘ to ‘]’ at the end of the URL.
Within the Authorization tab, ensure the Type is set to Bearer Token and paste the access token copied from the Postman ‘Post’ page, as described in step Obtaining an Access token through Postman. The location of fields that need to be populated is shown in Figure 12.
Figure 12: Screenshot of Postman 'Get' page and where to input the API URL, Bearer Token and Access Token
Navigate to the Header tab and manually type ‘subscription-key’ into the KEY column and in the VALUE column insert the subscription key (primary or secondary) retrieved from the Developer Portal in step Generating a subscription key(see Figure 3 for further details). Figure 13 provides guidance on the field that needs to be populated with the subscription key.
Figure 13: Screenshot of Postman 'Get' page and where to input the subscription key
Once completed, select send. This will return the PBS Embargo data from the requested endpoint.
Frequently asked questions
Access
What are the proof of identity requirements to access the HPP? Can a non-Australian user access the HPP?
myGovID 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 myGovID 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 myGovID 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.mygovid.gov.au/set-up
How do I set up an account in the HPP and link it to my organisation?
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.
I selected Digital identity rather than Digital Identity and RAM when logging into the Developer Portal. How I can fix this to be able to access the PBS Embargo Data?
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.
Will I need to log into the HPP to request access to the public API once it's released?
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 Department is working on a version of the API that will be made available to the general public which will not have any identity requirements. This version of the API will only contain data after it has been made effective in legislation.
Where can I find recordings of the webinars?
Recordings of our webinar series on accessing the PBS Embargo Data API can be located on the PBS Data Distribution Project page.
How can I get system API access credentials for my business solution?
You are unable to register a system for access to the API, as an individual person needs to accept the terms and conditions and be accountable for the appropriate use of the credentials.
Our suggestion is that the 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.
When do my API access credentials expire?
API access credentials expire annually for an organisation, based on the anniversary of the first application for access on behalf of the organisation. All representatives for the organisation will need to re-apply through the HPP to receive a new set of access credentials. API users will receive a reminder correspondence through the HPP, 30 days before the expiry date.
API/schedule updates
Once we have applied the Summary of Changes, how will we be notified of revisions to the current schedule and how should these be applied?
A revision to a schedule results in a new schedule, with a new schedule code and a new data record in the schedules endpoint.
So 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.
Will the Summary of Changes include updates to the SCHEDULE_T table?
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.
How does the design handles intra-release changes?
The cadence of release will follow the current XML data file release process, that is new files will be released on a monthly basis.
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.
How are API versions / deprecations being supported?
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 1 of an endpoint may have the URL:
https://data-api.health.gov.au/pbs-embargo/api/VERSION1/<endpoint>
whereas Version 2 of that endpoint may be given the URL:
https://data-api.health.gov.au/pbs-embargo/api/VERSION2/<endpoint>
The URL names allocated to endpoints are specifically referenced on the relevant Swagger documentation page under the Request heading.
Data
Why is there a variation in private hospital, public and community pharmacy dispensing rule values (DPMQ, brand premium, etc.) for a single item in a schedule?
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.
Can the API be downloaded as a JSON or CSV?
The PBS DDS 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.
How can the API be filtered by PBS code and program?
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/VERSION2/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.
Can the API be implemented into Users systems?
To make the transition of receiving systems as simple as possible, the PBS DDS API system has been designed to effectively emulate the existing XML 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. 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.
How are Restrictions stored in the API data?
A resource is available to assist with piecing together restriction fragments. Please note the attachments are subject to updates, the latest copy is available via the link in the Attachments section below.
Data model
Am I able to access schema scripts to set up a data base to match the data model provided?
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.
What is the approach in the model for schedules and SoC?
The PBS APIs have 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.
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.)
Existing documentation and resources
Can I continue to access the existing public and embargo PDFs?
PDFs will not be impacted by this project and will continue to be made available in their current locations.
Can I use the existing PBS API instead of the Data Distribution Project API?
This API has been available for a while, the data available through it is not comprehensive and is based on a development environment; it cannot be relied upon to be current. Public access to this API will be discontinued after the release of the public version of the PBS data API.
Can I continue to access the CARS item list and Chemotherapy Compounding Payment Scheme data through existing embargo access?
The process of accessing this information will not change.
Generating text files
How can I obtain unformatted text for restrictions rather than HTML?
The restrictions in the API are in 2 formats:
- The HTML versions. If you don’t need the HTML tags, you could strip them out in your code.
- 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 here: Accessing PBS Embargo data via the API · Health Products Portal (link at the bottom of the page piecing together restriction fragments)
How can I filter the ATC data so that we identify a single correct ATC_CODE, when there are multiple ATC_CODES linked to a PBS_CODE for the same PROGRAM_CODE and MANUFACTURER_CODE?
You will need to join the ATC table to the ITEM table via ITEM_ATC_RLTD_T.
- 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.
- 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.
- 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.
Is there is a way to find PBS codes for a medication package using the package’s CTPP code (Containered Trade Product Pack) or AusDI code?
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).
Am I able to access documentation to map the new database against the existing XML 3?
This is not currently available and we are unable to provide an estimation on when it can be made available.
Is it possible to see an example of a larger extract through postman?
A sample CSV export file is publicly available for download from the PBS Data Distribution Project page.
Where can I find a specific text file in the API?
There is not a 1 for 1 association between individual text files and API endpoints.
At the following link, you will find a data dictionary, ER diagram and an explanatory document that describes the mapping from the API to the text files: https://hpp.health.gov.au/article-details/?id=a1ea613e-f07e-466a-97be-361967b33cf4#API_data_model_and_data_dictionary
Broadly (there are significant differences), the drug text file is similar to the items API endpoint
Why can't I find the TPUU AMT IDs?
TPUU and Health namespace identifiers have been deliberately removed from the AMT data in the API, the Department does not intend to publish these in future. As a result, a small number of items in the API may not have any AMT data in the API. TPP identifiers are in the AMT data in the API.
These should be able to be used to derive TPUU identifiers, through the AMT.
Information on known issues can be accessed here.
API data model and data dictionary
The following attachments are subject to updates, the latest copy is available via the following links.