TM Forum Specification

TMF 635 Usage Management API

REST Specification

TMF635
June 2023

Release Status: Team Approval Approval Status: None

Version 4.1.0 IPR Mode: RAND

©TM Forum 2023. All Rights Reserved.

C2 General
Usage Management API REST Specification

NOTICE
Copyright © TM Forum 2023. All Rights Reserved.

This document and translations of it may be copied and furnished to others, and derivative works that comment on
or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in
whole or in part, without restriction of any kind, provided that the above copyright notice and this section are
included on all such copies and derivative works. However, this document itself may not be modified in any way,
including by removing the copyright notice or references to TM FORUM, except as needed for the purpose of
developing any document or deliverable produced by a TM FORUM Collaboration Project Team (in which case the
rules applicable to copyrights, as set forth in the TM FORUM IPR Policy, must be followed) or as required to
translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by TM FORUM or its successors or
assigns.

This document and the information contained herein is provided on an "AS IS" basis and TM FORUM DISCLAIMS
ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Direct inquiries to the TM Forum office:

4 Century Drive, Suite 100

Parsippany, NJ 07054, USA

Tel No. +1 973 944 5100

Fax No. +1 973 944 5110

TM Forum Web Page: www.tmforum.org

© TM Forum 2023. All Rights Reserved Page 2 of 13

C2 General
Usage Management API REST Specification

Table of Contents
NOTICE ............................................................................................................................................................................ 2
Table of Contents............................................................................................................................................................ 3
List of Tables ................................................................................................................................................................... 3
Introduction .................................................................................................................................................................... 4
SAMPLE USE CASES ......................................................................................................................................................... 5
Support of polymorphism and extension patterns ........................................................................................................ 6
RESOURCE MODEL .......................................................................................................................................................... 7
Managed Entity and Task Resource Models ................................................................................................................... 7
FIRST resource ................................................................................................................. Error! Bookmark not defined.
Notification Resource Models ...................................................................................................................................... 25
First Notification .............................................................................................................. Error! Bookmark not defined.
API OPERATIONS ........................................................................................................................................................... 30
VERB url .......................................................................................................................... Error! Bookmark not defined.
API NOTIFICATIONS....................................................................................................................................................... 51
Register listener ............................................................................................................................................................ 51
Unregister listener ........................................................................................................................................................ 52
Publish Event to listener ............................................................................................................................................... 52
Acknowledgements ...................................................................................................................................................... 54
Release History ............................................................................................................................................................. 54
Contributors to Document............................................................................................................................................ 54
List of Tables

N/A

© TM Forum 2023. All Rights Reserved Page 3 of 13

C2 General
Usage Management API REST Specification

Introduction

This document is the user-guide of the REST API for Usage Management. It includes the data model definition as
well as all available operations for the Usage and UsageSpecification resources.

The Usage API provides a standardized mechanism for usage management such as the creation, update, retrieval,
import and export of a collection of usages. A usage is an occurrence of employing a Product, Service or Resource
for its intended purpose which is of interest to the business and can have charges applied to it.

The Usage API manages both rated and non-rated usages. For example, it allows a service provider:

o To retrieve usage generated by a partner service platform in order to rate it

o To provide rated usages to a partner for their consumption

The Usage API manages the Usage resource:

- A Usage represents an event that may be of interest to the business and can have charges applied to it. It is
comprised of characteristics which define all the attributes known for that particular type of usage.
- The main attributes are its id, usageDate, usageType, it’s usageType related UsageSpecification,
characteristics (name/value pairs), status, related Parties and rating related information (such as date,
amount, taxes).
- A Usage follows a simple lifecycle which is presented later for illustrative purposes, defining such aspects as
whether it is rated, rerated or billed.

The Usage API performs the following operations on the Usage resource:

- Retrieval of a Usage or a collection of Usage, depending on filter criteria

- Partial update of a Usage or of a collection of Usage
- Creation of a usage

© TM Forum 2023. All Rights Reserved Page 4 of 13

C2 General
Usage Management API REST Specification

SAMPLE USE CASES

A few simple use-cases are presented:

• Creation of a simple UsageSpecification, defining the characteristics a voice call (caller and receipient
numbers, start and stop date-and-time); listing UsageSpecification’s at version 2.5; retrieving a single
UsageSpecification based on it’s id (91b2-43106cbc8191) and ultimately its deletion based on the same id.
• Creation of a simple Usage relating to a voicemail retrieval; listing Usage of usageType “Voice”; retrieving a
specific Usage based on it’s id (5130d5131a23); updating a Usage status to “billed” and ultimately deleting
this Usage based on the same id.
• Retrieve a simple Usage related to a data offer that has consumed from a Bucket;

© TM Forum 2023. All Rights Reserved Page 5 of 13

C2 General
Usage Management API REST Specification

Support of polymorphism and extension

Support of polymorphic collections and types and schema based extension is provided by means of a list of generic
meta-attributes that we describe below. Polymorphism in collections occurs when entities inherit from base
entities, for instance a TypeAUsage or TypeBUsage inheriting properties from the base Usage entity.

Generic support of polymorphism and pattern extensions is described in the TMF API Guidelines v4.0 Part 2
document.

The @type attribute provides a way to represent the actual class type of an entity. For example, within a list of
Usage instances some may be instances of TypeAUsage and some of TypeBUsage. The @type gives this information.
All resources and sub-resources of this API have a @type attributes that can be provided when this is useful.

The @referredType can be used within reference entities (like for instance a RelatedParty object) to explicitly
denote the actual entity type of the referred class. Notice that in reference entities the @type, when used, denotes
the class type of the reference itself, such as RelatedParty, and not the class type of the referred object. However
since reference classes are rarely sub-classed, @type is generally not useful in reference objects.

The @schemaLocation property can be used in resources to allow specifying user-defined properties of an Entity or
to specify the expected characteristics of an entity.

The @baseType attribute gives a way to provide explicitly the base of class of a given resource that has been
extended.

© TM Forum 2023. All Rights Reserved Page 6 of 13

C2 General
Usage Management API REST Specification

RESOURCE MODEL
Managed Entity and Task Resource Models

Usage resource
An occurrence of employing a Product, Service, or Resource for its intended purpose, which is of interest to the
business and can have charges applied to it. It is comprised of characteristics, which represent attributes of usage.

Resource model

© TM Forum 2023. All Rights Reserved Page 7 of 13

C2 General
Usage Management API REST Specification

Field descriptions

Usage fields

© TM Forum 2023. All Rights Reserved Page 8 of 13

C2 General
Usage Management API REST Specification

href An uri (Uri). Hyperlink reference.

id A string. unique identifier.

@baseType A string. When sub-classing, this defines the super-class.

@schemaLocation An uri (Uri). A URI to a JSON-Schema file that defines additional attributes and
relationships.

@type A string. When sub-classing, this defines the sub-class Extensible name.

description A string. Description of usage.

impactedBucket A list of impacted buckets (ImpactedBucket [*]). A reference to the bucket impacted
by the request or the value itself.

ratedProductUsage A list of rated product usages (RatedProductUsage [*]). An occurrence of employing a

product for its intended purpose with all rating details.

relatedParty A list of related parties (RelatedParty [*]). Related Entity reference. A related party
defines party or party role linked to a specific entity.

status An usage status type (UsageStatusType). Possible values for the status of the Usage.

usageCharacteristic A list of usage characteristics (UsageCharacteristic [*]). Provides the value of a given
characteristic.

usageDate A date time (DateTime). Date of usage.

usageSpecification An usage specification reference (UsageSpecificationRef). UsageSpecification is a

detailed description of a usage event that are of interest to the business and can have
charges applied to it. It is comprised of characteristics, which define all attributes
known for a particular type of usage.

usageType A string. Type of usage.

CharacteristicRelationship sub-resource

