TM Forum Specification

Customer Management API

REST Specification

TMF629
Release 18.0.0
June 2018

Latest Update: TM Forum Release 18.0.0 Member Evaluation

Version 3.0.1 IPR Mode: RAND
Customer Management API REST Specification

NOTICE
Copyright © TM Forum 2018. 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: [Link]

© TM Forum 2018. All Rights Reserved Page 2 of 35

Customer Management API REST Specification

TABLE OF CONTENTS
NOTICE ..................................................................................................................................................... 2
TABLE OF CONTENTS ............................................................................................................................... 3
LIST OF TABLES ........................................................................................................................................ 4
INTRODUCTION ....................................................................................................................................... 5
SAMPLE USE CASES.................................................................................................................................. 6
Support of polymorphism and extension patterns ................................................................................. 7
RESOURCE MODEL................................................................................................................................... 8
Managed Entity and Task Resource Models........................................................................................ 8
Customer resource ........................................................................................................................... 8
Field descriptions ............................................................................................................................. 9
Json representation sample ........................................................................................................... 14
Notification Resource Models ........................................................................................................... 15
Customer Creation Notification ..................................................................................................... 16
Customer Attribute Value Change Notification ............................................................................. 17
Customer State Change Notification.............................................................................................. 17
Customer Remove Notification ...................................................................................................... 18
API OPERATIONS.................................................................................................................................... 19
Operations on Customer ................................................................................................................... 19
List customers ................................................................................................................................ 19
Retrieve customer .......................................................................................................................... 22
Create customer ............................................................................................................................. 24
Patch customer .............................................................................................................................. 26
Delete customer ............................................................................................................................. 30
API NOTIFICATIONS ............................................................................................................................... 31
Register listener ................................................................................................................................. 31
Unregister listener ............................................................................................................................. 32
Publish Event to listener .................................................................................................................... 32
ACKNOWLEDGEMENTS ......................................................................................................................... 34
Version History .................................................................................................................................. 34
Release History .................................................................................................................................. 35
Contributors To Document ................................................................................................................ 35

© TM Forum 2018. All Rights Reserved Page 3 of 35

Customer Management API REST Specification

LIST OF TABLES

N/A

© TM Forum 2018. All Rights Reserved Page 4 of 35

Customer Management API REST Specification

INTRODUCTION
The following document is the specification of the REST API for Customer Management. It includes
the model definition as well as all available operations.

It provides a standardized mechanism for customer and customer account management

such as creation, update, retrieval, deletion and notification of events.
Customer can be a person, an organization or another service provider who buys products
from an enterprise. Customer management API allows management of identification and
financial information about him.
Customer management API manages the following data resources:
- Customer
o Customer represents a person or organization that buys products and services from the
enterprise or receives free offers or services. Customers can also be other service providers
who resell the enterprises products, other service providers that lease the enterprise's
resources for utilization by the other service provider's products and services, and so forth.
o Customer resource contains information about the customer. Main attributes are its
identifier, name, status and validity, description, characteristics, contact medium, related
customer account, related party, customer credit profile information

The customer management API performs the following operation on customer:

- Retrieval, creation, full or partial update and deletion of customers.

API Dependencies

This API assumes that the information regarding customer accounts and payment means is obtained
by accessing the Account Management API.

This API assumes that the information regarding related parties is obtained by accessing the Party
Management API.

© TM Forum 2018. All Rights Reserved Page 5 of 35

Customer Management API REST Specification

SAMPLE USE CASES

Reader will find example of use cases using Usage API in “Open Digital Business Scenarios and Use
Cases” document.

© TM Forum 2018. All Rights Reserved Page 6 of 35

Customer Management API REST Specification

SUPPORT OF POLYMORPHISM AND EXTENSION PATTERNS

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 BillingAccount and SettlementAccount inheriting
properties from the abstract Account entity.

Generic support of polymorphism and pattern extensions is described in the TMF API Guidelines v3.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 Account instances some may be instances of BillingAccount where other could be
instances of SettlementAccount. 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 an AccountRef 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 BillingAccountRef or
SettlementAccountRef, 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 2018. All Rights Reserved Page 7 of 35

Customer Management API REST Specification

RESOURCE MODEL

MANAGED ENTITY AND TASK RESOURCE MODELS

CUSTOMER RESOURCE
A Customer resource ...

Resource model

© TM Forum 2018. All Rights Reserved Page 8 of 35

Customer Management API REST Specification

FIELD DESCRIPTIONS
Customer fields

