Australia Post Endpoints API
The Endpoints API from Australia Post — 9 operation(s) for endpoints.
OpenAPI Specification
openapi: 3.0.1
info:
title: Delivery Partner Endpoints API
description: This API allows Australia Post partners to submit delivery events to Australia Post.
version: 1.3.0
x-short-desc: An API for Australia Post delivery partners.
x-api-key: delivery-partner
x-gateway-type: GATEWAY
x-api-id: delivery-partner_v1.3.0-rev.5
servers:
- url: https://digitalapi.auspost.com.au/delivery-partner
security:
- ApiKeyAuth: []
tags:
- name: Endpoints
paths:
/api/v1/event:
post:
tags:
- Endpoints
summary: Sends the delivery event to Australia Post
description: Accepts Tracking Events which have resulted in a notification being sent by a delivery partner and which AP are to be informed of.
operationId: event
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EventVO'
required: true
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/EventVO'
x-info:
pathLabel: Sends the delivery event to Australia Post
/points/postcode/{postcode}:
x-info:
pathLabel: points by postcode
get:
tags:
- Endpoints
summary: getPointsByPostcode
description: This endpoint returns a list of all Australia Post points within a specific post code area. You can filter your results using the types parameter.
operationId: getGeoLocationsByPostCodeUsingGET
parameters:
- name: postcode
in: path
description: A four-digit Australian postcode.
required: true
style: simple
explode: false
schema:
maximum: 9999
minimum: 0
type: integer
- $ref: '#/components/parameters/pc'
- $ref: '#/components/parameters/usage_types'
- $ref: '#/components/parameters/types'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PointsResponse'
examples:
multiple-points-returned-of-different-types:
$ref: '#/components/examples/multiple-points-returned-of-different-types'
/points/workcentres/{work_centre_id}:
x-info:
pathLabel: points by workcentreid
get:
tags:
- Endpoints
summary: getPointsByWorkCenterID
description: "This endpoint returns a list of all points associated with a specific Australia Post work centre's. You can filter your results using the types parameter. \n \n A work center is a unique numeric identification code that represents a parent Australia Post facility, and all of the child point objects (assets or facilities) associated with it. The facility and its point objects all share the same work_centre_id, but each point is unique."
operationId: getGeoLocationsByWcidUsingGET
parameters:
- name: work_centre_id
in: path
description: See the endpoint description above.
required: true
style: simple
explode: false
schema:
maximum: 999999999
minimum: 0
type: integer
- $ref: '#/components/parameters/pc'
- $ref: '#/components/parameters/usage_types'
- $ref: '#/components/parameters/types'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PointsResponse'
examples:
multiple-points-returned-of-different-types:
$ref: '#/components/examples/multiple-points-returned-of-different-types'
/points/deliverypoints/{delivery_point_id}:
x-info:
pathLabel: points by deliverypointid
get:
tags:
- Endpoints
summary: getPointsByDeliveryPointId
description: This endpoint returns a list of all points associated with a specific Australia Post delivery_point_id. You can filter your results using the types parameter. A delivery_point_id is a unique numeric identification code that represents a point to which Australia Post delivers or receives deliveries.
operationId: getGeoLocationsByDeliveryPointIdUsingGET
parameters:
- name: delivery_point_id
in: path
description: See the endpoint description above.
required: true
style: simple
explode: false
schema:
maxLength: 9
type: string
- $ref: '#/components/parameters/pc'
- $ref: '#/components/parameters/usage_types'
- $ref: '#/components/parameters/types'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PointsResponse'
examples:
getPostOfficeByDeliveryPointId:
$ref: '#/components/examples/single-po-returned'
/points/{location_code}:
x-info:
pathLabel: points by location code
get:
tags:
- Endpoints
summary: getPointsByLocationCode
description: This endpoint returns a list of all points associated with a specific Australia Post location_code. A location_code is a unique alphanumeric identification code that represents an Australia Post facility.
operationId: getPointsByLocationCodeUsingGET
parameters:
- name: location_code
in: path
description: See the endpoint description above.
required: true
style: simple
explode: false
schema:
type: string
- $ref: '#/components/parameters/pc'
- $ref: '#/components/parameters/usage_types'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PointsResponse'
examples:
getPostOfficeByLocationCode:
$ref: '#/components/examples/single-po-returned'
/points/type/{points_type}:
x-info:
pathLabel: points by location code
get:
tags:
- Endpoints
summary: getPointsByType
description: This endpoint returns a list of all points associated with a specific Australia Post point_type
operationId: getPointsByTypeUsingGET
parameters:
- name: points_type
in: path
description: "The point's type. There are six of these enumerated values, to select from: \n * UPL: Parcel lockers. \n * R_SPB: A red street post box. \n * C_SPB: Combined street post boxes (Both red and yellow boxes together). \n * PO: An Australia Post outlet. \n * OS: Outstation (These are a part of a post office not in the same physical building. For example, a separate building dedicated to PO boxes.) \n * DC: A delivery centre."
required: true
style: simple
explode: false
schema:
type: string
enum:
- PO
- UPL
- R_SPB
- C_SPB
- OS
- DC
- $ref: '#/components/parameters/pc'
- $ref: '#/components/parameters/usage_types'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PointsResponse'
examples:
getPostOffices:
$ref: '#/components/examples/single-po-returned'
/points/geo/{longitude}/{latitude}:
x-info:
pathLabel: points by long and lat
get:
tags:
- Endpoints
summary: getPointsByGeoCoordinates
description: This endpoint returns a list of all Australia Post points within a given range of the coordinates provided. Results are ordered by the distance field, from closest to farthest away. You can filter your results using the various parameters shown below.
operationId: getGeoLocationsUsingGET
parameters:
- name: longitude
in: path
description: A coordinate representing the angular distance in degrees, minutes and seconds, of a point east or west of the Greenwich Meridian, expressed as a double.
required: true
style: simple
explode: false
schema:
type: number
- name: latitude
in: path
description: A coordinate representing the angular distance in degrees, minutes and seconds, of a point north or south of the equator, expressed as a double.
required: true
style: simple
explode: false
schema:
type: number
- $ref: '#/components/parameters/pc'
- $ref: '#/components/parameters/usage_types'
- name: radius
in: query
description: The radius in kilometres, to search around the provided latitude/longitude coordinate point. The default value is 50, and the hard limit is 1000Km.
required: false
style: form
explode: true
schema:
maximum: 1000
minimum: 0
type: integer
- name: services
in: query
description: 'A comma-delimited string of service codes by which to filter the returned list of matching locations. **Note: ** A list of current services is available through the getServices endpoint.'
required: false
style: form
explode: true
schema:
type: string
- name: limit
in: query
description: The maximum number of results to return. The default value is 5.
required: false
style: form
explode: true
schema:
maximum: 10000
minimum: 0
type: integer
- $ref: '#/components/parameters/types'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PointsResponse'
examples:
multiple-points-returned-of-different-types:
$ref: '#/components/examples/multiple-points-returned-of-different-types'
/services:
x-info:
pathLabel: services
get:
tags:
- Endpoints
summary: getServices
description: This endpoint returns a list of all available services. The service code in each returned service object can be passed as a parameter when calling getServicesByServiceCodes or getPointsByGeoCoordinates endpoints.
operationId: getServicesUsingGET
parameters:
- $ref: '#/components/parameters/pc'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
services:
type: array
description: "An array of service objects. A service object is a data structure returned from calls to the /services endpoint, and represents an Australia Post service that might be available at one of its outlets or facilities. There are no parameters by which to filter the service objects returned from the /service endpoint. \n \n **Note:** Not all outlets and facilities offer all services, and the number of service objects returned may change if Australia Post increases or decreases the number of services it offers."
items:
type: object
properties:
description:
type: string
description: The name of the service.
name:
type: string
description: The name of the service expressed as an enumerated value.
appointment_required:
type: boolean
description: A value indicating if a customer must first make an appointment for the requested service.
categories:
type: array
description: An array of objects that describe the service category to which a specific service belongs.
items:
type: object
properties:
description:
type: string
description: The URL-encoded equivalent of the name field.
name:
type: string
description: The name of the service category to which a service belongs.
description: This object contains the name of a service category used to group services of a similar type.
searchable:
type: boolean
description: A value dictating whether or not a specific service will be presented in the response to a service query.
partner_code:
type: string
description: A code to identify the owner entity of the assets, facilities or services referred to by the location_code. This value is currently always "AP" (Australia Post), however, this may be expanded in future to include other entities.
service_code:
type: integer
description: A unique number identifying a specific service that is available at a location. For example, "99" that identifies the PostBillPay service.
format: int32
url_name:
type: string
description: The URL-encoded equivalent of the description field.
description: "A Service object describes a specific service that might be available from an Australia Post outlet or facility. **Note:** \n Not all outlets and facilities offer all of the services returned by the getServices endpoint."
examples:
example1:
summary: Parcel collection outside standard hours
value:
services:
- service_code: 1
partner_code: AP
name: parcel-pickup-outside-standard-hours
description: Parcel collection outside standard hours
appointment_required: false
searchable: false
url_name: parcel-pickup-outside-standard-hours
categories:
- name: opening_hours
description: Opening hours
- name: parcels_mail
description: Parcels & mail
/services/{service_codes}:
x-info:
pathLabel: services by service codes
get:
tags:
- Endpoints
summary: getServicesByServiceCodes
description: 'This endpoint returns an array of services based on a comma-delimited list of service codes supplied in the request. **Note: ** A list of all current service codes is available from the getServices endpoint.'
operationId: getServicesByServiceCodesUsingGET
parameters:
- name: service_codes
in: path
description: A comma-delimited list of service codes by which to filter the returned list of matching locations.
required: true
style: simple
explode: false
schema:
type: string
- $ref: '#/components/parameters/pc'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
services:
type: array
description: "An array of service objects. A service object is a data structure returned from calls to the /services endpoint, and represents an Australia Post service that might be available at one of its outlets or facilities. There are no parameters by which to filter the service objects returned from the /service endpoint. \n \n **Note:** Not all outlets and facilities offer all services, and the number of service objects returned may change if Australia Post increases or decreases the number of services it offers."
items:
type: object
properties:
description:
type: string
description: The name of the service.
name:
type: string
description: The name of the service expressed as an enumerated value.
appointment_required:
type: boolean
description: A value indicating if a customer must first make an appointment for the requested service.
categories:
type: array
description: An array of objects that describe the service category to which a specific service belongs.
items:
type: object
properties:
description:
type: string
description: The URL-encoded equivalent of the name field.
name:
type: string
description: The name of the service category to which a service belongs.
description: This object contains the name of a service category used to group services of a similar type.
searchable:
type: boolean
description: A value dictating whether or not a specific service will be presented in the response to a service query.
partner_code:
type: string
description: A code to identify the owner entity of the assets, facilities or services referred to by the location_code. This value is currently always "AP" (Australia Post), however, this may be expanded in future to include other entities.
service_code:
type: integer
description: A unique number identifying a specific service that is available at a location. For example, "99" that identifies the PostBillPay service.
format: int32
url_name:
type: string
description: The URL-encoded equivalent of the description field.
description: "A Service object describes a specific service that might be available from an Australia Post outlet or facility. **Note:** \n Not all outlets and facilities offer all of the services returned by the getServices endpoint."
examples:
example1:
summary: Example services
value:
services:
- service_code: 3
partner_code: AP
name: Special
description: Open before 9.00am weekdays
appointment_required: false
searchable: false
url_name: open-before-900am-weekdays
categories:
- name: opening_hours
description: Opening hours
- service_code: 6
partner_code: AP
name: Boxes_Available
description: PO Boxes available
appointment_required: false
searchable: false
url_name: po-boxes-available
categories:
- name: parcels_mail
description: Parcels & mail
components:
schemas:
AuditVO:
required:
- event_id
- event_source_name
type: object
properties:
event_source_name:
type: string
description: Event Source Name.
example: Doddle
event_id:
type: string
description: Event ID.
example: 2f445d1d-cbfc-4e3d-a742-ec3dc8f009fa
description: Audit details.
ProofOfDeliveryVO:
type: object
properties:
signer_name:
maxLength: 80
minLength: 1
type: string
description: The name of the person signing for acceptance of the delivery.
example: Don Johnson
identification_type:
maxLength: 50
minLength: 1
type: string
description: The type of ID presented.
example: DL
receiver_dob:
type: string
description: The date of birth of the recipient (ddMMyyyy).
format: date-time
attachment:
type: array
items:
$ref: '#/components/schemas/AttachmentVO'
service_actions:
$ref: '#/components/schemas/ServiceActionsVO'
description: The details of the delivery.
Point:
type: object
properties:
address:
description: An object that contains full street address information for a specific Australia Post outlet or facility.
allOf:
- $ref: '#/components/schemas/Address'
secondary_addresses:
description: An object that contains full street address information for a specific Australia Post outlet or facility.
allOf:
- $ref: '#/components/schemas/Address'
delivery_point_id:
type: integer
description: A unique numeric identification code that represents a point to which Australia Post delivers or receives deliveries.
format: int32
usage_type:
type: string
description: 'The usage_type field specifies the access level for a location point.
For parcel lockers (type=UPL):
* "1": Accessible to both registered and unregistered users.
* "2": Accessible only to registered users.'
description:
type: string
description: The name of the point, described as a generic type. For example, "Post Office".
directions:
type: string
description: Indicates address instructions.
fax_number:
type: string
description: An Australian fax number.
geo_location:
type: object
description: An object containing the precise coordinate location of an Australia Post outlet or facility.
allOf:
- $ref: '#/components/schemas/Location'
hatch_description:
type: string
description: A hatch is a customer service window in an Australia Post parcel pickup location. If a point has an associated hatch, this field may contain extra information specific to that hatch.
hours:
type: array
description: An array of objects that describe the hours of operation or availability of services at a location.
items:
allOf:
- $ref: '#/components/schemas/Hour'
location_code:
type: string
description: A unique identification code for a specific Australia Post asset or facility (See the type field below.).
name:
type: string
description: The name of the point in all uppercase characters. For example, "MELBOURNE GPO POST SHOP".
partner_code:
type: string
description: A code to identify the owner entity of the assets, facilities or services referred to by the location_code. This value is currently always "AP" (Australia Post), however, this may be expanded in future to include other entities.
phone_number:
type: string
description: An Australian telephone number.
service_codes:
type: array
description: A comma-delimited string of service IDs that identify the services available at a point. For more information about services, see the getServices endpoint
items:
type: string
type:
type: string
description: "A single enumerated value denoting a service type available at a requested location. When multiple types are available at one location, a separate point object is returned for each one. There are six possible types: \n * UPL: Parcel lockers. \n * R_SPB: A red street post box. \n * C_SPB: Combined street post boxes (Both red and yellow boxes together). \n * PO: An Australia Post outlet. \n * OS: Outstation (These are a part of a post office not in the same physical building. For example, a separate building dedicated to PO boxes.) \n * DC: A delivery centre."
work_centre_id:
type: integer
description: A unique numeric identification code that represents a parent Australia Post facility, and all of the child point objects (assets or facilities) associated with it. The facility and its point objects all share the same work_centre_id, but each point is unique.
format: int32
description: A point object is a descriptive record of an individual Australia Post outlet or facility, that includes location, contact and service availability data.
Location:
properties:
lat:
type: number
description: The global positioning latitude coordinate for a location. For example, 144.9696466.
format: double
lon:
type: number
description: The global positioning longitude coordinate for a location. For example, -37.8126618.
format: double
distance:
type: number
description: The distance in kilometres to a matching point from the coordinates provided in the endpoint request. **Note:** This field is displayed in the results for all endpoints that require you to provide longitude and latitude coordinates.
format: double
description: This object describes the precise location of an Australia Post outlet or facility. This object always returns latitude and longitude values for a point, although requests to the getPointsByGeoCoordinates endpoint will also include a distance value.
ArticleVO:
required:
- article_id
type: object
properties:
article_id:
maxLength: 100
minLength: 1
type: string
description: The Article Id.
example: JQ6378399101
full_barcode:
maxLength: 100
minLength: 0
type: string
description: The Full Barcode.
external_track_url:
type: string
description: External tracking url to allow tracking via 3rd party carrier.
description: Article details.
ServiceActionsVO:
type: object
properties:
type_id:
maxLength: 50
minLength: 0
type: string
description: 'The type of ID presented. Valid types are: Australian Driver License,Red or Orange MyPost card with address, Keypass or other Government-issued Proof of Age card, Australian or international passport, Digital iD.'
id_available:
pattern: X|N
type: string
description: Was ID of the receiver made available at the time of delivery?
example: X
sight_id:
pattern: X|N
type: string
description: Was ID of the receiver sighted by the person making the delivery?
example: X
over_18:
pattern: X|N
type: string
description: Was the recipient over 18? Relevant where the Service Code on the manifest is one of 81, 82, 83.
example: X
description: Elements relating to the specific Product Service Codes, e.g. Service Codes 81, 82 and 83 are for alcohol and require ID to be presented in some Australian States
EventVO:
required:
- article
- audit
- event_date_time
- event_originator
- event_reason
- event_type
type: object
properties:
event_type:
maxLength: 50
minLength: 1
type: string
description: The code indicating which type of event has occurred.
event_reason:
maxLength: 50
minLength: 1
type: string
description: Text describing the event type reason.
example: Transferred
event_reason_text:
maxLength: 80
minLength: 0
type: string
description: Text or comments describing the event reason as entered by user.
example: BADLY DAMAGED
event_date_time:
type: string
description: The timestamp indication when the reason occurred in ISO 8601 Offset from UTC format.
format: date-time
example: '2019-07-08T09:04:45+10:00'
article:
$ref: '#/components/schemas/ArticleVO'
audit:
$ref: '#/components/schemas/AuditVO'
event_originator:
$ref: '#/components/schemas/EventOriginatorVO'
delivery:
$ref: '#/components/schemas/DeliveryVO'
facility:
$ref: '#/components/schemas/FacilityVO'
description: An event originating in a partner's system, which AP is to be informed of.
EventOriginatorVO:
required:
- person
- system
type: object
properties:
system:
$ref: '#/components/schemas/SystemVO'
person:
$ref: '#/components/schemas/PersonVO'
description: Details of the System where the event originated.
PointsResponse:
properties:
points:
type: array
description: An array of point objects. A point object is a data structure returned from calls to Locations API endpoints, and represents the location of a specific Australia Post outlet or facility. The number of point objects returned depends on the endpoint used, and the parameters provided in the request.
items:
allOf:
- $ref: '#/components/schemas/Point'
FacilityVO:
type: object
properties:
location:
$ref: '#/components/schemas/LocationVO'
description: Facility details
PersonVO:
required:
- person_id
type: object
properties:
person_id:
maxLength: 50
minLength: 1
type: string
description: The identifier of the sending person.
example: ABBOTSFORD LPO
description: The person associated with the origin of the event.
LocationVO:
required:
- location_name
- work_centre_code
type: object
properties:
work_centre_code:
maxLength: 10
minLength: 1
type: string
description: Work Centre Code.
example: '123456'
location_name:
maxLength: 50
minLength: 1
type: string
description: Location Name.
example: ABBOTSFORD
description: Location details
Hour:
properties:
end_date:
type: string
description: The end date of an operating period, when non-standard hours are observed. The date is returned in the format DD/MM/YYYY. For example, "30/06/2016".
end_time:
type: string
description: The time when an outlet or facility closes on a particular day, in the format hh:mm. For example, 23:15.
start_date:
type: string
description: The start date of an operating period, when non-standard hours are observed. The date is returned in the format DD/MM/YYYY. For example, "29/06/2016".
start_time:
type: string
description: The time when an outlet or facility opens on a particular day, in the format hh:mm. For example, 09:00.
type:
type: string
description: "The hour type, representing the hours of operation at a location. There are six possible enumerated values: \n * HOURS: Standard operating hours when a location is open. \n * LUNCH: The lunchtime period when a location is closed. \n * HATCH: The hours when the parcel pickup customer service counter is open. \n * SPECIAL_HOURS
# --- truncated at 32 KB (44 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/australia-post/refs/heads/main/openapi/australia-post-endpoints-api-openapi.yml