Another Characteristic that is related to the current Characteristic.

href An uri (Uri). Hyperlink reference.

id A string. Unique identifier of the characteristic.

@baseType A string. When sub-classing, this defines the super-class.

@schemaLocation An uri (Uri). A URI to a JSON-Schema file that defines additional attributes and
relationships.

@type A string. When sub-classing, this defines the sub-class Extensible name.

© TM Forum 2023. All Rights Reserved Page 9 of 13

C2 General
Usage Management API REST Specification

relationshipType A string. The type of relationship.

ImpactedBucket sub-resource

A resource that references other buckets that have been impacted by the action of type
TopupBalance,AdjustBalance,TransferBalance or ReserveBalance.

@baseType A string. When sub-classing, this defines the super-class.

@schemaLocation An uri (Uri). A URI to a JSON-Schema file that defines additional attributes and
relationships.

@type A string. When sub-classing, this defines the sub-class Extensible name.

amountAfter A quantity (Quantity). Indicates the amount after on the impacted bucket after the
action has completed.

amountBefore A quantity (Quantity). Indicates the amount remaiing on the impacted bucket.

bucket A bucket reference (BucketRef). A reference to the bucket impacted by the request or
the value itself.

confirmationDate A date time (DateTime). Date when the deduction was confirmed in the server.

description A string. Text describing the contents of the balance managed by the bucket.

item A list of impacted bucket items (ImpactedBucketItem [1..*]). a resource used by the
ImpactedBucket resource to capture the impact of a ImpactedBucket.

name A string. Friendly name to identify the bucket.

requestedDate A date time (DateTime). Date when the deduction request was received in the server.

ImpactedBucketItem sub-resource

a resource used by the ImpactedBucket resource to capture the impact of a ImpactedBucket.

@baseType A string. When sub-classing, this defines the super-class.

@schemaLocation An uri (Uri). A URI to a JSON-Schema file that defines additional attributes and
relationships.

@type A string. When sub-classing, this defines the sub-class Extensible name.

amount A quantity (Quantity). Indicate the amount on the bucket.

description A string. Description of the recharge operation.

itemType A string. This indicates whether the action led to the bucket being incremented or
decremented.eg credit or debit.

© TM Forum 2023. All Rights Reserved Page 10 of 13

C2 General
Usage Management API REST Specification

name A string. This represents the transaction activity. e.g topup, bonus, additional bonus,
tax, fees, and so on.

reason A string. Text describing the reason for the action/task.

Money sub-resource

A base / value business entity used to represent money.

unit A string. Currency (ISO4217 norm uses 3 letters to define the currency).

value A float. A signed floating point number, the meaning of the sign is according to the
context of the API that uses this Data type.

Quantity sub-resource

An amount in a given unit.

amount A float. Numeric value in a given unit.

units A string. Unit.

RatedProductUsage sub-resource

An occurrence of employing a product for its intended purpose with all rating details.

@baseType A string. When sub-classing, this defines the super-class.

@schemaLocation An uri (Uri). A URI to a JSON-Schema file that defines additional attributes and
relationships.

@type A string. When sub-classing, this defines the sub-class Extensible name.

bucketValueConvertedInAmount A money (Money). A base / value business entity used to represent money.

isBilled A boolean. Boolean indicating if usage have been billed or not.

isTaxExempt A boolean. Indicates if the rated amount is exempt of tax.

offerTariffType A string. Type of tariff applied.

productRef A product reference (ProductRef).

ratingAmountType A string. Type of amount.

ratingDate A date time (DateTime). Date of usage rating.

taxExcludedRatingAmount A money (Money). A base / value business entity used to represent money.

taxIncludedRatingAmount A money (Money). A base / value business entity used to represent money.

taxRate A float. Tax rate.

© TM Forum 2023. All Rights Reserved Page 11 of 13

C2 General
Usage Management API REST Specification

usageRatingTag A string. Tag value: [usage]: the usage is always rated outside a usage bundle
[included usage]: the usage is rated inside a usage bundle
[non included usage]: the usage bundle is exhausted. The usage is rated
outside the usage bundle.

RelatedParty sub-resource

Related Entity reference. A related party defines party or party role linked to a specific entity.

@referredType A string. The actual type of the target instance when needed for disambiguation.

name A string. Name of the related entity.

href An uri (Uri). Hyperlink reference.

id A string. unique identifier.

@baseType A string. When sub-classing, this defines the super-class.

@schemaLocation An uri (Uri). A URI to a JSON-Schema file that defines additional attributes and
relationships.

@type A string. When sub-classing, this defines the sub-class Extensible name.

role A string. Role played by the related party.

UsageCharacteristic sub-resource

Provides the value of a given characteristic.

id A string. Unique identifier of the characteristic.

name A string. Name of the characteristic.

valueType A string. Data type of the value of the characteristic.

@baseType A string. When sub-classing, this defines the super-class.

@schemaLocation An uri (Uri). A URI to a JSON-Schema file that defines additional attributes and
relationships.

@type A string. When sub-classing, this defines the sub-class Extensible name.

characteristicRelationship A list of characteristic relationships (CharacteristicRelationship [*]). Another

Characteristic that is related to the current Characteristic.

value An any (Any). The value of the characteristic.

BucketRef relationship

link to the resource that holds bucket information.

© TM Forum 2023. All Rights Reserved Page 12 of 13

C2 General
Usage Management API REST Specification

@referredType A string. The actual type of the target instance when needed for disambiguation.

name A string. Name of the related entity.

href An uri (Uri). Hyperlink reference.

id A string. unique identifier.

@baseType A string. When sub-classing, this defines the super-class.

@schemaLocation An uri (Uri). A URI to a JSON-Schema file that defines additional attributes and
relationships.

@type A string. When sub-classing, this defines the sub-class Extensible name.

usageType A string. defines the type of the underlying Balance eg data,voice, any currency eg
EUR, USD etc.

ProductRef relationship

@referredType A string. The actual type of the target instance when needed for disambiguation.

name A string. Name of the related entity.

href An uri (Uri). Hyperlink reference.

id A string. unique identifier.

@baseType A string. When sub-classing, this defines the super-class.

@schemaLocation An uri (Uri). A URI to a JSON-Schema file that defines additional attributes and
relationships.

@type A string. When sub-classing, this defines the sub-class Extensible name.

UsageSpecificationRef relationship

UsageSpecification reference. UsageSpecification is a detailed description of a usage event that are of interest to
the business and can have charges applied to it. It is comprised of characteristics, which define all attributes known
for a particular type of usage.

href An uri (Uri). Hyperlink reference.

id A string. unique identifier.

@baseType A string. When sub-classing, this defines the super-class.

@schemaLocation An uri (Uri). A URI to a JSON-Schema file that defines additional attributes and
relationships.

© TM Forum 2023. All Rights Reserved Page 13 of 13

C2 General
Usage Management API REST Specification

@type A string. When sub-classing, this defines the sub-class Extensible name.

@referredType A string. The actual type of the target instance when needed for disambiguation.

name A string. The name of the usage specification.

Json representation sample

We provide below the json representation of an example of a 'Usage' resource object

