Australia Post Endpoints API

openapi: 3.2.0
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:
  parameters:
    usage_types:
      name: usage_types
      in: query
      description: The usage_types parameter is an optional comma-separated string used to filter locations by its usage type. The filter works as an OR condition, meaning locations matching any of the specified values will be returned. If omitted, all locations will be returned.
      required: false
      style: form
      explode: true
      schema:
        type: string
        example: 1,2
    pc:
      name: pc
      in: query
      description: A partner code identifies an entity that owns location data. Currently we offer access only to Australia Post outlet and services data. In the future we may expand this to include location data from partner providers. **Note:** If this field is left empty, the default value is "AP". Submitting any other value will return an empty data set.
      required: false
      style: form
      explode: true
      schema:
        type: string
      x-hide: true
    types:
      name: types
      in: query
      description: "The types parameter is an optional string of comma-delimited values denoting which outlets and facilities you want to locate. There are six of these enumerated values, all of which are selected by default: \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: false
      style: form
      explode: true
      schema:
        type: string
        enum:
        - PO
        - UPL
        - R_SPB
        - C_SPB
        - OS
        - DC
  schemas:
    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.
    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.
    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.
    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
    AttachmentVO:
      required:
      - attachment_content
      - content_type
      type: object
      properties:
        attachment_content:
          type: string
          description: A base64 encoded PNG image of the recipients signature. Restricted to 10240 bytes.
          example: VGhpcyB3b3VsZCBiZSBhIHNhbXBsZSBQTkcgaW1hZ2UgYmluYXJ5...
        content_type:
          type: string
          description: The type of image format of the attachment content.
          example: image/png
      description: Image attachments showing details of a delivery (e.g. for damaged article).
    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   Non-standard operating hours at a location. \n * SPECIAL_CLOSED  Non-standard closing times at a location. \n * SPECIAL_LUNCH: A non-standard time when a location is closed for the lunchtime period. \n **Note: ** Times are specific to the location of the point, expressed as local time at that point."
        weekday:
          type: integer
          description: Day of the week, enumerated from Monday (0) to Sunday (6).
      description: An Hour object describes a range of date and time-related information for a specific Australia Post outlet or facility.
    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'
    DeliveryVO:
      type: object
      properties:
        destination_postcode:
          maxLength: 4
          minLength: 4
          pattern: ^\d{4}$
          type: string
          description: The 4-digit Australian Postcode to where the article has been sent
          example: '3204'
        proof_of_delivery:
          $ref: '#/components/schemas/ProofOfDeliveryVO'
      description: Delivery 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.
    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
    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.
    Address:
      properties:
        type:
          type: string
          description: 'Type of address. There are three possible enumerated values: STREET_ADDRESS, PARCEL_COLLECT and COLLECTION_POINT.'
        address_line_1:
          type: string
          description: Address line one.
        address_line_2:
          type: string
          description: Address line two.
        address_line_3:
          type: string
          description: Address line three.
        suburb:
          type: string
          description: An Australian suburb name.
        state:
          type: string
          description: An Australian state name.
        postcode:
          type: integer
          description: A four-digit Australian postcode.
          format: int32
        country_code:
          type: string
          description: An alphabetical two-digit country identification code, as specified in the ISO 3166-2 standard.
        country_name:
          type: string
          description: The name of the country (as written in English), represented by the country_code field.
        geo_location:
          type:
          - object
          - 'null'
          description: An object containing the precise coordinate location of an Australia Post outlet or facility.
          allOf:
          - $ref: '#/components/schemas/Location'
        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
        directions:
          type: string
          description: Indicates address instructions.
      description: An Address object contains full street address information for a specific Australia Post outlet or facility.
    FacilityVO:
      type: object
      properties:
        location:
          $ref: '#/components/schemas/L

# --- 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