openapi: 3.0.1 info: description: | **This file forms part of Mplify 121.1** This API implements Business Requirements described in Mplify 150 This draft represents Mplify work in progress and is subject to change It allows the Buyer to retrieve address information from the Seller, including exact formats, for addresses known to the Seller. List of supported Use Cases: - Send Notifications Copyright 2025 Mplify Alliance and its contributors. This file includes content based on the TM Forum Geographic Address API (TMF673 v4.0.1) available at https://github.com/tmforum-apis/TMF673_GeographicAddress, which is licensed by the TM Forum under the Apache License version 2.0. Such content has been modified by the Mplify Alliance and its contributors. title: Geographic Address Notification version: 8.0.0 servers: - url: 'https://{serverBase}/mefApi/sonata/geographicAddressNotification/v8/' variables: serverBase: default: mplify.net description: The base of Buyer's URL. tags: - description: | The Seller's endpoint to send particular event types notifications to. name: Notification listeners paths: /listener/geographicAddressValidationStateChangeEvent: post: deprecated: false description: >- This endpoint is used to receive notifications on Geographic Address Validation state change operationId: listenToGeographicAddressValidationStateChangeEvent parameters: - name: buyerId in: query description: >- The unique identifier of the organization that is acting as the a Buyer. MUST be specified in the request when the requester represents more than one Buyer. required: false schema: type: string - name: sellerId in: query description: >- The unique identifier of the organization that is acting as the Seller. MUST be specified in the request when the responding entity represents more than one Seller. required: false schema: type: string requestBody: content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/GeographicAddressValidationEvent' required: true responses: '204': description: 'No Content (https://tools.ietf.org/html/rfc7231#section-6.3.5)' '400': content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error400' description: Bad Request '401': content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error401' description: Unauthorized '403': content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error403' description: Forbidden '500': content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error500' description: Internal Server Error summary: Geographic Address Validation State Change Notification endpoint tags: - Notification listeners components: schemas: Error: description: > Standard Class used to describe API response error Not intended to be use directly. The `code` in the HTTP header is used as a discriminator for the type of error returned in runtime. properties: reason: description: >- Text that explains the reason for error. This can be shown to a client user. maxLength: 255 type: string message: description: >- Text that provide mode details and corrective actions related to the error. This can be shown to a client user. type: string referenceError: description: url pointing to documentation describing the error format: uri type: string required: - reason type: object Error400: allOf: - $ref: '#/components/schemas/Error' - properties: code: description: >- One of the following error codes: - missingQueryParameter: The URI is missing a required query-string parameter - missingQueryValue: The URI is missing a required query-string parameter value - invalidQuery: The query section of the URI is invalid. - invalidBody: The request has an invalid body $ref: '#/components/schemas/Error400Code' required: - code type: object description: 'Bad Request. (https://tools.ietf.org/html/rfc7231#section-6.5.1)' Error400Code: description: >- One of the following error codes: - missingQueryParameter: The URI is missing a required query-string parameter - missingQueryValue: The URI is missing a required query-string parameter value - invalidQuery: The query section of the URI is invalid. - invalidBody: The request has an invalid body enum: - missingQueryParameter - missingQueryValue - invalidQuery - invalidBody type: string Error401: allOf: - $ref: '#/components/schemas/Error' - properties: code: description: >- One of the following error codes: - missingCredentials: No credentials provided. - invalidCredentials: Provided credentials are invalid or expired $ref: '#/components/schemas/Error401Code' required: - code type: object description: 'Unauthorized. (https://tools.ietf.org/html/rfc7235#section-3.1)' Error401Code: description: |- One of the following error codes: - missingCredentials: No credentials provided. - invalidCredentials: Provided credentials are invalid or expired enum: - missingCredentials - invalidCredentials type: string Error403: allOf: - $ref: '#/components/schemas/Error' - properties: code: description: |- This code indicates that the server understood the request but refuses to authorize it because of one of the following error codes: - accessDenied: Access denied - forbiddenRequester: Forbidden requester - tooManyUsers: Too many users $ref: '#/components/schemas/Error403Code' required: - code type: object description: 'Forbidden. (https://tools.ietf.org/html/rfc7231#section-6.5.3)' Error403Code: description: |- This code indicates that the server understood the request but refuses to authorize it because of one of the following error codes: - accessDenied: Access denied - forbiddenRequester: Forbidden requester - tooManyUsers: Too many users enum: - accessDenied - forbiddenRequester - tooManyUsers type: string Error500: allOf: - $ref: '#/components/schemas/Error' - properties: code: description: >- One of the following error codes: - internalError: Internal server error - the server encountered an unexpected condition that prevented it from fulfilling the request. enum: - internalError type: string required: - code type: object description: >- Internal Server Error. (https://tools.ietf.org/html/rfc7231#section-6.6.1) Event: description: >- Event class is used to describe information structure used for notification. type: object properties: eventId: description: Id of the event type: string eventTime: description: Date-time when the event occurred type: string format: date-time eventType: description: The type of the notification. type: string event: description: The event linked to the involved resource object type: object required: - event - eventId - eventTime - eventType GeographicAddressValidationEvent: allOf: - $ref: '#/components/schemas/Event' - properties: eventType: description: | Indicates the type of the event. enum: - geographicAddressValidationStateChangeEvent type: string event: description: > A reference to the Geographic Address Validation that is source of the notification. $ref: '#/components/schemas/GeographicAddressValidationEventPayload' required: - event - eventType type: object GeographicAddressValidationEventPayload: description: >- The identifier of the Geographic Address Validation being subject of this event. properties: id: description: ID of the Geographic Address Validation type: string href: description: Hyperlink to access the Geographic Address Validation type: string state: description: A state reached at change date $ref: '#/components/schemas/GeographicAddressValidationStateType' required: - id - state type: object GeographicAddressValidationStateType: description: | A list of possible `state` values for GeographicAddressValidation. | Name | Description | | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | acknowledged | A GeographicAddressValidation request has been received by the Seller and has passed basic validation. A `GeographicAddressValidation.id` is assigned in the `acknowledged` state and moves to `inProgress` when it passes business validation. If it does not pass business validation, it moves to the `rejected` state. | | inProgress | The GeographicAddressValidation request is currently being worked on by the Seller. | | ready | The GeographicAddressValidation processing is completed by the Seller and it is ready to be retrieved or the Immediate Response has been returned. | | rejected | The GeographicAddressValidation processing has failed at least one of the validation checks the Seller performs after it reached the `acknowledged` state. | type: string enum: - acknowledged - inProgress - ready - rejected