{
"id": "93c2-683ea281566c",
"href": "https://api.csp.com/tmf-api/usagemanagement/v4/usage/93c2-683ea281566c",
"usageDate": "2020-11-20T16:07:00Z",
"description": "Voicemail Retrieval",
"usageType": "Voicemail",
"ratedProductUsage": [
{
"isBilled": false,
"isTaxExempt": true,
"offerTariffType": "Normal",
"ratingAmountType": "Total",
"ratingDate": "2020-06-17T21:03:37.829Z",
"taxRate": 0,
"usageRatingTag": "voicemail",
"bucketValueConvertedInAmount": {
"unit": "EUR",
"value": 0
},
"productRef": {
"id": "a22b-1c848b2a1b64",
"href": "https://api.csp.com/tmf-api/productInventory/v4/product/a22b-1c848b2a1b64",
"name": "Voicemail",
"@referredType": "Product"
},
"taxExcludedAmount": {
"unit": "EUR",
"value": 0
},
"taxIncludedAmount": {
"unit": "EUR",
"value": 0
}
}
],
"relatedParty": [
{
"id": "8185-b246a6746136",
"href": "https://api.csp.com/tmf-api/partyManagement/v4/individual/8185-b246a6746136",
"name": "Ivor Message",
"role": "Customer",
"@referredType": "Individual"
}
],
"status": "received",

© TM Forum 2023. All Rights Reserved Page 14 of 13

C2 General
Usage Management API REST Specification

"usageCharacteristic": [
{
"id": "a0ba-ae64952b68ba",
"name": "duration-seconds",
"valueType": "integer",
"value": "12"
}
],
"usageSpecification": {
"id": "9be4-cfee80785eb5",
"href": "https://api.csp.com/tmf-api/usageManagement/v4/usageSpecification/9be4-cfee80785eb5",
"name": "Voicemail Retrieval Specification",
"@referredType": "UsageSpecification"
}
}

Usage Specification resource

A detailed description of a usage event that are of interest to the business and can have charges applied to it. It is
comprised of characteristics, which define all attributes known for a particular type of usage.

Resource model

© TM Forum 2023. All Rights Reserved Page 15 of 13

C2 General
Usage Management API REST Specification

Field descriptions

UsageSpecification fields

© TM Forum 2023. All Rights Reserved Page 16 of 13

C2 General
Usage Management API REST Specification

description A string. Description of the specification.

isBundle A boolean. isBundle determines whether specification represents a single

specification (false), or a bundle of specifications (true).

lastUpdate A date time (DateTime). Date and time of the last update of the specification.

lifecycleStatus A string. Used to indicate the current lifecycle status of this catalog item.

name A string. Name given to the specification.

version A string. specification version.

href An uri (Uri). Hyperlink reference.

id A string. unique identifier.

@baseType A string. When sub-classing, this defines the super-class.

@schemaLocation An uri (Uri). A URI to a JSON-Schema file that defines additional attributes and
relationships.

@type A string. When sub-classing, this defines the sub-class Extensible name.

attachment A list of attachment ref or values (AttachmentRefOrValue [*]). Attachments that may
be of relevance to this specification, such as picture, document, media.

constraint A list of constraint references (ConstraintRef [*]). This is a list of constraint references
applied to this specification.

entitySpecRelationship A list of entity specification relationships (EntitySpecificationRelationship [*]).

Relationship to another specification.

relatedParty A list of related parties (RelatedParty [*]). Parties who manage or otherwise have an
interest in this specification.

specCharacteristic A list of characteristic specifications (CharacteristicSpecification [*]). List of

characteristics that the entity can take.

targetEntitySchema A target entity schema (TargetEntitySchema). Pointer to a schema that defines the
target entity.

validFor A time period. The period for which this REST resource is valid.

AttachmentRefOrValue sub-resource

An attachment by value or by reference. An attachment complements the description of an element, for example
through a document, a video, a picture.

@referredType A string. The actual type of the target instance when needed for disambiguation.

© TM Forum 2023. All Rights Reserved Page 17 of 13

C2 General
Usage Management API REST Specification

description A string. A narrative text describing the content of the attachment.

href An uri (Uri). URI for this Attachment.

id A string. Unique identifier for this particular attachment.

url An uri (Uri). Remote reference to the content if web-addressable.

name A string. The name of the attachment.

@baseType A string. When sub-classing, this defines the super-class.

@schemaLocation An uri (Uri). A URI to a JSON-Schema file that defines additional attributes and
relationships.

@type A string. When sub-classing, this defines the sub-class Extensible name.

attachmentType A string. Attachment type such as video, picture.

content A base 6 4 (Base64). The actual contents of the attachment object, if embedded,
encoded as base64.

mimeType A string. Attachment mime type such as extension file for video, picture and
document.

size A quantity (Quantity). The size of the attachment.

validFor A time period. The period of time for which the attachment is valid.

CharacteristicSpecification sub-resource

This class defines a characteristic specification.

@valueSchemaLocation A string. This (optional) field provides a link to the schema describing the value
type.

configurable A boolean. If true, the Boolean indicates that the target Characteristic is
configurable.

description A string. A narrative that explains the CharacteristicSpecification.

extensible A boolean. An indicator that specifies that the values for the characteristic can
be extended by adding new values when instantiating a characteristic for a
resource.

id A string. Unique ID for the characteristic.

isUnique A boolean. Specifies if the value of this characteristic is unique across all
entities instantiated from the specification that uses this characteristc. For
example, consider a ProductSpecification for a set-top box, with a
CharacteristicSpecification cardID. Each set-top box must have a different

© TM Forum 2023. All Rights Reserved Page 18 of 13

C2 General
Usage Management API REST Specification

value for cardID, so this isUnique attribute would be set to true for the
characteristic.

maxCardinality An integer. The maximum number of instances a CharacteristicValue can take

on. For example, zero to five phone numbers in a group calling plan, where
five is the value for the maxCardinality.

minCardinality An integer. The minimum number of instances a CharacteristicValue can take

on. For example, zero to five phone numbers in a group calling plan, where
zero is the value for the minCardinality.

name A string. A word, term, or phrase by which this characteristic specification is

known and distinguished from other characteristic specifications.

regex A string. A rule or principle represented in regular expression used to derive

the value of a characteristic value.

valueType A string. A kind of value that the characteristic can take on, such as numeric,
text and so forth.

@baseType A string. When sub-classing, this defines the super-class.

@schemaLocation An uri (Uri). A URI to a JSON-Schema file that defines additional attributes and
relationships.

@type A string. When sub-classing, this defines the sub-class Extensible name.

charSpecRelationship A list of characteristic specification relationships

(CharacteristicSpecificationRelationship [*]). An aggregation, migration,
substitution, dependency or exclusivity relationship between/among
Specification Characteristics.

characteristicValueSpecification A list of characteristic value specifications (CharacteristicValueSpecification

[*]). A CharacteristicValueSpecification object is used to define a set of
attributes, each of which can be assigned to a corresponding set of attributes
in a CharacteristicSpecification object. The values of the attributes in the
CharacteristicValueSpecification object describe the values of the attributes
that a corresponding Characteristic object can take on.

validFor A time period. The period of time for which a characteristic is applicable.

CharacteristicSpecificationRelationship sub-resource

An aggregation, migration, substitution, dependency or exclusivity relationship between/among Characteristic

specifications. The specification characteristic is embedded within the specification whose ID and href are in this
entity, and identified by its ID.

@baseType A string. When sub-classing, this defines the super-class.

© TM Forum 2023. All Rights Reserved Page 19 of 13

C2 General
Usage Management API REST Specification

@schemaLocation An uri (Uri). A URI to a JSON-Schema file that defines additional attributes and
relationships.

@type A string. When sub-classing, this defines the sub-class Extensible name.

characteristicSpecificationId A string. Unique identifier of the characteristic within the specification.

name A string. Name of the target characteristic within the specification.

parentSpecificationHref An uri (Uri). Hyperlink reference to the parent specification containing the target
characteristic.

parentSpecificationId A string. Unique identifier of the parent specification containing the target
characteristic.

relationshipType A string. Type of relationship such as aggregation, migration, substitution,

dependency, exclusivity.

validFor A time period. The period for which the object is valid.

CharacteristicValueSpecification sub-resource

specification of a value (number or text or an object) that can be assigned to a Characteristic.

@baseType A string. When sub-classing, this defines the super-class.

@schemaLocation An uri (Uri). A URI to a JSON-Schema file that defines additional attributes and
relationships.

