MEF Product Offering Qualification Management (Mef Lso Sonata Product Offering Qualification Management)
MEF Product Offering Qualification Management from MEF — 4 path(s) described in OpenAPI.
OpenAPI Specification
openapi: 3.0.1
info:
title: Product Offering Qualification Management
description: >
**This file forms part of Mplify 87.1**
This API implements Business Requirements described in Mplify 79.1
The Product Offering Qualification (POQ) Management API allows a Buyer to
check whether the Seller can deliver a product or set of products from
among their product offerings at the geographic address or a service site
specified by the Buyer; or modify a previously purchased product.
The following use cases are managed:
- Create Product Offering Qualification
- Retrieve POQ List
- Retrieve POQ by Identifier
- Register for POQ Notifications (note: Send POQ Notification is supported
by productOfferingQualificationNotification.api.yaml)
Copyright 2025 Mplify Alliance and its contributors
This file includes content based on the TM Forum Product Offering
Qualification API (TMF679 v4.0.0) available at
https://github.com/tmforum-apis/TMF679_ProductOfferingQualification, 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.
version: 8.0.0
servers:
- url: 'https://{serverBase}/mefApi/sonata/productOfferingQualification/v8/'
variables:
serverBase:
description: The base of Seller's URL.
default: mplify.net
tags:
- name: productOfferingQualification
description:
Operations for managing the Product Offering Qualification request.
- name: events subscription
description:
Operations for managing the subscription for events notification.
paths:
/hub:
post:
tags:
- events subscription
summary:
Allows a Buyer to register to receive POQ state change notifications
description: >-
A request initiated by the Buyer to instruct the Seller to send
notifications of POQ create, POQ and/or POQ Item state changes if the
Buyer has registered for these notifications. The state change
notifications are sent only in the Deferred response scenario as in the
Immediate response scenario once the response to the POQ Request is
provided (create notification), there will be no further state changes.
operationId: registerListener
parameters:
- name: buyerId
in: query
description: >-
The unique identifier of the organization that is acting as the
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:
description: >-
Data containing the callback endpoint to which to deliver the
information.
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/EventSubscriptionInput'
required: true
responses:
'201':
description:
'Created. (https://tools.ietf.org/html/rfc7231#section-6.3.2)'
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/EventSubscription'
'400':
description: Bad Request
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error401'
'403':
description: Forbidden
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error403'
'422':
description: Unprocessable entity due to business validation problems
content:
application/json;charset=utf-8:
schema:
type: array
items:
$ref: '#/components/schemas/Error422'
'500':
description: Internal Server Error
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error500'
'501':
description: >-
Method not implemented. Used in case Seller is not supporting
Notification mechanism
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error501'
'/hub/{id}':
get:
tags:
- events subscription
summary: Retrieves a Hub by ID
description: This operation retrieves a hub entity.
operationId: retrieveHub
parameters:
- name: id
in: path
description: Identifier of the Hub
required: true
schema:
type: string
- name: buyerId
in: query
description: >-
The unique identifier of the organization that is acting as the
Buyer. MUST be specified in the request only 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 only when responding entity
represents more than one Seller.
required: false
schema:
type: string
responses:
'200':
description: Success
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/EventSubscription'
'400':
description: Bad Request
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error401'
'403':
description: Forbidden
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error403'
'404':
description: Not Found
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error404'
'500':
description: Internal Server Error
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error500'
'501':
description: Method not implemented.
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error501'
delete:
tags:
- events subscription
summary: Unregister a listener
description: |
This operation is used to delete an event subscription.
operationId: unregisterListener
parameters:
- name: id
in: path
description: Identifier of the EventSubscription
required: true
schema:
type: string
- name: buyerId
in: query
description: >-
The unique identifier of the organization that is acting as the
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
responses:
'204':
description:
'No Content. (https://tools.ietf.org/html/rfc7231#section-6.3.5)'
'400':
description: Bad Request
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error401'
'403':
description: Forbidden
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error403'
'404':
description: Not Found
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error404'
'422':
description: Unprocessable entity due to business validation problems
content:
application/json;charset=utf-8:
schema:
type: array
items:
$ref: '#/components/schemas/Error422'
'500':
description: Internal Server Error
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error500'
'501':
description: >-
Method not implemented. Used in case Seller is not supporting
Notification mechanism
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error501'
/productOfferingQualification:
get:
tags:
- productOfferingQualification
summary: >-
Retrieve a list of ProductOfferingQualifications based on a set of
criteria
description: >-
The Buyer requests a list of POQs from the Seller based on a set of POQ
filter criteria. For each POQ returned, the Seller also provides a POQ
Identifier that uniquely identifies this POQ within the Seller's system.
The order of the elements returned to the Buyer is defined by the Seller
(e.g. natural order) and does not change between the pages. If criteria
for attribute X are provided, all returned items must match it.
operationId: listProductOfferingQualification
parameters:
- name: state
in: query
description: >-
State of the POQ to be retrieved. See `MEFPOQTaskStateType`
definition for details
required: false
schema:
type: string
enum:
- acknowledged
- inProgress
- done
- rejected
- terminatedWithError
- name: creationDate.gt
in: query
description: Creation Date is on or after this date
required: false
schema:
type: string
format: date-time
- name: creationDate.lt
in: query
description: Creation Date is on or before this date
required: false
schema:
type: string
format: date-time
- name: requestedPOQCompletionDate.gt
in: query
description: POQ requested response date is on or after this date
required: false
schema:
type: string
format: date-time
- name: requestedPOQCompletionDate.lt
in: query
description: POQ requested response date is on or before this date
required: false
schema:
type: string
format: date-time
- name: externalId
in: query
description: >-
ID given by the consumer and only understandable by him (to
facilitate his searches afterward)
required: false
schema:
type: string
- name: projectId
in: query
description: Identifier of Buyer project associated with POQ
required: false
schema:
type: string
- name: buyerId
in: query
description: >-
The unique identifier of the organization that is acting as the
Buyer
required: false
schema:
type: string
- name: sellerId
in: query
description: >-
The unique identifier of the organization that is acting as the
Seller
required: false
schema:
type: string
- name: offset
in: query
description: >-
Requested index for the start of POQ to be provided in response
requested by the client. Note that the index starts with "0".
required: false
schema:
type: integer
format: int32
- name: limit
in: query
description: >-
Requested number of POQ to be provided in response requested by
client
required: false
schema:
type: integer
format: int32
responses:
'200':
description: 'OK. (https://tools.ietf.org/html/rfc7231#section-6.3.1)'
headers:
X-Pagination-Throttled:
description: >
Used to indicate that the result page was throttled to maximum
possible size and there are additional results that can be
fetched
schema:
type: boolean
X-Total-Count:
description: >
The total number of matching POQ. E.g. if there are 50 matching
items in total, but the request has offset=10 and limit=10, then
the X-Total-Count is 50.
schema:
type: integer
X-Result-Count:
description: The number of POQ included in the response
schema:
type: integer
content:
application/json;charset=utf-8:
schema:
type: array
items:
$ref: '#/components/schemas/ProductOfferingQualification_Find'
'400':
description: Bad Request
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error401'
'403':
description: Forbidden
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error403'
'422':
description: Unprocessable entity due to business validation problems
content:
application/json;charset=utf-8:
schema:
type: array
items:
$ref: '#/components/schemas/Error422'
'500':
description: Internal Server Error
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error500'
'501':
description: >-
Method not implemented. Used in case Seller is not supporting
Notification mechanism
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error501'
post:
tags:
- productOfferingQualification
summary: Send a request to perform product offering qualification
description: >-
A request initiated by the Buyer to determine whether the Seller is able
to deliver a product or set of products from among their product
offerings, at the Buyer's location(s); or modify a previously purchased
product. The Seller also provides estimated time intervals to complete
these deliveries.
operationId: createProductOfferingQualification
parameters:
- name: buyerId
in: query
description: >-
The unique identifier of the organization that is acting as the
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:
description: >-
POQ content provided by the Buyer. See the definition's description
for details.
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/ProductOfferingQualification_Create'
required: true
responses:
'201':
description:
'Created. (https://tools.ietf.org/html/rfc7231#section-6.3.2)'
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/ProductOfferingQualification'
'400':
description: Bad Request
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error401'
'403':
description: Forbidden
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error403'
'422':
description: Unprocessable entity due to business validation problems
content:
application/json;charset=utf-8:
schema:
type: array
items:
$ref: '#/components/schemas/Error422'
'500':
description: Internal Server Error
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error500'
'/productOfferingQualification/{id}':
get:
tags:
- productOfferingQualification
summary: Retrieves a ProductOfferingQualification by ID
description: >-
The Buyer requests the full details of a single Product Offering
Qualification based on a POQ identifier returned from the POQ create
(`createProductOfferingQualification`) or POQ find
(`listProductOfferingQualification`)
operationId: retrieveProductOfferingQualification
parameters:
- name: id
in: path
description:
POQ identifier (matches `ProductOfferingQualification.id`)
required: true
schema:
type: string
- 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
responses:
'200':
description: 'OK. (https://tools.ietf.org/html/rfc7231#section-6.3.1)'
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/ProductOfferingQualification'
'400':
description: Bad Request
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error401'
'403':
description: Forbidden
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error403'
'404':
description: Not Found
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error404'
'500':
description: Internal Server Error
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error500'
'501':
description: >-
Method not implemented. Used in case Seller is not supporting
Notification mechanism
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error501'
components:
schemas:
AlternateProductOfferingProposal:
description: >
If in request the Buyer has requested to have alternate product
proposals, then this class represents a single proposal. All properties
are assigned by the Seller.
type: object
properties:
id:
description: >
A unique identifier for this Alternate Product Offering Proposal
assigned by the Seller.
type: string
serviceabilityConfidence:
description: >-
The level of confidence of the Seller to be able to service the
request with the Alternate Product Offering. Note that this response
is only an evaluation of the technical feasibility of delivery
independent of when the Product Offering can be delivered. When the
item state is `done` the Seller **MUST** provide a value. It **MUST
NOT** be populated for other states.
$ref: '#/components/schemas/AlternateServiceabilityColor'
serviceabilityConfidenceReason:
description:
The reason for the Serviceability Confidence Reason value.
type: string
installationInterval:
description: >
The estimated minimum interval that the Seller requires in their
standard process to complete the delivery of this product from the
time the order is placed and any precedents have been completed.
$ref: '#/components/schemas/Duration'
alternateProduct:
description: Alternate product proposal
$ref: '#/components/schemas/MEFAlternateProduct'
guaranteedUntilDate:
description: |
Date until the Seller guarantees the qualification result.
type: string
format: date-time
deliveryType:
description: >
The mechanism used to deliver the Product to the place of its
installation.
$ref: '#/components/schemas/DeliveryType'
3rdPartyProvider:
description: >
If the Delivery Type is `offNet*` it specifies what 3rd party
provider is used to connect to that place of installation.
type: string
3rdPartyProviderProductOffering:
description: >
If the Delivery Type is `offNet*`, it specifies the 3rd party
provider's offering is used to connect to that place of
installation.
type: string
required:
- alternateProduct
- deliveryType
- id
- installationInterval
- serviceabilityConfidence
AlternateServiceabilityColor:
description: |
A color that indicates confidence to service the request.
| ServiceabilityColor | Description |
|------------------------- | ----------------------------------------------------------------------------- |
| green | The Seller is highly confident that they can deliver the Product Offering. It is not expected that the Seller will change this after an order is placed. |
| yellow | The Seller is confident that they can deliver the Product Offering subject to a feasibility check. The delivery of the Product Offering is subject to checks that the Seller may not carry out until later in the pre-sales/fulfillment process. The Seller cannot be highly confident that they can deliver the Product Offering until those checks are performed. There is a possibility that the Seller may determine that they will not be able to deliver the Product Offering. |
type: string
enum:
- green
- yellow
ContactInformation:
description: >-
Contact data for a person or organization that is involved in the
product offering qualification. In a given context it is always
specified by the Seller (e.g. Seller Contact Information) or by the
Buyer.
type: object
properties:
number:
description: Phone number
type: string
emailAddress:
description: Email address
type: string
postalAddress:
description: >-
Identifies the postal address of the person or office to be
contacted.
$ref: '#/components/schemas/FieldedAddressRepresentation'
organization:
description: The organization or company that the contact belongs to
type: string
name:
description: Name of the contact
type: string
numberExtension:
description: Phone number extension
type: string
required:
- emailAddress
- name
- number
DeliveryType:
description: |
The mechanism used to deliver the Product to the place of its installation.
| Delivery Type | Description |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| offNetWithBuild | A place does not have an existing connection to the Seller's network, but the Seller can connect via a partner who is willing to build out their network to connect to the place (refer to definition of Build). Some providers may refer to this as Near-Net. |
| offNetWithoutBuild | A place that does not have an existing connection to the Seller's network, but the Seller can connect via a 3rd party's existing connection. This may require augmentation of additional equipment, but no Build is needed for the connection. |
| onNetWithBuild | A place that does not have an existing connection to the Seller's network, but to which the Seller is willing to build out their network to connect to the place (refer to definition of Build). Some providers may refer to this as Near-Net. |
| onNetWithoutBuild | A place that has an existing connection to the Seller's network. This may require the augmentation of additional equipment. |
type: string
enum:
- offNetWithBuild
- offNetWithoutBuild
- onNetWithBuild
- onNetWithoutBuild
Duration:
description: 'A Duration in a given unit of time e.g. 3 hours, or 5 days.'
type: object
properties:
amount:
description: 'Duration (number of seconds, minutes, hours, etc.)'
type: integer
minimum: 0
units:
description: Time unit enumerated
$ref: '#/components/schemas/TimeUnit'
required:
- amount
- units
Error:
description: >
Standard Class used to describe API response error Not intended to be
used directly. The `code` in the HTTP header is used as a discriminator
for the type of error returned in runtime.
type: object
properties:
reason:
description: >-
Text that explains the reason for the error. This can be shown to a
client user.
type: string
maxLength: 255
message:
description: >-
Text that provides 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
type: string
format: uri
required:
- reason
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
type: string
enum:
- missingQueryParameter
- missingQueryValue
- invalidQuery
- invalidBody
Error401:
description:
'Unauthorized. (https://tools.ietf.org/html/rfc7235#section-3.1)'
allOf:
- $ref: '#/components/schemas/Error'
- type: object
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
Error401Code:
description: |-
One of the following error codes:
- missingCredentials: No credentials provided.
- invalidCredentials: Provided credentials are invalid or expired
type: string
enum:
- missingCredentials
- invalidCredentials
Error403:
description: >-
Forbidden. This code indicates that the server understood the request
but refuses to authorize it.
(https://tools.ietf.org/html/rfc7231#section-6.5.3)
allOf:
- $ref: '#/components/schemas/Error'
- type: object
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:
-
# --- truncated at 32 KB (87 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mef/refs/heads/main/openapi/mef-lso-sonata-product-offering-qualification-management-openapi.yml