@baseType A string. Generic attribute indicating the base class type of the extension
class of the current object. Useful only when the class type of the current
object is unknown to the implementation.

@schemaLocation A string. Generic attribute containing the link to the schema that defines
the structure of the class type of the current object.

@type A string. Generic attribute containing the name of the resource class type.

href A string. Url used to reference the party role.

id A string. Unique identifier for PartyRoles.

name A string. A word, term, or phrase by which the PartyRole is known and
distinguished from other PartyRoles.

status A string. Used to track the lifecycle status of the party role.

statusReason A string. A string providing an explanation on the value of the status

lifecycle. For instance, if the status is Rejected, statusReason will provide
the reason for rejection.

validFor A time period. The time period that the PartyRole is valid for.

engagedParty A party reference (PartyRef). A party represents an organization or an

individual.

type A role type reference (RoleTypeRef). The role type - useful only in the
context of a partnership defining more than one role type.

account A list of account references (AccountRef [*]). An account may be a party

account or a financial account.

paymentMethod A list of payment method references (PaymentMethodRef [*]). A payment

method defines a specific mean of payment (e.g. direct debit).

contactMedium A list of contact mediums (ContactMedium [*]). Indicates the contact

medium that could be used to contact the party.

characteristic A list of characteristics (Characteristic [*]). Describes the characteristic of a

party role.

© TM Forum 2018. All Rights Reserved Page 9 of 35

Customer Management API REST Specification

creditProfile A list of credit profiles (CreditProfile [*]). Credit profile for the party
(containing credit scoring, ...). By default, only the current credit profile is
retrieved. It can be used as a list to give the party credit profiles history,
the first one in the list will be the current one.

agreement A list of agreement references (AgreementRef [*]). An agreement

represents a contract or arrangement, either written or verbal and
sometimes enforceable by law, such as a service level agreement or a
customer price agreement. An agreement involves a number of other
business entities, such as products, services, and resources and/or their
specifications.

relatedParty A list of related party references (RelatedPartyRef [*]). A related party

defines party or party role linked to a specific entity.

Characteristic sub-resource

Describes a given characteristic of an object or entity through a name/value pair.

name A string. Name of the characteristic.

value A string. The value of the characteristic provided as a string.

ContactMedium sub-resource

Indicates the contact medium that could be used to contact the party.

@baseType A string. Generic attribute indicating the base class type of the extension
class of the current object. Useful only when the class type of the current
object is unknown to the implementation.

@schemaLocation A string. Generic attribute containing the link to the schema that defines
the structure of the class type of the current object.

@type A string. Generic attribute containing the name of the resource class type.

preferred A boolean. If true, indicates that is the preferred contact medium.

type A string. Type of the contact medium, such as: email address, telephone
number, postal address.

validFor A time period. The time period that the contact medium is valid for.

characteristic A medium characteristic (MediumCharacteristic). Describes the contact

medium characteristics that could be used to contact a party (an
individual or an organization).

© TM Forum 2018. All Rights Reserved Page 10 of 35

Customer Management API REST Specification

CreditProfile sub-resource

Credit profile for the party (containing credit scoring, ...). By default, only the current credit profile is
retrieved. It can be used as a list to give the party credit profiles history, the first one in the list will be
the current one.

@baseType A string. Generic attribute indicating the base class type of the extension
class of the current object. Useful only when the class type of the current
object is unknown to the implementation.

@schemaLocation A string. Generic attribute containing the link to the schema that defines
the structure of the class type of the current object.

@type A string. Generic attribute containing the name of the resource class type.

creditProfileDate A date time (DateTime). The date the profile was established.

creditRiskRating An integer. This is an integer whose value is used to rate the risk.

creditScore An integer. A measure of a person's or an organization's creditworthiness

calculated on the basis of a combination of factors such as their income
and credit history.

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

MediumCharacteristic sub-resource

Describes the contact medium characteristics that could be used to contact a party (an individual or
an organization).

city A string. The city.

country A string. The country.

emailAddress A string. Full email address in standard format.

faxNumber A string. The fax number of the contact.

phoneNumber A string. The primary phone number of the contact.

postCode A string. Postcode.

stateOrProvince A string. State or province.

street1 A string. Describes the street.

street2 A string. Complementary street description.

© TM Forum 2018. All Rights Reserved Page 11 of 35

Customer Management API REST Specification

type A string. Type of medium (fax, mobile phone...).

AccountRef relationship

Account reference. A account may be a party account or a financial account.