@type A string. When sub-classing, this defines the sub-class Extensible name.

isDefault A boolean. If true, the Boolean Indicates if the value is the default value for a
characteristic.

rangeInterval A string. An indicator that specifies the inclusion or exclusion of the valueFrom and
valueTo attributes. If applicable, possible values are "open", "closed", "closedBottom"
and "closedTop".

regex A string. A regular expression constraint for given value.

unitOfMeasure A string. A length, surface, volume, dry measure, liquid measure, money, weight,
time, and the like. In general, a determinate quantity or magnitude of the kind
designated, taken as a standard of comparison for others of the same kind, in
assigning to them numerical values, as 1 foot, 1 yard, 1 mile, 1 square foot.

validFor A time period. The period of time for which a value is applicable.

value An any (Any). A discrete value that the characteristic can take on, or the actual value
of the characteristic.

© TM Forum 2023. All Rights Reserved Page 20 of 13

C2 General
Usage Management API REST Specification

valueFrom An integer. The low range value that a characteristic can take on.

valueTo An integer. The upper range value that a characteristic can take on.

valueType A string. A kind of value that the characteristic value can take on, such as numeric,
text and so forth.

EntitySpecificationRelationship sub-resource

A migration, substitution, dependency or exclusivity relationship between/among entity specifications.

@referredType A string. The actual type of the target instance when needed for disambiguation.

name A string. Name of the related entity.

href An uri (Uri). Hyperlink reference.

id A string. unique identifier.

@baseType A string. When sub-classing, this defines the super-class.

@schemaLocation An uri (Uri). A URI to a JSON-Schema file that defines additional attributes and
relationships.

@type A string. When sub-classing, this defines the sub-class Extensible name.

associationSpec An association specification reference (AssociationSpecificationRef). A specification

for an association used by this relationship.

relationshipType A string. Type of relationship such as migration, substitution, dependency, exclusivity.

role A string. The association role for this entity specification.

validFor A time period. The period for which the entitySpecRelationship is valid.

Quantity sub-resource

An amount in a given unit.

amount A float. Numeric value in a given unit.

units A string. Unit.

RelatedParty sub-resource

Related Entity reference. A related party defines party or party role linked to a specific entity.

@referredType A string. The actual type of the target instance when needed for disambiguation.

name A string. Name of the related entity.

href An uri (Uri). Hyperlink reference.

© TM Forum 2023. All Rights Reserved Page 21 of 13

C2 General
Usage Management API REST Specification

id A string. unique identifier.

@baseType A string. When sub-classing, this defines the super-class.

@schemaLocation An uri (Uri). A URI to a JSON-Schema file that defines additional attributes and
relationships.

@type A string. When sub-classing, this defines the sub-class Extensible name.

role A string. Role played by the related party.

TargetEntitySchema sub-resource

The reference object to the schema and type of target entity which is described by a specification.

@schemaLocation A string. This field provides a link to the schema describing the target entity.

@type A string. Class type of the target entity.

AssociationSpecificationRef relationship

reference to an AssociationSpecification object.

@referredType A string. The actual type of the target instance when needed for disambiguation.

name A string. Name of the related entity.

href An uri (Uri). Hyperlink reference.

id A string. unique identifier.

@baseType A string. When sub-classing, this defines the super-class.

@schemaLocation An uri (Uri). A URI to a JSON-Schema file that defines additional attributes and
relationships.

@type A string. When sub-classing, this defines the sub-class Extensible name.

ConstraintRef relationship

Constraint reference. The Constraint resource represents a policy/rule applied to an entity or entity spec.

@referredType A string. The actual type of the target instance when needed for disambiguation.

name A string. Name of the related entity.

href An uri (Uri). Hyperlink reference.

id A string. unique identifier.

@baseType A string. When sub-classing, this defines the super-class.

© TM Forum 2023. All Rights Reserved Page 22 of 13

C2 General
Usage Management API REST Specification

@schemaLocation An uri (Uri). A URI to a JSON-Schema file that defines additional attributes and
relationships.

@type A string. When sub-classing, this defines the sub-class Extensible name.

version A string. constraint version.

Json representation sample

We provide below the json representation of an example of a 'UsageSpecification' resource object

{
"id": "9aa3-3e7737dd5080",
"href": "https://api.csp.com/tmf-api/usageManagement/v4/usageSpecification/9aa3-3e7737dd5080",
"description": "Specification for voice calls usage",
"name": "Voice-Call-Specification",
"usageSpecCharacteristic": [
{
"name": "originatingCountryCode",
"description": "country code of the caller",
"configurable": "true",
"valueType": "number",
"minCardinality": 1,
"maxCardinality": 1,
"isUnique": true
},
{
"name": "originatingNumber",
"description": "phone number of the caller",
"configurable": "true",
"valueType": "number",
"minCardinality": 1,
"maxCardinality": 1,
"isUnique": true
},
{
"name": "destinationCountryCode",
"description": "country code of the called party",
"configurable": "true",
"valueType": "number",
"minCardinality": 1,
"maxCardinality": 1,
"isUnique": true
},
{
"name": "destinationNumber",
"description": "phone number of the called party",
"configurable": "true",
"valueType": "number",
"minCardinality": 1,
"maxCardinality": 1,
"isUnique": true
},
{
"name": "duration",

© TM Forum 2023. All Rights Reserved Page 23 of 13

C2 General
Usage Management API REST Specification

"description": "duration of the call",

"configurable": "true",
"valueType": "number",
"minCardinality": 1,
"maxCardinality": 1
},
{
"name": "unit",
"description": "unit of the duration",
"configurable": "true",
"valueType": "string",
"minCardinality": 0,
"maxCardinality": 1,
"usageSpecCharacteristicValue": [
{
"isDefault": true,
"value": "SEC"
}
]
},
{
"name": "startDateTime",
"description": "startdate and starttime of the call",
"configurable": "true",
"valueType": "dateTime",
"minCardinality": 1,
"maxCardinality": 1
},
{
"name": "endDateTime",
"description": "enddate and endtime of the call",
"configurable": "true",
"valueType": "dateTime",
"minCardinality": 1,
"maxCardinality": 1
}
],
"validFor": {
"startDateTime": "2022-02-20T17:00:00.000Z",
"endDateTime": "2099-01-11T00:00:00.000Z"
}
}

Note that a Usage instance can reference multiple RelatedParty instances – such as the person who made a voice
call, or consumed a service. It must have a reference to a UsageSpecification, which will define the characteristics
relevant to this usage type. These may be discrete or ranged, or have relationships to each other – as defined in the
UsageSpecification data model.

This is an illustrative state machine diagram for the Usage resource:

© TM Forum 2023. All Rights Reserved Page 24 of 13

C2 General
Usage Management API REST Specification

Usage State definitions:

The following table provides usage state descriptions:

State Definition
Received This acknowledges that the usage has been received and is pending message validation.
Rejected The Rejected state is where invalid information is provided through the usage instance (not
necessarily checked synchronously)
Guided Identified with customer and product references
Rated The Usage has been rated (assigned a value). From this point on, the ratedProductUsage
collection will have a value
Rerated Marked for re-rating
Billed Billed for a customer invoice
Recycled Resubmitted after error correction
Rejected Invalid information or failed business rules

Notification Resource Models

7 notifications are defined for this API

© TM Forum 2023. All Rights Reserved Page 25 of 13

C2 General
Usage Management API REST Specification

Notifications related to Usage:

- UsageCreateEvent
- UsageAttributeValueChangeEvent
- UsageDeleteEvent
- UsageStateChangeEvent

Notifications related to UsageSpecification:

- UsageSpecificationCreateEvent
- UsageSpecificationAttributeValueChangeEvent
- UsageSpecificationDeleteEvent

