MEF
MEF LSO Cantata Geographic Address Notification

Geographic Address Notification — the OpenAPI definition published by Mplify (formerly MEF) in the MEF LSO Cantata SDK, Kylie release. LSO Cantata is the Interface Reference Point between a Customer (typically an enterprise) and a Service Provider, covering the business/product layer. 1 path(s), 1 operation(s). Apache-2.0 licensed and openly downloadable from public GitHub.
Documentation GitHub OpenAPI
OpenAPI Specification

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: 2.0.0
servers:
  - url: 'https://{serverBase}/mefApi/cantata/geographicAddressNotification/v2/'
    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
MEF LSO Cantata Geographic Address Notification

Documentation

Specifications

Other Resources

OpenAPI Specification