@referredType A string. Generic attribute indicating the name of the class type of the
referred resource entity.

description A string. Detailed description of the account.

href A string. Reference of the account.

id A string. Unique identifier of the account.

name A string. Name of the account.

AgreementRef relationship

Agreement reference. An agreement represents a contract or arrangement, either written or verbal

and sometimes enforceable by law, such as a service level agreement or a customer price agreement.
An agreement involves a number of other business entities, such as products, services, and resources
and/or their specifications.

@referredType A string. Generic attribute indicating the name of the class type of the
referred resource entity.

href A string. Reference of the agreement.

id A string. Identifier of the agreement.

name A string. Name of the agreement.

PartyRef relationship

Party reference. A party represents an organization or an individual.

@referredType A string. Generic attribute indicating the name of the class type of the
referred resource entity.

description A string. Text describing the referred party.

href A string. Reference of the referred party (such as a partner or any other
party role).

id A string. Unique identifier of the referred party.

© TM Forum 2018. All Rights Reserved Page 12 of 35

Customer Management API REST Specification

name A string. Name of the referred party (such as a partner or any other party
role).

PaymentMethodRef relationship

PaymentMethod reference. A payment method defines a specific mean of payment (e.g. direct
debit).

@referredType A string. Generic attribute indicating the name of the class type of the
referred resource entity.

href A string. Reference of the payment mean.

id A string. Unique identifier of the payment mean.

name A string. Name of the payment mean.

RelatedPartyRef relationship

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

@referredType A string. Generic attribute indicating the name of the class type of the
referred resource entity.

href A string. Reference of the related party, could be a party reference or a

party role reference.

id A string. Unique identifier of a related party.

name A string. Name of the related party.

role A string. Role of the related party.

RoleTypeRef relationship

RoleType reference.

@referredType A string. Generic attribute indicating the name of the class type of the
referred resource entity.

name A string. The name of the role type. It uniquely identifies the role type
within the partnership type.

partnershipHref A string. Reference url of the partnership type containing the role type.

partnershipId A string. The identifier of the partnership type containing the role type.

partnershipName A string. The name of the partnership type defining this role type.

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

Customer Management API REST Specification

JSON REPRESENTATION SAMPLE

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

{
"href": "[Link]
"id": "1140",
"name": "Moon Football Club",
"status": "Approved",
"statusReason": "Account details checked",
"validFor": {
"startDateTime": "2018-06-12T00:00",
"endDateTime": "2019-01-11T00:00"
},
"engagedParty": [
{
"href": "[Link]
"id": "500",
"name": "Happy Travellers"
}
],
"account": [
{
"description": "This account ...",
"href": "[Link]
"id": "8251",
"name": "Travel Account"
}
],
"paymentMethod": [
{
"href": "[Link]
"id": "9562",
"name": "professional payment"
}
],
"contactMedium": [
{
"preferred": false,
"type": "TelephoneNumber",
"validFor": {
"startDateTime": "2018-06-13T00:00",
"endDateTime": "2019-01-11T00:00"
},
"characteristic": {
"city": "Paris",
"street1": "15 Rue des Canards",
"emailAddress": "[Link]@[Link]",
© TM Forum 2018. All Rights Reserved Page 14 of 35
Customer Management API REST Specification

"postCode": "75014",
"country": "France",
"type": "home"
}
}
],
"characteristic": [
{"name":"fidelityProgram","value":"premium"}
],
"creditProfile": [
{
"creditProfileDate": "2018-06-15T00:00",
"creditRiskRating": 4,
"creditScore": 5,
"validFor": {
"startDateTime": "2018-06-13T00:00",
"endDateTime": "2019-01-11T00:00"
}
}
],
"agreement": [
{
"href": "[Link]
"id": "4721",
"name": "Summer Contract Agreement"
}
],
"relatedParty": [
{
"href": "[Link]
"id": "2777",
"name": "John Doe",
"role": "bill receiver"
}
]
}

NOTIFICATION RESOURCE MODELS

4 notifications are defined for this API

Notifications related to Customer:

- CustomerCreationNotification
- CustomerAttributeValueChangeNotification

© TM Forum 2018. All Rights Reserved Page 15 of 35

Customer Management API REST Specification

- CustomerStateChangeNotification
- CustomerRemoveNotification

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

CUSTOMER CREATION NOTIFICATION

Notification sent when a new Customer resource is created.

Json representation sample

© TM Forum 2018. All Rights Reserved Page 16 of 35
Customer Management API REST Specification

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