The notification structure for all notifications in this API follow the pattern depicted by the figure below.
A notification event resource (depicted by "SpecificEvent" placeholder) is a sub class of a generic Event structure
containing at least an id of the event occurrence (eventId), an event timestamp (eventTime), and the name of the
resource (eventType).
This notification structure owns an event payload structure ("SpecificEventPayload" placeholder) linked to the
resource concerned by the notification using the resource name as access field ("resourceName" placeholder).

Usage Create Event

Notification UsageCreateEvent case for resource Usage

Json representation sample

We provide below the json representation of an example of a 'UsageCreateEvent' notification event object

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"UsageCreateEvent",
"event": {
"usage" :
{-- SEE Usage RESOURCE SAMPLE --}
}
}

Usage Attribute Value Change Event

Notification UsageAttributeValueChangeEvent case for resource Usage

Json representation sample

We provide below the json representation of an example of a 'UsageAttributeValueChangeEvent' notification event

object

{
"eventId":"00001",

© TM Forum 2023. All Rights Reserved Page 26 of 13

C2 General
Usage Management API REST Specification

"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"UsageAttributeValueChangeEvent",
"event": {
"usage" :
{-- SEE Usage RESOURCE SAMPLE --}
}
}

Usage Delete Event

Notification UsageDeleteEvent case for resource Usage

Json representation sample

We provide below the json representation of an example of a 'UsageDeleteEvent' notification event object

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"UsageDeleteEvent",
"event": {
"usage" :
{-- SEE Usage RESOURCE SAMPLE --}
}
}

Usage State Change Event

Notification UsageStateChangeEvent case for resource Usage

Json representation sample

We provide below the json representation of an example of a 'UsageStateChangeEvent' notification event object

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"UsageStateChangeEvent",
"event": {
"usage" :
{-- SEE Usage RESOURCE SAMPLE --}
}
}

Usage Specification Create Event

Notification UsageSpecificationCreateEvent case for resource UsageSpecification

Json representation sample

© TM Forum 2023. All Rights Reserved Page 27 of 13

C2 General
Usage Management API REST Specification

We provide below the json representation of an example of a 'UsageSpecificationCreateEvent' notification event

object

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"UsageSpecificationCreateEvent",
"event": {
"usageSpecification" :
{-- SEE UsageSpecification RESOURCE SAMPLE --}
}
}

Usage Specification Attribute Value Change Event

Notification UsageSpecificationAttributeValueChangeEvent case for resource UsageSpecification

Json representation sample

We provide below the json representation of an example of a 'UsageSpecificationAttributeValueChangeEvent'

notification event object

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"UsageSpecificationAttributeValueChangeEvent",
"event": {
"usageSpecification" :
{-- SEE UsageSpecification RESOURCE SAMPLE --}
}
}

Usage Specification Delete Event

Notification UsageSpecificationDeleteEvent case for resource UsageSpecification

Json representation sample

We provide below the json representation of an example of a 'UsageSpecificationDeleteEvent' notification event

object

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"UsageSpecificationDeleteEvent",
"event": {
"usageSpecification" :
{-- SEE UsageSpecification RESOURCE SAMPLE --}
}
}

© TM Forum 2023. All Rights Reserved Page 28 of 13

C2 General
Usage Management API REST Specification

© TM Forum 2023. All Rights Reserved Page 29 of 13

C2 General
Usage Management API REST Specification

API OPERATIONS
Remember the following Uniform Contract:

Operation on Entities Uniform API Operation Description

Query Entities GET Resource GET must be used to retrieve a

representation of a resource.

Create Entity POST Resource POST must be used to create a

new resource

Partial Update of an Entity PATCH Resource PATCH must be used to partially

update a resource

Remove an Entity DELETE Resource DELETE must be used to remove

a resource

Execute an Action on an Entity POST on TASK Resource POST must be used to execute
Task Resources

Other Request Methods POST on TASK Resource GET and POST must not be used
to tunnel other request
methods.

Filtering and attribute selection rules are described in the TMF REST Design Guidelines.

Notifications are also described in a subsequent section.

Operations on Usage

List usages

GET /usage?fields=...&{filtering}
Description

This operation list usage entities.

Attribute selection is enabled for all first level attributes.
Filtering may be available depending on the compliance level supported by an implementation.

© TM Forum 2023. All Rights Reserved Page 30 of 13

C2 General
Usage Management API REST Specification

Usage Samples

Retrieving previous Usage details for the usageType of 'Voice'.

Request

GET /tmf-api/usageManagement/v4/usage?fields=id,href,status,usageType,usageDate&usageType=Voice
Accept: application/json

Response

200

[
{
"id": "93c2-683ea281566c",
"href": "https://api.csp.com/tmf-api/usageManagement/v4/Usage/93c2-683ea281566c",
"status": "received",
"usageType": "Voice",
"usageDate": "2020-11-20T08:13:16.000Z"
},
{
"id": "bbba-0c6e63171b78",
"href": "https://api.csp.com/tmf-api/usageManagement/v4/Usage/bbba-0c6e63171b78",
"status": "rated",
"usageType": "Voice",
"usageDate": "2020-09-01T08:30:01.000Z"
}
]

Retrieve usage

GET /usage/{id}?fields=...&{filtering}
Description

This operation retrieves an usage entity.

Attribute selection is enabled for all first level attributes.
Filtering on sub-resources may be available depending on the compliance level supported by an implementation.

Usage Samples

A request for a previous Usage event. The criteria is the Usage id 5130d5131a23

© TM Forum 2023. All Rights Reserved Page 31 of 13

C2 General
Usage Management API REST Specification

Request

GET /tmf-api/usageManagement/v4/usage/5130d5131a23
Accept: application/json

Response

200

{
"id": "5130d5131a23",
"href": "https://api.csp.com/tmf-api/usageManagement/v4/Usage/5130d5131a23",
"ratedProductUsage": [
{
"ratingDate": "2020-02-20T17:00:00.000Z",
"usageRatingTag": "Usage",
"ratingAmountType": "Total",
"taxIncludedRatingAmount": {
"value": 12.0,
"unit": "EUR"
},
"taxExcludedRatingAmount": {
"value": 10.0,
"unit": "EUR"
},
"taxRate": 20.0,
"isTaxExempt": false,
"offerTariffType": "Normal",
"bucketValueConvertedInAmount": {
"value": 10.0,
"unit": "EUR"
}
}
],
"relatedParty": [
{
"id": "a396-5c90a41a23ea",
"href": "https://api.csp.com/tmf-api/partyManagement/v4/organization/a396-5c90a41a23ea",
"role": "serviceProvider",
"@referredType": "Organization"
},
{
"id": "8a41-d6451fe98963",
"href": "https://api.csp.com/tmf-api/partyManagement/v4/individual/8a41-d6451fe98963",
"role": "customer",
"@referredType": "Individual"
}
],
"status": "rated",
"usageType": "Voice",
"usageCharacteristic": [
{

© TM Forum 2023. All Rights Reserved Page 32 of 13

C2 General
Usage Management API REST Specification

"name": "originatingCountryCode",
"value": "43"
},
{
"name": "originatingNumber",
"value": "676123456789"
},
{
"name": "destinationCountryCode",
"value": "49"
},
{
"name": "destinationNumber",
"value": "170123456789"
},
{
"name": "duration",
"value": 20
},
{
"name": "unit",
"value": "SEC"
}
],
"usageSpecification": {
"id": "af59-b504c742900e",
"href": "https:/api.csp.com/tmf-api/usageManagement/v4/usageSpecification/af59-b504c742900e",
"name": "VoiceCall"
}
}

Create usage

POST /usage
Description

This operation creates an usage entity.

Mandatory and Non Mandatory Attributes

The following tables provide the list of mandatory and non mandatory attributes when creating a Usage, including
any possible rule conditions and applicable default values. Notice that it is up to an implementer to add additional
mandatory attributes.