notification object

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"CustomerCreationNotification",
"event": {
"customer" :
{-- SEE Customer RESOURCE SAMPLE --}
}
}

CUSTOMER ATTRIBUTE VALUE CHANGE NOTIFICATION

Notification sent when changing an attribute of a Customer resource.

Json representation sample

We provide below the json representation of an example of a

'CustomerAttributeValueChangeNotification' notification object

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"CustomerAttributeValueChangeNotification",
"event": {
"customer" :
{-- SEE Customer RESOURCE SAMPLE --}
}
}

CUSTOMER STATE CHANGE NOTIFICATION

Notification sent when changing the state of a Customer resource.

Json representation sample

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

notification object

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"CustomerStateChangeNotification",

© TM Forum 2018. All Rights Reserved Page 17 of 35

Customer Management API REST Specification

"event": {
"customer" :
{-- SEE Customer RESOURCE SAMPLE --}
}
}

CUSTOMER REMOVE NOTIFICATION

Notification sent when removing a Customer resource.

Json representation sample

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

notification object

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"CustomerRemoveNotification",
"event": {
"customer" :
{-- SEE Customer RESOURCE SAMPLE --}
}
}

© TM Forum 2018. All Rights Reserved Page 18 of 35

Customer 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

Complete Update of an PUT Resource PUT must be used to

Entity completely update a
resource identified by its
resource URI

Remove an Entity DELETE Resource DELETE must be used to

remove a resource

Execute an Action on an POST on TASK Resource POST must be used to

Entity 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 CUSTOMER

LIST CUSTOMERS
© TM Forum 2018. All Rights Reserved Page 19 of 35
Customer Management API REST Specification

GET /customer?fields=...&{filtering}

Description

This operation list customer 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

Here's an example of a request for retrieving Customer resources.

Request

GET {apiRoot}/customer
Accept: application/json

Response

200

[
{
"href": "[Link]
"id": "1140",
"name": "Moon Football Club",
"status": "Approved",
"statusReason": "Account details checked",
"validFor": {
"startDateTime": "2018-06-12T00:00",
"endDateTime": "2019-01-11T00:00"
},
"engagedParty": [
{
"href": "[Link]
"id": "500",
"name": "Happy Travellers"
}
],
"account": [
{
"description": "This account ...",
"href": "[Link]
© TM Forum 2018. All Rights Reserved Page 20 of 35
Customer Management API REST Specification

"id": "8251",
"name": "Travel Account"
}
],
"paymentMethod": [
{
"href": "[Link]
"id": "9562",
"name": "professional payment"
}
],
"contactMedium": [
{
"preferred": false,
"type": "TelephoneNumber",
"validFor": {
"startDateTime": "2018-06-13T00:00",
"endDateTime": "2019-01-11T00:00"
},
"characteristic": {
"city": "Paris",
"country": "France",
"emailAddress": "[Link]@[Link]",
"postCode": "75014",
"street1": "15 Rue des Canards",
"type": "home"
}
}
],
"characteristic": [
{
"name": "fidelityProgram",
"value": "premium"
}
],
"creditProfile": [
{
"creditProfileDate": "2018-06-15T00:00",
"creditRiskRating": 4,
"creditScore": 5,
"validFor": {
"startDateTime": "2018-06-13T00:00",
"endDateTime": "2019-01-11T00:00"
}
}
],
"agreement": [
{
© TM Forum 2018. All Rights Reserved Page 21 of 35
Customer Management API REST Specification

"href": "[Link]
"id": "4721",
"name": "Summer Contract Agreement"
}
],
"relatedParty": [
{
"href": "[Link]
"id": "2777",
"name": "John Doe",
"role": "bill receiver"
}
]
}
]

RETRIEVE CUSTOMER
GET /customer/{id}?fields=...&{filtering}

Description

This operation retrieves a customer 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

Here's an example of a request for retrieving a Customer resource.

Request

GET {apiRoot}/customer/1140
Accept: application/json

Response

200

© TM Forum 2018. All Rights Reserved Page 22 of 35

Customer Management API REST Specification

"href": "[Link]
"id": "1140",
"name": "Moon Football Club",
"status": "Approved",
"statusReason": "Account details checked",
"validFor": {
"startDateTime": "2018-06-12T00:00",
"endDateTime": "2019-01-11T00:00"
},
"engagedParty": [
{
"href": "[Link]
"id": "500",
"name": "Happy Travellers"
}
],
"account": [
{
"description": "This account ...",
"href": "[Link]
"id": "8251",
"name": "Travel Account"
}
],
"paymentMethod": [
{
"href": "[Link]
"id": "9562",
"name": "professional payment"
}
],
"contactMedium": [
{
"preferred": false,
"type": "TelephoneNumber",
"validFor": {
"startDateTime": "2018-06-13T00:00",
"endDateTime": "2019-01-11T00:00"
},
"characteristic": {
"city": "Paris",
"country": "France",
"emailAddress": "[Link]@[Link]",
"postCode": "75014",
"street1": "15 Rue des Canards",
"type": "home"
}
}
© TM Forum 2018. All Rights Reserved Page 23 of 35
Customer Management API REST Specification

],
"characteristic": [
{
"name": "fidelityProgram",
"value": "premium"
}
],
"creditProfile": [
{
"creditProfileDate": "2018-06-15T00:00",
"creditRiskRating": 4,
"creditScore": 5,
"validFor": {
"startDateTime": "2018-06-13T00:00",
"endDateTime": "2019-01-11T00:00"
}
}
],
"agreement": [
{
"href": "[Link]
"id": "4721",
"name": "Summer Contract Agreement"
}
],
"relatedParty": [
{
"href": "[Link]
"id": "2777",
"name": "John Doe",
"role": "bill receiver"
}
]
}

CREATE CUSTOMER
POST /customer

Description

This operation creates a customer entity.

Mandatory and Non Mandatory Attributes

© TM Forum 2018. All Rights Reserved Page 24 of 35

Customer Management API REST Specification

The following tables provides the list of mandatory and non mandatory attributes when creating a
Customer, 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

name

Non Mandatory Attributes Default Value Rule

@baseType
@schemaLocation
@type
status
statusReason
validFor
engagedParty
type
account
paymentMethod
contactMedium
characteristic
creditProfile
agreement
relatedParty

Additional Rules

The following table provides additional rules indicating mandatory fields in sub-resources or
relationships when creating a Customer resource.

Context Mandatory Sub-Attributes

engagedParty id, href
characteristic name, value
contactMedium type, characteristic
account id, href, name
creditProfile creditProfileDate, validFor
paymentMethod id, href

Default Values Summary

When creating the resource, the following table summarizes the default values applicable to optional
attributes of the resource (or sub-resources).

Attributes Default Value

id Automatically generated
© TM Forum 2018. All Rights Reserved Page 25 of 35
Customer Management API REST Specification

Attributes Default Value

engagedParty Automatically generated using the name of the customer
whenever possible.

Usage Samples

Here's an example of a request for creating a Customer resource. In this example the request only
passes mandatory attributes. In this example, the engaged party is searched based on the customer
name, then it is included in the result (retrieved if existing or created on the fly if not existing).

Request

POST {apiRoot}/customer
Content-Type: application/json

{
"name": "Moon Football Club"
}

Response

201

{
"href": "[Link]
"id": "1140",
"name": "Moon Football Club",
"engagedParty": [
{
"href": "[Link]
"id": "500",
"name": "Moon Football Club "
}
]
}

PATCH CUSTOMER
PATCH /customer/{id}

Description

© TM Forum 2018. All Rights Reserved Page 26 of 35

Customer Management API REST Specification

This operation allows partial updates of a customer entity. Support of json/merge