Mandatory Attributes Rule

Non Mandatory Attributes Rule

@baseType
@schemaLocation
@type

© TM Forum 2023. All Rights Reserved Page 33 of 13

C2 General
Usage Management API REST Specification

description
impactedBucket
ratedProductUsage
relatedParty
status
usageCharacteristic
usageDate
usageSpecification
usageType

Usage Samples

Create a Usage event for a Voicemail retrieval - the resulting resource ID is 5130d5131a23

Request

POST /tmf-api/usageManagement/v4/usage
Content-Type: application/json

{
"ratedProductUsage": [
{
"ratingDate": "2020-02-20T17:00:00.000Z",
"usageRatingTag": "Usage",
"ratingAmountType": "Total",
"taxIncludedRatingAmount": {
"value": 12.0,
"unit": "EUR"
},
"taxExcludedRatingAmount": {
"value": 10.0,
"unit": "EUR"
},
"taxRate": 20.0,
"isTaxExempt": false,
"offerTariffType": "Normal",
"bucketValueConvertedInAmount": {
"value": 10.0,
"unit": "EUR"
}
}
],
"relatedParty": [
{
"id": "a396-5c90a41a23ea",
"href": "http://host:port/partyManagement/organization/a396-5c90a41a23ea",
"role": "serviceProvider",
"@referredType": "Organization"
},
{
"id": "8a41-d6451fe98963",
"href": "http://serverlocation:port/partyManagement/individual/8a41-d6451fe98963",

© TM Forum 2023. All Rights Reserved Page 34 of 13

C2 General
Usage Management API REST Specification

"role": "customer",
"@referredType": "Individual"
}
],
"status": "rated",
"usageType": "VOICE",
"usageCharacteristic": [
{
"name": "originatingCountryCode",
"value": "43"
},
{
"name": "originatingNumber",
"value": "676123456789"
},
{
"name": "destinationCountryCode",
"value": "49"
},
{
"name": "destinationNumber",
"value": "170123456789"
},
{
"name": "duration",
"value": "20"
},
{
"name": "unit",
"value": "SEC"
}
],
"usageSpecification": {
"id": "af59-b504c742900e",
"href": "https://api.csp.com/tmf-api/usageManagement/v4/usageSpecification/af59-b504c742900e",
"name": "VoiceCall"
}
}

Response

201

{
"id": "5130d5131a23",
"href": "https://api.csp.com/tmf-api/usageManagement/v4/usage/5130d5131a23",
"ratedProductUsage": [
{
"ratingDate": "2020-02-20T17:00:00.000Z",
"usageRatingTag": "Usage",
"ratingAmountType": "Total",
"taxIncludedRatingAmount": {
"value": 12.0,

© TM Forum 2023. All Rights Reserved Page 35 of 13

C2 General
Usage Management API REST Specification

"unit": "EUR"
},
"taxExcludedRatingAmount": {
"value": 10.0,
"unit": "EUR"
},
"taxRate": 20.0,
"isTaxExempt": false,
"offerTariffType": "Normal",
"bucketValueConvertedInAmount": {
"value": 10.0,
"unit": "EUR"
}
}
],
"relatedParty": [
{
"id": "a396-5c90a41a23ea",
"href": "http://host:port/partyManagement/organization/a396-5c90a41a23ea",
"role": "serviceProvider",
"@referredType": "Organization"
},
{
"id": "8a41-d6451fe98963",
"href": "http://serverlocation:port/partyManagement/individual/8a41-d6451fe98963",
"role": "customer",
"@referredType": "Individual"
}
],
"status": "rated",
"usageType": "VOICE",
"usageCharacteristic": [
{
"name": "originatingCountryCode",
"value": "43"
},
{
"name": "originatingNumber",
"value": "676123456789"
},
{
"name": "destinationCountryCode",
"value": "49"
},
{
"name": "destinationNumber",
"value": "170123456789"
},
{
"name": "duration",
"value": 20
},
{
"name": "unit",
"value": "SEC"

© TM Forum 2023. All Rights Reserved Page 36 of 13

C2 General
Usage Management API REST Specification

}
],
"usageSpecification": {
"id": "af59-b504c742900e",
"href": "https://api.csp.com/tmf-api/usageManagement/v4/usageSpecification/af59-b504c742900e",
"name": "VoiceCall"
}
}

Patch usage

PATCH /usage/{id}
Description

This operation allows partial updates of an usage entity. Support of json/merge