([Link] is mandatory, support of json/patch
([Link] 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
name
status
statusReason
validFor
engagedParty
type
account
paymentMethod
contactMedium
characteristic
creditProfile
agreement
relatedParty

Non Patchable Attributes Rule

id
href

Usage Samples

Here's an example of a request for patching a Customer resource.

Request

PATCH {apiRoot}/customer/1140
Content-Type: application/merge-patch+json

© TM Forum 2018. All Rights Reserved Page 27 of 35

Customer Management API REST Specification

{
"name": "new name"
}

Response

201

{
"href": "[Link]
"id": "1140",
"name": "new name",
"status": "Approved",
"statusReason": "Account details checked",
"validFor": {
"startDateTime": "2018-06-12T00:00",
"endDateTime": "2019-01-11T00:00"
},
"engagedParty": [
{
"href": "[Link]
"id": "500",
"name": "Happy Travellers"
}
],
"account": [
{
"description": "This account ...",
"href": "[Link]
"id": "8251",
"name": "Travel Account"
}
],
"paymentMethod": [
{
"href": "[Link]
"id": "9562",
"name": "professional payment"
}
],
"contactMedium": [
{
"preferred": false,
"type": "TelephoneNumber",
"validFor": {
© TM Forum 2018. All Rights Reserved Page 28 of 35
Customer Management API REST Specification

"startDateTime": "2018-06-13T00:00",
"endDateTime": "2019-01-11T00:00"
},
"characteristic": {
"city": "Paris",
"country": "France",
"emailAddress": "[Link]@[Link]",
"postCode": "75014",
"street1": "15 Rue des Canards",
"type": "home"
}
}
],
"characteristic": [
{
"name": "fidelityProgram",
"value": "premium"
}
],
"creditProfile": [
{
"creditProfileDate": "2018-06-15T00:00",
"creditRiskRating": 4,
"creditScore": 5,
"validFor": {
"startDateTime": "2018-06-13T00:00",
"endDateTime": "2019-01-11T00:00"
}
}
],
"agreement": [
{
"href": "[Link]
"id": "4721",
"name": "Summer Contract Agreement"
}
],
"relatedParty": [
{
"href": "[Link]
"id": "2777",
"name": "John Doe",
"role": "bill receiver"
}
]
}

© TM Forum 2018. All Rights Reserved Page 29 of 35

Customer Management API REST Specification

DELETE CUSTOMER
DELETE /customer/{id}

Description

This operation deletes a customer entity.

Usage Samples

Here's an example of a request for deleting a Customer resource.

Request

DELETE {apiRoot}/customer/42

Response

204

© TM Forum 2018. All Rights Reserved Page 30 of 35

Customer Management API REST Specification

API NOTIFICATIONS
For every single of operation on the entities use the following templates and provide sample REST
notification POST calls.

It is assumed that the Pub/Sub uses the Register and UnRegister mechanisms described in the REST
Guidelines reproduced below.

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": "[Link]

Response

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

{"id":"42","callback":"[Link]

© TM Forum 2018. All Rights Reserved Page 31 of 35

Customer 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

© TM Forum 2018. All Rights Reserved Page 32 of 35

Customer Management API REST Specification

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.

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 2018. All Rights Reserved Page 33 of 35

Customer Management API REST Specification

ACKNOWLEDGEMENTS

VERSION HISTORY

Version Date Release led by: Description

Number

0.a 28/11/2013 Arindam Basu (Ericsson) Initial Spec prepared in the TMF
Sudipta Dutta (Ericsson) Conference held at Bangalore, India
Brinda Santh M (IBM) (Nov 26 to Nov 28)
Hemant Gour (IBM)
Shashank Singh (IBM)
Vishal Aggarwal (IBM)
Nitish Jaisoor (Infosys)
Rajesh Gannaprapu (Infosys)
Srinivasan Duraiswamy
(Infosys)
Veeramani K (Infosys)
0.b 5/03/2014 Christian Traxler (Infonova) Extension of customer API mgmt.
Alexander Sturn (Infonova) during Spec Jam held in Vienna,
Gilbert Scheiblhofer (A1) Austria
Josh Salomon (Amdocs)
Véronique Mauneau (Orange)
Maxime Delon (Orange)
2.0 15/04/2016 Pierre Gauthier (TM Forum) Regenerated from API Data Model
Mariano Belaunde (Orange) and re-branded.
Does not include any more
accounting and payment mean
resources since this is provided
through the Accounting API.

3.0 15-Jun-2018 Mariano Belaunde (Orange) Update to support Guidelines 3.0

3.0.1 27-Jun-2018 Adrienne Walcott Formatting/style edits prior to R18

publishing.

© TM Forum 2018. All Rights Reserved Page 34 of 35

Customer Management API REST Specification

RELEASE HISTORY

Release Date Release led by: Description

Number

18.0.0 25-Jun-2018 Arindam Basu (Ericsson) Initial Release

Sudipta Dutta (Ericsson)
Brinda Santh M (IBM)
Hemant Gour (IBM)
Shashank Singh (IBM)
Vishal Aggarwal (IBM)
Nitish Jaisoor (Infosys)
Rajesh Gannaprapu (Infosys)
Srinivasan Duraiswamy
(Infosys)
Veeramani K (Infosys)

CONTRIBUTORS TO DOCUMENT

Veronique Mauneau Orange

Jean-Luc Tymen Orange

Mariano Belaunde Orange

Pierre Gauthier TM Forum

John Morey Ciena

Cliff C Faurer AMKB Cloud

© TM Forum 2018. All Rights Reserved Page 35 of 35