(https://tools.ietf.org/html/rfc7386) is mandatory, support of json/patch (http://tools.ietf.org/html/rfc5789) is
optional.

Note: If the update operation yields to the creation of sub-resources or relationships, the same rules concerning
mandatory sub-resource attributes and default value settings in the POST operation applies to the PATCH
operation. Hence these tables are not repeated here.

Patchable and Non Patchable Attributes

The tables below provide the list of patchable and non patchable attributes, including constraint rules on their
usage.

Patchable Attributes Rule

@baseType
@schemaLocation
@type
description
impactedBucket
ratedProductUsage
relatedParty
status
usageCharacteristic
usageSpecification
usageType

Non Patchable Attributes Rule

id
href
usageDate

Usage Samples

© TM Forum 2023. All Rights Reserved Page 37 of 13

C2 General
Usage Management API REST Specification

Changing the lifecycle state of a previous Usage event, changing the Usage with id 5130d5131a23

Request

PATCH /tmf-api/usageManagement/v4/usage/5130d5131a23
Content-Type: application/merge-patch+json

{
"status": "billed"
}

Response

200

{
"id": "5130d5131a23",
"href": "https://api.csp.com/tmf-api/usageManagement/v4/usage/5130d5131a23",
"ratedProductUsage": [
{
"ratingDate": "2020-02-20T17:00:00.000Z",
"usageRatingTag": "Usage",
"ratingAmountType": "Total",
"taxIncludedRatingAmount": {
"value": 12.0,
"unit": "EUR"
},
"taxExcludedRatingAmount": {
"value": 10.0,
"unit": "EUR"
},
"taxRate": 20.0,
"isTaxExempt": false,
"offerTariffType": "Normal",
"bucketValueConvertedInAmount": {
"value": 10.0,
"unit": "EUR"
}
}
],
"relatedParty": [
{
"id": "a396-5c90a41a23ea",
"href": "http://api.csp.com/tmf-api/partyManagement/v4/organization/a396-5c90a41a23ea",
"role": "serviceProvider",
"@referredType": "Organization"
},
{
"id": "8a41-d6451fe98963",
"href": "http://api.csp.com/tmf-api/partyManagement/v4/individual/8a41-d6451fe98963",
"role": "customer",
"@referredType": "Individual"

© TM Forum 2023. All Rights Reserved Page 38 of 13

C2 General
Usage Management API REST Specification

}
],
"status": "billed",
"usageType": "VOICE",
"usageCharacteristic": [
{
"name": "originatingCountryCode",
"value": "43"
},
{
"name": "originatingNumber",
"value": "676123456789"
},
{
"name": "destinationCountryCode",
"value": "49"
},
{
"name": "destinationNumber",
"value": "170123456789"
},
{
"name": "duration",
"value": "20"
},
{
"name": "unit",
"value": "SEC"
}
],
"usageSpecification": {
"id": "af59-b504c742900e",
"href": "https:/api.csp.com/tmf-api/UsageManagement/v4/usageSpecification/af59-b504c742900e",
"name": "VoiceCall"
}
}

Delete usage

DELETE /usage/{id}
Description

This operation deletes an usage entity.

Usage Samples

A request to delete an existing Usage event

© TM Forum 2023. All Rights Reserved Page 39 of 13

C2 General
Usage Management API REST Specification

Request

DELETE /tmf-api/usageManagement/v4/usage/5130d5131a23

Response

204

Operations on Usage Specification

List usage specifications

GET /usageSpecification?fields=...&{filtering}
Description

This operation list usage specification entities.

Attribute selection is enabled for all first level attributes.
Filtering may be available depending on the compliance level supported by an implementation.

Usage Samples

Retrieving previous UsageSpecifications which are at version 2.5

Request

GET /tmf-api/usageManagement/v4/usageSpecification?version=2.5
Accept: application/json

Response

200

[
{
"id": "91b2-43106cbc8191",
"href": "https://api.csp.com/tmf-api/usageManagement/v4/usageSpecification/91b2-43106cbc8191",
"description": "Specification of usage for voice calls",
"isBundle": false,
"lastUpdate": "2020-07-07T08:34:13.831Z",
"lifecycleStatus": "string",
"name": "Voice-Usage-Specification",

© TM Forum 2023. All Rights Reserved Page 40 of 13

C2 General
Usage Management API REST Specification

"version": "2.5",
"specCharacteristic": [
{
"name": "Originating Country Code",
"description": "Country Code of the caller",
"configurable": true,
"valueType": "string",
"minCardinality": 1,
"maxCardinality": 1
},
{
"name": "Originating Number",
"description": "Phone number of the caller",
"configurable": true,
"valueType": "string",
"minCardinality": 1,
"maxCardinality": 1
},
{
"name": "Destination Country Code",
"description": "Country Code of the recipient",
"configurable": true,
"valueType": "string",
"minCardinality": 1,
"maxCardinality": 1
},
{
"name": "Destination Number",
"description": "Phone number of the recipient",
"configurable": true,
"valueType": "string",
"minCardinality": 1,
"maxCardinality": 1
},
{
"name": "Duration",
"description": "Duration of the call in seconds",
"configurable": true,
"valueType": "number",
"minCardinality": 1,
"maxCardinality": 1
},
{
"name": "startDateTime",
"description": "Start date and start time of the call",
"configurable": true,
"valueType": "dateTime",
"minCardinality": 1,
"maxCardinality": 1
},
{
"name": "endDateTime",
"description": "End date and end time of the call",
"configurable": true,
"valueType": "dateTime",

© TM Forum 2023. All Rights Reserved Page 41 of 13

C2 General
Usage Management API REST Specification

"minCardinality": 1,
"maxCardinality": 1
}
]
}
]

Retrieve usage specification

GET /usageSpecification/{id}?fields=...&{filtering}
Description

This operation retrieves an usage specification entity.

Attribute selection is enabled for all first level attributes.
Filtering on sub-resources may be available depending on the compliance level supported by an implementation.

Usage Samples

A request for a specific UsageSpecification with an id 91b2-43106cbc8191

Request

GET /tmf-api/usageManagement/v4/usageSpecification/91b2-43106cbc8191
Accept: application/json

Response

200

{
"id": "91b2-43106cbc8191",
"href": "https://api.csp.com/tmf-api/usageManagement/v4/usageSpecification/91b2-43106cbc8191",
"description": "Specification of usage for voice calls",
"isBundle": false,
"lastUpdate": "2020-07-07T08:34:13.831Z",
"lifecycleStatus": "string",
"name": "Voice-Usage-Specification",
"version": "2.5",
"specCharacteristic": [
{
"name": "Originating Country Code",
"description": "Country Code of the caller",
"configurable": true,
"valueType": "string",
"minCardinality": 1,
"maxCardinality": 1

© TM Forum 2023. All Rights Reserved Page 42 of 13

C2 General
Usage Management API REST Specification

},
{
"name": "Originating Number",
"description": "Phone number of the caller",
"configurable": true,
"valueType": "string",
"minCardinality": 1,
"maxCardinality": 1
},
{
"name": "Destination Country Code",
"description": "Country Code of the recipient",
"configurable": true,
"valueType": "string",
"minCardinality": 1,
"maxCardinality": 1
},
{
"name": "Destination Number",
"description": "Phone number of the recipient",
"configurable": true,
"valueType": "string",
"minCardinality": 1,
"maxCardinality": 1
},
{
"name": "Duration",
"description": "Duration of the call in seconds",
"configurable": true,
"valueType": "number",
"minCardinality": 1,
"maxCardinality": 1
},
{
"name": "startDateTime",
"description": "Start date and start time of the call",
"configurable": true,
"valueType": "dateTime",
"minCardinality": 1,
"maxCardinality": 1
},
{
"name": "endDateTime",
"description": "End date and end time of the call",
"configurable": true,
"valueType": "dateTime",
"minCardinality": 1,
"maxCardinality": 1
}
]
}

Create usage specification

© TM Forum 2023. All Rights Reserved Page 43 of 13

C2 General
Usage Management API REST Specification

POST /usageSpecification
Description

This operation creates an usage specification entity.

Mandatory and Non Mandatory Attributes

The following tables provide the list of mandatory and non mandatory attributes when creating a
UsageSpecification, including any possible rule conditions and applicable default values. Notice that it is up to an
implementer to add additional mandatory attributes.

Mandatory Attributes Rule

Non Mandatory Attributes Rule

description
isBundle
lastUpdate
lifecycleStatus
name
version
@baseType
@schemaLocation
@type
attachment
constraint
entitySpecRelationship
relatedParty
specCharacteristic
targetEntitySchema
validFor

Usage Samples

Create a UsageSpecification for a Voice call - the resulting resource id is 8b64-0cfd1a90c9ed

Request

POST /tmf-api/usageManagement/v4/usageSpecification
Content-Type: application/json

{
"description": "Specification of usage for voice calls",
"isBundle": false,
"lastUpdate": "2020-07-07T08:34:13.831Z",
"name": "Voice-Usage-Specification",
"version": "2.5",
"specCharacteristic": [

© TM Forum 2023. All Rights Reserved Page 44 of 13

C2 General
Usage Management API REST Specification

{
"name": "Originating Country Code",
"description": "Country Code of the caller",
"configurable": true,
"valueType": "string",
"minCardinality": 1,
"maxCardinality": 1
},
{
"name": "Originating Number",
"description": "Phone number of the caller",
"configurable": true,
"valueType": "string",
"minCardinality": 1,
"maxCardinality": 1
},
{
"name": "Destination Country Code",
"description": "Country Code of the recipient",
"configurable": true,
"valueType": "string",
"minCardinality": 1,
"maxCardinality": 1
},
{
"name": "Destination Number",
"description": "Phone number of the recipient",
"configurable": true,
"valueType": "string",
"minCardinality": 1,
"maxCardinality": 1
},
{
"name": "Duration",
"description": "Duration of the call in seconds",
"configurable": true,
"valueType": "number",
"minCardinality": 1,
"maxCardinality": 1
},
{
"name": "startDateTime",
"description": "Start date and start time of the call",
"configurable": true,
"valueType": "dateTime",
"minCardinality": 1,
"maxCardinality": 1
},
{
"name": "endDateTime",
"description": "End date and end time of the call",
"configurable": true,
"valueType": "dateTime",
"minCardinality": 1,
"maxCardinality": 1

© TM Forum 2023. All Rights Reserved Page 45 of 13

C2 General
Usage Management API REST Specification

}
]
}

Response

201

{
"id": "8b64-0cfd1a90c9ed",
"href": "https://api.csp.com/tmf-api/usagemanagement/v4/usageSpecification/8b64-0cfd1a90c9ed",
"description": "Specification of usage for voice calls",
"isBundle": false,
"lastUpdate": "2020-07-07T08:34:13.831Z",
"name": "Voice-Usage-Specification",
"version": "2.5",
"specCharacteristic": [
{
"name": "Originating Country Code",
"description": "Country Code of the caller",
"configurable": true,
"valueType": "string",
"minCardinality": 1,
"maxCardinality": 1
},
{
"name": "Originating Number",
"description": "Phone number of the caller",
"configurable": true,
"valueType": "string",
"minCardinality": 1,
"maxCardinality": 1
},
{
"name": "Destination Country Code",
"description": "Country Code of the recipient",
"configurable": true,
"valueType": "string",
"minCardinality": 1,
"maxCardinality": 1
},
{
"name": "Destination Number",
"description": "Phone number of the recipient",
"configurable": true,
"valueType": "string",
"minCardinality": 1,
"maxCardinality": 1
},
{
"name": "Duration",
"description": "Duration of the call in seconds",
"configurable": true,

© TM Forum 2023. All Rights Reserved Page 46 of 13

C2 General
Usage Management API REST Specification

"valueType": "number",
"minCardinality": 1,
"maxCardinality": 1
},
{
"name": "startDateTime",
"description": "Start date and start time of the call",
"configurable": true,
"valueType": "dateTime",
"minCardinality": 1,
"maxCardinality": 1
},
{
"name": "endDateTime",
"description": "End date and end time of the call",
"configurable": true,
"valueType": "dateTime",
"minCardinality": 1,
"maxCardinality": 1
}
]
}

Patch usage specification

PATCH /usageSpecification/{id}
Description

This operation allows partial updates of an usage specification entity. Support of json/merge
(https://tools.ietf.org/html/rfc7386) is mandatory, support of json/patch (http://tools.ietf.org/html/rfc5789) is
optional.

Note: If the update operation yields to the creation of sub-resources or relationships, the same rules concerning
mandatory sub-resource attributes and default value settings in the POST operation applies to the PATCH
operation. Hence these tables are not repeated here.

Patchable and Non Patchable Attributes

The tables below provide the list of patchable and non patchable attributes, including constraint rules on their
usage.

Patchable Attributes Rule

description
isBundle
lastUpdate
lifecycleStatus
name
version
@baseType

© TM Forum 2023. All Rights Reserved Page 47 of 13

C2 General
Usage Management API REST Specification

@schemaLocation
@type
attachment
constraint
entitySpecRelationship
relatedParty
specCharacteristic
targetEntitySchema
validFor

Non Patchable Attributes Rule

id
href

Usage Samples

Changing the version of an existing UsageSpecification with an id of 903a-79a12c91b92a

Request

PATCH /tmf-api/usageManagement/v4/usageSpecification/903a-79a12c91b92a
Content-Type: application/merge-patch+json

{
"version": "3.0"
}

Response

200

{
"id": "903a-79a12c91b92a",
"href": "https://api.csp.com/tmf-api/usagemanagement/v4/usageSpecification/903a-79a12c91b92a",
"description": "Specification of usage for voice calls",
"isBundle": false,
"lastUpdate": "2020-07-07T08:34:13.831Z",
"name": "Voice-Usage-Specification",
"version": "3.0",
"specCharacteristic": [
{
"name": "Originating Country Code",
"description": "Country Code of the caller",
"configurable": true,
"valueType": "string",
"minCardinality": 1,
"maxCardinality": 1
},

© TM Forum 2023. All Rights Reserved Page 48 of 13

C2 General
Usage Management API REST Specification

{
"name": "Originating Number",
"description": "Phone number of the caller",
"configurable": true,
"valueType": "string",
"minCardinality": 1,
"maxCardinality": 1
},
{
"name": "Destination Country Code",
"description": "Country Code of the recipient",
"configurable": true,
"valueType": "string",
"minCardinality": 1,
"maxCardinality": 1
},
{
"name": "Destination Number",
"description": "Phone number of the recipient",
"configurable": true,
"valueType": "string",
"minCardinality": 1,
"maxCardinality": 1
},
{
"name": "Duration",
"description": "Duration of the call in seconds",
"configurable": true,
"valueType": "number",
"minCardinality": 1,
"maxCardinality": 1
},
{
"name": "startDateTime",
"description": "Start date and start time of the call",
"configurable": true,
"valueType": "dateTime",
"minCardinality": 1,
"maxCardinality": 1
},
{
"name": "endDateTime",
"description": "End date and end time of the call",
"configurable": true,
"valueType": "dateTime",
"minCardinality": 1,
"maxCardinality": 1
}
]
}

Delete usage specification

DELETE /usageSpecification/{id}
© TM Forum 2023. All Rights Reserved Page 49 of 13

C2 General
Usage Management API REST Specification

Description

This operation deletes an usage specification entity.

Usage Samples

A request to delete an existing UsageSpecification with an id of 8b64-0cfd1a90c9ed

Request

DELETE /tmf-api/usageManagement/v4/usageSpecification/8b64-0cfd1a90c9ed

Response

204

© TM Forum 2023. All Rights Reserved Page 50 of 13

C2 General
Usage Management API REST Specification

API NOTIFICATIONS
It is assumed that the Publish/Subscribe model uses the Register and UnRegister mechanisms described in the REST
Guidelines.

Register listener
POST /hub

Description

Sets the communication endpoint address the service instance must use to deliver information about its health
state, execution state, failures and metrics. Subsequent POST calls will be rejected by the service if it does not
support multiple listeners. In this case DELETE /api/hub/{id} must be called before an endpoint can be created
again.

Behavior

Returns HTTP/1.1 status code 204 if the request was successful.

Returns HTTP/1.1 status code 409 if request is not successful.

Usage Samples

Here's an example of a request for registering a listener.

Request

POST /api/hub
Accept: application/json

{"callback": "http://in.listener.com"}

Response

201
Content-Type: application/json
Location: /api/hub/42

{"id":"42","callback":"http://in.listener.com","query":null}

© TM Forum 2023. All Rights Reserved Page 51 of 13

C2 General
Usage Management API REST Specification

Unregister listener
DELETE /hub/{id}

Description

Clears the communication endpoint address that was set by creating the Hub..

Behavior

Returns HTTP/1.1 status code 204 if the request was successful.

Returns HTTP/1.1 status code 404 if the resource is not found.

Usage Samples

Here's an example of a request for un-registering a listener.

Request

DELETE /api/hub/42
Accept: application/json

Response

204

Publish Event to listener

POST /client/listener

Description

Clears the communication endpoint address that was set by creating the Hub.

Provides to a registered listener the description of the event that was raised. The /client/listener url is the callback
url passed when registering the listener.

Behavior

Returns HTTP/1.1 status code 201 if the service is able to set the configuration.

Usage Samples

Here's an example of a notification received by the listener. In this example “EVENT TYPE” should be replaced by
one of the notification types supported by this API (see Notification resources Models section) and EVENT BODY
refers to the data structure of the given notification type.

© TM Forum 2023. All Rights Reserved Page 52 of 13

C2 General
Usage Management API REST Specification

Request

POST /client/listener
Accept: application/json

{
"event": {
EVENT BODY
},
"eventType": "EVENT_TYPE"
}

Response

201

For detailed examples on the general TM Forum notification mechanism, see the TMF REST Design Guidelines.

© TM Forum 2023. All Rights Reserved Page 53 of 13

C2 General
Any Management API REST Specification

Acknowledgements

Release History

Release Date Release led by: Description

Number

Release 1.0 03/06/2016 Andreas Polz Mature draft of user-guide

(Infonova) developed during the SpecJam
sessions in Vienna, Mart 4-6TH 2014

Release 2.0 13/07/2020 Stephen Harrop Major update to accommodate

(Vodafone Group) patterns from TMF-API Design
Guidelines v4.0 and schema library
Yasen Pavlov based generation.
(Vodafone Germany)

Release 4.1.0 10/06/2023 Nuno Martins Including ImpactedBucket reference

(MATRIXX Software) to the Usage data model to be able
to describe the optional relationship
with Buckets.

Contributors to Document

© TM Forum 2023. All Rights Reserved Page 54 of

13

C2 General