TM Forum Specification

Account Management
API REST Specification

TMF666
Release 17.0.1
November 2017

Latest Update: TM Forum Release 17 TM Forum Approved

Version 1.0.1 IPR Mode: RAND

TM Forum 2017. All Rights Reserved.

Account Management API REST Specification

NOTICE
Copyright © TM Forum 2017. 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.

TM FORUM invites any TM FORUM Member or any other party that believes it has patent claims that
would necessarily be infringed by implementations of this TM Forum Standards Final Deliverable, to notify
the TM FORUM Team Administrator and provide an indication of its willingness to grant patent licenses to
such patent claims in a manner consistent with the IPR Mode of the TM FORUM Collaboration Project
Team that produced this deliverable.

The TM FORUM invites any party to contact the TM FORUM Team Administrator if it is aware of a claim
of ownership of any patent claims that would necessarily be infringed by implementations of this TM
FORUM Standards Final Deliverable by a patent holder that is not willing to provide a license to such
patent claims in a manner consistent with the IPR Mode of the TM FORUM Collaboration Project Team
that produced this TM FORUM Standards Final Deliverable. TM FORUM may include such claims on its
website, but disclaims any obligation to do so.

TM FORUM takes no position regarding the validity or scope of any intellectual property or other rights
that might be claimed to pertain to the implementation or use of the technology described in this TM
FORUM Standards Final Deliverable or the extent to which any license under such rights might or might
not be available; neither does it represent that it has made any effort to identify any such rights.
Information on TM FORUM's procedures with respect to rights in any document or deliverable produced
by a TM FORUM Collaboration Project Team can be found on the TM FORUM website. Copies of claims
of rights made available for publication and any assurances of licenses to be made available, or the result
of an attempt made to obtain a general license or permission for the use of such proprietary rights by
implementers or users of this TM FORUM Standards Final Deliverable, can be obtained from the TM
FORUM Team Administrator. TM FORUM makes no representation that any information or list of
intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential
Claims.

© TM Forum 2017. All Rights Reserved. Page 2

Account Management API REST Specification

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 2017. All Rights Reserved. Page 3

Account Management API REST Specification

TABLE OF CONTENTS
NOTICE ........................................................................................................................................ 2

Table of Contents.......................................................................................................................... 4

List of Tables ................................................................................................................................ 7

Introduction ................................................................................................................................... 8

SAMPLE USE CASES .................................................................................................................. 9

RESOURCE MODEL .................................................................................................................. 10

Managed Entity and Task Resource Models ........................................................................................ 10

Party Account resource ..................................................................................................................... 10

Billing Account resource .................................................................................................................... 20

Settlement Account resource ............................................................................................................. 30

Financial Account resource ............................................................................................................... 39

Billing Cycle Specification resource ................................................................................................... 46

Bill Format resource .......................................................................................................................... 48

Bill Presentation Media resource ....................................................................................................... 48

Notification Resource Models ............................................................................................................... 49

Party Account Attribute Value Change Notification ............................................................................ 50

Party Account State Change Notification ........................................................................................... 51

Billing Account Attribute Value Change Notification ........................................................................... 51

Billing Account State Change Notification .......................................................................................... 51

Settlement Account Attribute Value Change Notification.................................................................... 52

Settlement Account State Change Notification .................................................................................. 52

Financial Account Creation Notification ............................................................................................. 53

Financial Account Attribute Value Change Notification ...................................................................... 53

Financial Account State Change Notification ..................................................................................... 53

Financial Account Remove Notification .............................................................................................. 54

API OPERATIONS...................................................................................................................... 55

Operations on Party Account ................................................................................................................ 55

© TM Forum 2017. All Rights Reserved. Page 4

Account Management API REST Specification

List party accounts............................................................................................................................. 55

Retrieve party account ....................................................................................................................... 56

Create party account ......................................................................................................................... 60

Patch party account ........................................................................................................................... 61

Delete party account.......................................................................................................................... 63

Operations on Billing Account............................................................................................................... 63

List billing accounts ........................................................................................................................... 63

Retrieve billing account...................................................................................................................... 64

Create billing account ........................................................................................................................ 68

Patch billing account.......................................................................................................................... 69

Delete billing account ........................................................................................................................ 71

Operations on Settlement Account ....................................................................................................... 71

List settlement accounts .................................................................................................................... 72

Retrieve settlement account .............................................................................................................. 72

Create settlement account ................................................................................................................. 76

Patch settlement account .................................................................................................................. 77

Delete settlement account ................................................................................................................. 79

Operations on Financial Account .......................................................................................................... 80

List financial accounts ....................................................................................................................... 80

Retrieve financial account.................................................................................................................. 82

Create financial account .................................................................................................................... 84

Patch financial account ...................................................................................................................... 86

Delete financial account..................................................................................................................... 89

Operations on Billing Cycle Specification.............................................................................................. 90

List billing cycle specifications ........................................................................................................... 90

Retrieve billing cycle specification ..................................................................................................... 91

Create billing cycle specification ........................................................................................................ 91

Patch billing cycle specification.......................................................................................................... 93

© TM Forum 2017. All Rights Reserved. Page 5

Account Management API REST Specification

Delete billing cycle specification ........................................................................................................ 94

Operations on Bill Format ..................................................................................................................... 95

List bill formats .................................................................................................................................. 95

Retrieve bill format............................................................................................................................. 95

Create bill format ............................................................................................................................... 96

Patch bill format ................................................................................................................................. 97

Delete bill format................................................................................................................................ 98

Operations on Bill Presentation Media .................................................................................................. 99

List bill presentation medias .............................................................................................................. 99

Retrieve bill presentation media....................................................................................................... 100

Create bill presentation media ......................................................................................................... 100

Patch bill presentation media ........................................................................................................... 101

Delete bill presentation media.......................................................................................................... 102

API NOTIFICATIONS................................................................................................................ 104

Register listener ................................................................................................................................. 104

Unregister listener .............................................................................................................................. 104

Publish Event to listener ..................................................................................................................... 105

Acknowledgments ..................................................................................................................... 107

Release History .................................................................................................................................. 107

Contributors to Document ................................................................................................................... 107

© TM Forum 2017. All Rights Reserved. Page 6

Account Management API REST Specification

LIST OF TABLES

N/A

© TM Forum 2017. All Rights Reserved. Page 7

Account Management API REST Specification

INTRODUCTION

The Account API provides a standardized mechanism for the management of billing and settlement accounts, as
well as for financial accounting (account receivable) either in B2B or B2B2C contexts.
It allows creation, update and retrieval of account information either in a B2B2C relationship context (creation of
mass market customer billing account within a “Billing on Behalf of” process for example) or in a B2B context
(creation of a billing/settlement account for a partner or B2B customer).
It also allows creation and query of bill items allowing partners or B2B customer to check their invoice.
Accounts typically refer to parties and party roles. However, the management of party and party roles is out of the
scope of this API. The TMF APIs Party Management, Customer Management and Party Role Management can
be used for this purpose.

© TM Forum 2017. All Rights Reserved. Page 8

Account Management API REST Specification

SAMPLE USE CASES

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

© TM Forum 2017. All Rights Reserved. Page 9

Account Management API REST Specification

RESOURCE MODEL

Managed Entity and Task Resource Models

PARTY ACCOUNT RESOURCE

Account used for billing or for settlement purposes concerning a given party (an organization or an
individual).

Resource model

© TM Forum 2017. All Rights Reserved. Page 10

Account Management API REST Specification

Lifecycle

© TM Forum 2017. All Rights Reserved. Page 11

Account Management API REST Specification

The Party Account lifecycle is tracked by the 'state' attribute. Typical lifecycle values are: Defined, Active,
Suspended, pending Update, pending Closed, Closed.
Note that an implementation of the specification may enrich the list of states depicted in the diagram. The
state machine specifying the typical state change transitions is provided below.

Field descriptions

PartyAccount fields

creditLimit A money (Money). The maximum amount of money that may be charged on
an account.

description A string. Detailed description of the party account.

href A string. Unique reference of the account.

id A string. Unique identifier of the account.

lastModified A date time (DateTime). Date of last modification of the account.

name A string. Name of the account.

state A string. Contains the lifecycle state such as: Active, Closed, Suspended and
so on.

© TM Forum 2017. All Rights Reserved. Page 12

Account Management API REST Specification

type A string. A categorization of an account, such as individual, joint, and so forth,

whose instances share some of the same characteristics. Note: for flexibility
we use a String here but an implementation may use an enumeration with a
limited list of valid values.

billStructure A bill structure (BillStructure). The structure of the bill for party accounts
(billing or settlement).

paymentPlan A list of payment plans (PaymentPlan [*]). Defines a plan for payment (when a
party wants to spread his payments).

financialAccount A financial account reference (FinancialAccountRef). AccountReceivable

reference. An account of money owed by a party to another entity in exchange
for goods or services that have been delivered or used. An account receivable
aggregates the amounts of one or more party accounts (billing or settlement)
owned by a given party.

defaultPaymentMethod A payment method reference (PaymentMethodRef). A payment method

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

relatedParty A list of related party references (RelatedPartyRef [*]). A related party defines
party or party role linked to a specific entity.

taxExemption A list of account tax exemptions (AccountTaxExemption [*]). Proof of freedom

from taxes imposed by a taxing jurisdiction.

contact A list of contacts (Contact [*]). An individual or an organization used as a

contact point for a given account and accessed via some contact medium.

accountBalance A list of account balances (AccountBalance [*]). Balances linked to the

account.

accountRelationship A list of account relationships (AccountRelationship [*]). Significant connection

between accounts. For instance an aggregating account for a list of shop
branches each having its own billing account.

AccountBalance sub-resource

Balances linked to the account.

amount A money (Money). Balance amount.

type A string. Type of the balance : deposit balance, disputed balance, loyalty
balance, receivable balance...

validFor A time period. Balance validity period.

AccountRelationship sub-resource

Significant connection between accounts. For instance an aggregating account for a list of shop branches
each having its own billing account.

© TM Forum 2017. All Rights Reserved. Page 13

Account Management API REST Specification

relationshipType A string. Type of relationship.

validFor A time period. Validity period of that relationship.

account An account reference (AccountRef). An account may be a party account or a

financial account.

AccountTaxExemption sub-resource

Proof of freedom from taxes imposed by a taxing jurisdiction.

certificateNumber A string. Identifier of a document that shows proof of exemption from taxes for
the taxing jurisdiction.

issuingJurisdiction A string. Name of the taxing jurisdiction for which taxes are exempt.

reason A string. Reason of the tax exemption.

validFor A time period. Period for which the exemption is valid.

BillStructure sub-resource

The structure of the bill for party accounts (billling or settlement).

presentationMedia A list of bill presentation media references (BillPresentationMediaRef [*]).

PresentationMedia reference. A mean of communicating a bill, supported by
the associated bill format. For example, post mail, email, web page.

format A bill format reference (BillFormatRef). A bill format is a description of the way
in which a bill is presented.

cycleSpecification A billing cycle specification reference (BillingCycleSpecificationRef). A

description of when to initiate a billing cycle and the various sub steps of a
billing cycle.

Contact sub-resource

An individual or an organization used as a contact point for a given account and accessed via some
contact medium.

contactName A string. A displayable name for that contact.

contactType A string. Type of contact (primary, secondary...).

partyRoleType A string. Identifies what kind of party role type is linked to the contact (a
account manager...).

validFor A time period. Validity period of that contact.

contactMedium A list of contact mediums (ContactMedium [*]). Indicates the contact medium
that could be used to contact the party.

© TM Forum 2017. All Rights Reserved. Page 14

Account Management API REST Specification

relatedParty A related party reference (RelatedPartyRef). A related party defines party or

party role linked to a specific entity.

ContactMedium sub-resource

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

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).

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.

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

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 positive floating point number.

PaymentPlan sub-resource

Defines a plan for payment (when a party wants to spread his payments).

© TM Forum 2017. All Rights Reserved. Page 15

Account Management API REST Specification

numberOfPayments An integer. Number of payments used to spread the global payment.

paymentFrequency A string. Frequency of the payments, such as monthly and bimonthly.

priority An integer. Priority of the payment plan.

status A string. Status of the payment plan (effective, ineffective).

totalAmount A money (Money). Amount paid.

type A string. Type of payment plan.

validFor A time period. Validity period of the payment plan.

paymentMethod A payment method reference (PaymentMethodRef). A payment method

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

AccountRef relationship

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

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.

BillFormatRef relationship

BillFormat reference. A bill format is a description of the way in which a bill is presented.

href A string. Reference of the bill format.

id A string. Unique identifier of the bill format.

name A string. A short descriptive name.

BillPresentationMediaRef relationship

PresentationMedia reference. A mean of communicating a bill, supported by the associated bill format. For
example, post mail, email, web page.

href A string. Reference of the bill presentation media.

id A string. Unique identifier of the bill presentation media.

name A string. A short descriptive name.

BillingCycleSpecificationRef relationship

BillingCycleSpecification reference. A description of when to initiate a billing cycle and the various sub
steps of a billing cycle.

© TM Forum 2017. All Rights Reserved. Page 16

Account Management API REST Specification

dateShift An integer. An offset of a billing/settlement date. The offset is expressed as

number of days with regard to the start of the billing/settlement period.

frequency A string. Frequency of the billing cycle (monthly for instance).

href A string. Reference of the billing cycle specification.

id A string. Unique identifier of the billing cycle specification.

name A string. A short descriptive name.

FinancialAccountRef relationship

AccountReceivable reference. An account of money owed by a party to another entity in exchange for
goods or services that have been delivered or used. An account receivable aggregates the amounts of
one or more party accounts (billing or settlement) owned by a given party.

href A string. Unique reference of the account.

id A string. Unique identifier of the account.

name A string. Name of the account.

accountBalance An account balance (AccountBalance). Balances linked to the account.

PaymentMethodRef relationship

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

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.

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.

validFor A time period. Validity period of the related party.

Json representation sample

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

© TM Forum 2017. All Rights Reserved. Page 17

Account Management API REST Specification

{
"creditLimit": "10000",
"description": "This party account ...",
"href": "[Link]
"id": "6698",
"lastModified": "2017-05-03T00:00",
"name": "Administration account",
"state": "Active",
"type": "Business",
"paymentStatus": "Due",
"billStructure": {
"presentationMedia": [
{
"href": "[Link]
"id": "5499",
"name": "Email"
}
],
"format": {
"href": "[Link]
"id": "9847",
"name": "Summary invoice"
},
"cycleSpecification": {
"dateShift": 43,
"frequency": "monthly",
"href": "[Link]
"id": "4706",
"name": "Monthly billing"
}
},
"paymentPlan": [
{
"numberOfPayments": 10,
"paymentFrequency": "monthly",
"priority": 2,
"status": "Effective",
"totalAmount": 543.8,
"type": "regular",
"validFor": {
"startDateTime": "2017-05-01T00:00",
"endDateTime": "2017-11-29T00:00"
},
"paymentMethod": {
"href": "[Link]
"id": "2942",
"name": "family payment"
}
}
],
"financialAccount": {
"href": "[Link]
"id": "5860",
"name": "Partnership account",
"accountBalance": {
"amount": 55.79,

© TM Forum 2017. All Rights Reserved. Page 18

Account Management API REST Specification

"type": "DepositBalance",
"validFor": {
"startDateTime": "2017-05-06T00:00",
"endDateTime": "2017-11-29T00:00"
}
}
},
"defaultPaymentMethod": {
"href": "[Link]
"id": "8509",
"name": "professional payment"
},
"relatedParty": [
{
"href": "[Link]
"id": "9653",
"name": "John Doe",
"role": "seller",
"validFor": {
"startDateTime": "2017-05-05T00:00",
"endDateTime": "2017-11-29T00:00"
}
}
],
"taxExemption": [
{
"certificateNumber": "45678909876",
"issuingJurisdiction": "Embassy",
"reason": "VIP",
"validFor": {
"startDateTime": "2017-04-29T00:00",
"endDateTime": "2017-11-29T00:00"
}
}
],
"contact": [
{
"contactName": "Anna Cristal",
"contactType": "primary",
"partyRoleType": "Publisher",
"validFor": {
"startDateTime": "2017-05-02T00:00",
"endDateTime": "2017-11-29T00:00"
},
"contactMedium": [
{
"preferred": true,
"type": "TelephoneNumber",
"validFor": {
"startDateTime": "2017-05-01T00:00",
"endDateTime": "2017-11-29T00:00"
},
"characteristic": [
{
"name": "Colour",
"value": "pink"

© TM Forum 2017. All Rights Reserved. Page 19

Account Management API REST Specification

},
{
"name": "Memory",
"value": "64"
}
]
}
],
"relatedParty": {
"href": "[Link]
"id": "5755",
"name": "Richard Cole",
"role": "bill responsible",
"validFor": {
"startDateTime": "2017-05-04T00:00",
"endDateTime": "2017-11-29T00:00"
}
}
}
],
"accountBalance": [
{
"amount": 53.41,
"type": "DepositBalance",
"validFor": {
"startDateTime": "2017-05-05T00:00",
"endDateTime": "2017-11-29T00:00"
}
}
],
"accountRelationship": [
{
"relationshipType": "contains",
"validFor": {
"startDateTime": "2017-05-04T00:00",
"endDateTime": "2017-11-29T00:00"
},
"account": {
"description": "This account ...",
"href": "[Link]
"id": "2126",
"name": "Travel Account"
}
}
]
}

BILLING ACCOUNT RESOURCE

A party account used for billing purposes. It includes a description of the bill structure (frequency,
presentation media, format and so on).

Resource model

© TM Forum 2017. All Rights Reserved. Page 20

Account Management API REST Specification

Lifecycle

The Billing Account lifecycle is tracked by the 'state' attribute. Typical lifecycle values are: Defined, Active,
Suspended, pending Update, pending Closed, Closed.
Note that an implementation of the specification may enrich the list of states depicted in the diagram. The
state machine specifying the typical state change transitions is provided below.

Field descriptions

BillingAccount fields

creditLimit A money (Money). The maximum amount of money that may be charged on
an account.

© TM Forum 2017. All Rights Reserved. Page 21

Account Management API REST Specification

description A string. Detailed description of the party account.

href A string. Unique reference of the account.

id A string. Unique identifier of the account.

lastModified A date time (DateTime). Date of last modification of the account.

name A string. Name of the account.

state A string. Contains the lifecycle state such as: Active, Closed, Suspended and
so on.

type A string. A categorization of an account, such as individual, joint, and so forth,

whose instances share some of the same characteristics. Note: for flexibility
we use a String here but an implementation may use an enumeration with a
limited list of valid values.

billStructure A bill structure (BillStructure). The structure of the bill for party accounts
(billling or settlement).

paymentPlan A list of payment plans (PaymentPlan [*]). Defines a plan for payment (when a
party wants to spread his payments).

financialAccount A financial account reference (FinancialAccountRef). AccountReceivable

reference. An account of money owed by a party to another entity in exchange
for goods or services that have been delivered or used. An account receivable
aggregates the amounts of one or more party accounts (billing or settlement)
owned by a given party.

defaultPaymentMethod A payment method reference (PaymentMethodRef). A payment method

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

relatedParty A list of related party references (RelatedPartyRef [*]). A related party defines
party or party role linked to a specific entity.

taxExemption A list of account tax exemptions (AccountTaxExemption [*]). Proof of freedom

from taxes imposed by a taxing jurisdiction.

contact A list of contacts (Contact [*]). An individual or an organization used as a

contact point for a given account and accessed via some contact medium.

accountBalance A list of account balances (AccountBalance [*]). Balances linked to the

account.

accountRelationship A list of account relationships (AccountRelationship [*]). Significant connection

between accounts. For instance an aggregating account for a list of shop
branches each having its own billing account.

AccountBalance sub-resource

Balances linked to the account.

© TM Forum 2017. All Rights Reserved. Page 22

Account Management API REST Specification

amount A money (Money). Balance amount.

type A string. Type of the balance : deposit balance, disputed balance, loyalty
balance, receivable balance...

validFor A time period. Balance validity period.

AccountRelationship sub-resource

Significant connection between accounts. For instance an aggregating account for a list of shop branches
each having its own billing account.

relationshipType A string. Type of relationship.

validFor A time period. Validity period of that relationship.

account An account reference (AccountRef). A account may be a party account or a

financial account.

AccountTaxExemption sub-resource

Proof of freedom from taxes imposed by a taxing jurisdiction.

certificateNumber A string. Identifier of a document that shows proof of exemption from taxes for
the taxing jurisdiction.

issuingJurisdiction A string. Name of the taxing jurisdiction for which taxes are exempt.

reason A string. Reason of the tax exemption.

validFor A time period. Period for which the exemption is valid.

BillStructure sub-resource

The structure of the bill for party accounts (billling or settlement).

presentationMedia A list of bill presentation media references (BillPresentationMediaRef [*]).

PresentationMedia reference. A mean of communicating a bill, supported by
the associated bill format. For example, post mail, email, web page.

format A bill format reference (BillFormatRef). A bill format is a description of the way
in which a bill is presented.

cycleSpecification A billing cycle specification reference (BillingCycleSpecificationRef). A

description of when to initiate a billing cycle and the various sub steps of a
billing cycle.

Contact sub-resource

An individual or an organization used as a contact point for a given account and accessed via some
contact medium.

contactName A string. A displayable name for that contact.

© TM Forum 2017. All Rights Reserved. Page 23

Account Management API REST Specification

contactType A string. Type of contact (primary, secondary...).

partyRoleType A string. Identifies what kind of party role type is linked to the contact (a
account manager...).

validFor A time period. Validity period of that contact.

contactMedium A list of contact mediums (ContactMedium [*]). Indicates the contact medium
that could be used to contact the party.

relatedParty A related party reference (RelatedPartyRef). A related party defines party or

party role linked to a specific entity.

ContactMedium sub-resource

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

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).

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.

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

Money sub-resource

© TM Forum 2017. All Rights Reserved. Page 24

Account Management API REST Specification

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 positive floating point number.

PaymentPlan sub-resource

Defines a plan for payment (when a party wants to spread his payments).

numberOfPayments An integer. Number of payments used to spread the global payment.

paymentFrequency A string. Frequency of the payments, such as monthly and bimonthly.

priority An integer. Priority of the payment plan.

status A string. Status of the payment plan (effective, ineffective).

totalAmount A money (Money). Amount paid.

type A string. Type of payment plan.

validFor A time period. Validity period of the payment plan.

paymentMethod A payment method reference (PaymentMethodRef). A payment method

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

AccountRef relationship

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

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.

BillFormatRef relationship

BillFormat reference. A bill format is a description of the way in which a bill is presented.

href A string. Reference of the bill format.

id A string. Unique identifier of the bill format.

name A string. A short descriptive name.

BillPresentationMediaRef relationship

PresentationMedia reference. A mean of communicating a bill, supported by the associated bill format. For
example, post mail, email, web page.

© TM Forum 2017. All Rights Reserved. Page 25

Account Management API REST Specification

href A string. Reference of the bill presentation media.

id A string. Unique identifier of the bill presentation media.

name A string. A short descriptive name.

BillingCycleSpecificationRef relationship

BillingCycleSpecification reference. A description of when to initiate a billing cycle and the various sub
steps of a billing cycle.

dateShift An integer. An offset of a billing/settlement date. The offset is expressed as

number of days with regard to the start of the billing/settlement period.

frequency A string. Frequency of the billing cycle (monthly for instance).

href A string. Reference of the billing cycle specification.

id A string. Unique identifier of the billing cycle specification.

name A string. A short descriptive name.

FinancialAccountRef relationship

AccountReceivable reference. An account of money owed by a party to another entity in exchange for
goods or services that have been delivered or used. An account receivable aggregates the amounts of
one or more party accounts (billing or settlement) owned by a given party.

href A string. Unique reference of the account.

id A string. Unique identifier of the account.

name A string. Name of the account.

accountBalance An account balance (AccountBalance). Balances linked to the account.

PaymentMethodRef relationship

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

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.

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

© TM Forum 2017. All Rights Reserved. Page 26

Account Management API REST Specification

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.

validFor A time period. Validity period of the related party.

Json representation sample

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

{
"paymentStatus": "Due",
"creditLimit": "a Money ...",
"description": "This billing account ...",
"href": "[Link]
"id": "4835",
"lastModified": "2017-05-03T00:00",
"name": "Home Account",
"state": "Active",
"type": "Business",
"billStructure": {
"presentationMedia": [
{
"href": "[Link]
"id": "7176",
"name": "Paper"
}
],
"format": {
"href": "[Link]
"id": "5195",
"name": "Summary invoice"
},
"cycleSpecification": {
"dateShift": 75,
"frequency": "monthly",
"href": "[Link]
"id": "1266",
"name": "Annual billing"
}
},
"paymentPlan": [
{
"numberOfPayments": 4,
"paymentFrequency": "monthly",
"priority": 4,
"status": "Effective",
"totalAmount": 543.8,
"type": "special",
"validFor": {
"startDateTime": "2017-05-06T00:00",
"endDateTime": "2017-11-29T00:00"
},
"paymentMethod": {

© TM Forum 2017. All Rights Reserved. Page 27

Account Management API REST Specification

"href": "[Link]
"id": "8829",
"name": "family payment"
}
}
],
"financialAccount": {
"href": "[Link]
"id": "1163",
"name": "Partnership account",
"accountBalance": {
"amount": 57.68,
"type": "DepositBalance",
"validFor": {
"startDateTime": "2017-05-03T00:00",
"endDateTime": "2017-11-29T00:00"
}
}
},
"defaultPaymentMethod": {
"href": "[Link]
"id": "8092",
"name": "family payment"
},
"relatedParty": [
{
"href": "[Link]
"id": "3332",
"name": "John Doe",
"role": "user",
"validFor": {
"startDateTime": "2017-04-30T00:00",
"endDateTime": "2017-11-29T00:00"
}
}
],
"taxExemption": [
{
"certificateNumber": "98765432345",
"issuingJurisdiction": "Prefecture",
"reason": "VIP",
"validFor": {
"startDateTime": "2017-05-06T00:00",
"endDateTime": "2017-11-29T00:00"
}
}
],
"contact": [
{
"contactName": "Charles Chopin",
"contactType": "secondary",
"partyRoleType": "Publisher",
"validFor": {
"startDateTime": "2017-05-02T00:00",
"endDateTime": "2017-11-29T00:00"
},

© TM Forum 2017. All Rights Reserved. Page 28

Account Management API REST Specification

"contactMedium": [
{
"preferred": true,
"type": "Email",
"validFor": {
"startDateTime": "2017-05-06T00:00",
"endDateTime": "2017-11-29T00:00"
},
"characteristic": [
{
"name": "Colour",
"value": "white"
},
{
"name": "Memory",
"value": "64"
}
]
}
],
"relatedParty": {
"href": "[Link]
"id": "3665",
"name": "Richard Cole",
"role": "customer",
"validFor": {
"startDateTime": "2017-05-06T00:00",
"endDateTime": "2017-11-29T00:00"
}
}
}
],
"accountBalance": [
{
"amount": 54.88,
"type": "ReceivableBalance",
"validFor": {
"startDateTime": "2017-05-01T00:00",
"endDateTime": "2017-11-29T00:00"
}
}
],
"accountRelationship": [
{
"relationshipType": "contains",
"validFor": {
"startDateTime": "2017-05-04T00:00",
"endDateTime": "2017-11-29T00:00"
},
"account": {
"description": "This account ...",
"href": "[Link]
"id": "4807",
"name": "Paradise Account"
}
}

© TM Forum 2017. All Rights Reserved. Page 29

Account Management API REST Specification

]
}

SETTLEMENT ACCOUNT RESOURCE

A party account used for settlement purposes. It includes a description of the structure used for the
settlement (frequency, presentation media, format and so on).

Resource model

Lifecycle

The Settlement Account lifecycle is tracked by the 'state' attribute. Typical lifecycle values are: Defined,
Active, Suspended, pending Update, pending Closed, Closed.
Note that an implementation of the specification may enrich the list of states depicted in the diagram. The
state machine specifying the typical state change transitions is provided below.

© TM Forum 2017. All Rights Reserved. Page 30

Account Management API REST Specification

Field descriptions

SettlementAccount fields

creditLimit A money (Money). The maximum amount of money that may be charged on
an account.

description A string. Detailed description of the party account.

href A string. Unique reference of the account.

id A string. Unique identifier of the account.

lastModified A date time (DateTime). Date of last modification of the account.

name A string. Name of the account.

state A string. Contains the lifecycle state such as: Active, Closed, Suspended and
so on.

type A string. A categorization of an account, such as individual, joint, and so forth,

whose instances share some of the same characteristics. Note: for flexibility
we use a String here but an implementation may use an enumeration with a
limited list of valid values.

© TM Forum 2017. All Rights Reserved. Page 31

Account Management API REST Specification

billStructure A bill structure (BillStructure). The structure of the bill for party accounts
(billling or settlement).

paymentPlan A list of payment plans (PaymentPlan [*]). Defines a plan for payment (when a
party wants to spread his payments).

financialAccount A financial account reference (FinancialAccountRef). AccountReceivable

reference. An account of money owed by a party to another entity in exchange
for goods or services that have been delivered or used. An account receivable
aggregates the amounts of one or more party accounts (billing or settlement)
owned by a given party.

defaultPaymentMethod A payment method reference (PaymentMethodRef). A payment method

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

relatedParty A list of related party references (RelatedPartyRef [*]). A related party defines
party or party role linked to a specific entity.

taxExemption A list of account tax exemptions (AccountTaxExemption [*]). Proof of freedom

from taxes imposed by a taxing jurisdiction.

contact A list of contacts (Contact [*]). An individual or an organization used as a

contact point for a given account and accessed via some contact medium.

accountBalance A list of account balances (AccountBalance [*]). Balances linked to the

account.

accountRelationship A list of account relationships (AccountRelationship [*]). Significant connection

between accounts. For instance an aggregating account for a list of shop
branches each having its own billing account.

AccountBalance sub-resource

Balances linked to the account.

amount A money (Money). Balance amount.

type A string. Type of the balance : deposit balance, disputed balance, loyalty
balance, receivable balance...

validFor A time period. Balance validity period.

AccountRelationship sub-resource

Significant connection between accounts. For instance an aggregating account for a list of shop branches
each having its own billing account.

relationshipType A string. Type of relationship.

validFor A time period. Validity period of that relationship.

© TM Forum 2017. All Rights Reserved. Page 32

Account Management API REST Specification

account An account reference (AccountRef). An account may be a party account or a

financial account.

AccountTaxExemption sub-resource

Proof of freedom from taxes imposed by a taxing jurisdiction.

certificateNumber A string. Identifier of a document that shows proof of exemption from taxes for
the taxing jurisdiction.

issuingJurisdiction A string. Name of the taxing jurisdiction for which taxes are exempt.

reason A string. Reason of the tax exemption.

validFor A time period. Period for which the exemption is valid.

BillStructure sub-resource

The structure of the bill for party accounts (billling or settlement).

presentationMedia A list of bill presentation media references (BillPresentationMediaRef [*]).

PresentationMedia reference. A mean of communicating a bill, supported by
the associated bill format. For example, post mail, email, web page.

format A bill format reference (BillFormatRef). A bill format is a description of the way
in which a bill is presented.

cycleSpecification A billing cycle specification reference (BillingCycleSpecificationRef). A

description of when to initiate a billing cycle and the various sub steps of a
billing cycle.

Contact sub-resource

An individual or an organization used as a contact point for a given account and accessed via some
contact medium.

contactName A string. A displayable name for that contact.

contactType A string. Type of contact (primary, secondary...).

partyRoleType A string. Identifies what kind of party role type is linked to the contact (a
account manager...).

validFor A time period. Validity period of that contact.

contactMedium A list of contact mediums (ContactMedium [*]). Indicates the contact medium
that could be used to contact the party.

relatedParty A related party reference (RelatedPartyRef). A related party defines party or

party role linked to a specific entity.

ContactMedium sub-resource

© TM Forum 2017. All Rights Reserved. Page 33

Account Management API REST Specification

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

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).

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.

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

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 positive floating point number.

PaymentPlan sub-resource

Defines a plan for payment (when a party wants to spread his payments).

numberOfPayments An integer. Number of payments used to spread the global payment.

paymentFrequency A string. Frequency of the payments, such as monthly and bimonthly.

© TM Forum 2017. All Rights Reserved. Page 34

Account Management API REST Specification

priority An integer. Priority of the payment plan.

status A string. Status of the payment plan (effective, ineffective).

totalAmount A money (Money). Amount paid.

type A string. Type of payment plan.

validFor A time period. Validity period of the payment plan.

paymentMethod A payment method reference (PaymentMethodRef). A payment method

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

AccountRef relationship

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

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.

BillFormatRef relationship

BillFormat reference. A bill format is a description of the way in which a bill is presented.

href A string. Reference of the bill format.

id A string. Unique identifier of the bill format.

name A string. A short descriptive name.

BillPresentationMediaRef relationship

PresentationMedia reference. A mean of communicating a bill, supported by the associated bill format. For
example, post mail, email, web page.

href A string. Reference of the bill presentation media.

id A string. Unique identifier of the bill presentation media.

name A string. A short descriptive name.

BillingCycleSpecificationRef relationship

BillingCycleSpecification reference. A description of when to initiate a billing cycle and the various sub
steps of a billing cycle.

dateShift An integer. An offset of a billing/settlement date. The offset is expressed as

number of days with regard to the start of the billing/settlement period.

© TM Forum 2017. All Rights Reserved. Page 35

Account Management API REST Specification

frequency A string. Frequency of the billing cycle (monthly for instance).

href A string. Reference of the billing cycle specification.

id A string. Unique identifier of the billing cycle specification.

name A string. A short descriptive name.

FinancialAccountRef relationship

AccountReceivable reference. An account of money owed by a party to another entity in exchange for
goods or services that have been delivered or used. An account receivable aggregates the amounts of
one or more party accounts (billing or settlement) owned by a given party.

href A string. Unique reference of the account.

id A string. Unique identifier of the account.

name A string. Name of the account.

accountBalance An account balance (AccountBalance). Balances linked to the account.

PaymentMethodRef relationship

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

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.

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.

validFor A time period. Validity period of the related party.

Json representation sample

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

{
"paymentStatus": "Due",
"creditLimit": "a Money ...",
"description": "This settlement account ...",

© TM Forum 2017. All Rights Reserved. Page 36

Account Management API REST Specification

"href": "[Link]
"id": "6202",
"lastModified": "2017-05-03T00:00",
"name": "Per Usage Account",
"state": "active",
"type": "Business",
"billStructure": {
"presentationMedia": [
{
"href": "[Link]
"id": "7422",
"name": "Paper"
}
],
"format": {
"href": "[Link]
"id": "3588",
"name": "Detailed invoice"
},
"cycleSpecification": {
"dateShift": 20,
"frequency": "monthly",
"href": "[Link]
"id": "5190",
"name": "Annual billing"
}
},
"paymentPlan": [
{
"numberOfPayments": 4,
"paymentFrequency": "bimonthly",
"priority": 4,
"status": "Effective",
"totalAmount": 543.8,
"type": "regular",
"validFor": {
"startDateTime": "2017-05-04T00:00",
"endDateTime": "2017-11-29T00:00"
},
"paymentMethod": {
"href": "[Link]
"id": "1547",
"name": "family payment"
}
}
],
"financialAccount": {
"href": "[Link]
"id": "4503",
"name": "Travel account",
"accountBalance": {
"amount": 55.91,
"type": "ReceivableBalance",
"validFor": {
"startDateTime": "2017-04-30T00:00",
"endDateTime": "2017-11-29T00:00"

© TM Forum 2017. All Rights Reserved. Page 37

Account Management API REST Specification

}
}
},
"defaultPaymentMethod": {
"href": "[Link]
"id": "3135",
"name": "family payment"
},
"relatedParty": [
{
"href": "[Link]
"id": "2981",
"name": "Gustave Flaubert",
"role": "owner",
"validFor": {
"startDateTime": "2017-05-06T00:00",
"endDateTime": "2017-11-29T00:00"
}
}
],
"taxExemption": [
{
"certificateNumber": "45678909876",
"issuingJurisdiction": "Embassy",
"reason": "VIP",
"validFor": {
"startDateTime": "2017-05-06T00:00",
"endDateTime": "2017-11-29T00:00"
}
}
],
"contact": [
{
"contactName": "Ludwig Borgia",
"contactType": "secondary",
"partyRoleType": "CustomerAccountRepresentative",
"validFor": {
"startDateTime": "2017-04-30T00:00",
"endDateTime": "2017-11-29T00:00"
},
"contactMedium": [
{
"preferred": true,
"type": "TelephoneNumber",
"validFor": {
"startDateTime": "2017-05-06T00:00",
"endDateTime": "2017-11-29T00:00"
},
"characteristic": [
{
"name": "Colour",
"value": "blue"
},
{
"name": "Memory",
"value": "64"

© TM Forum 2017. All Rights Reserved. Page 38

Account Management API REST Specification

}
]
}
],
"relatedParty": {
"href": "[Link]
"id": "4985",
"name": "Gustave Flaubert",
"role": "vendor",
"validFor": {
"startDateTime": "2017-05-06T00:00",
"endDateTime": "2017-11-29T00:00"
}
}
}
],
"accountBalance": [
{
"amount": 51.77,
"type": "DepositBalance",
"validFor": {
"startDateTime": "2017-04-29T00:00",
"endDateTime": "2017-11-29T00:00"
}
}
],
"accountRelationship": [
{
"relationshipType": "linked",
"validFor": {
"startDateTime": "2017-05-04T00:00",
"endDateTime": "2017-11-29T00:00"
},
"account": {
"description": "This account ...",
"href": "[Link]
"id": "2553",
"name": "Paradise Account"
}
}
]
}

FINANCIAL ACCOUNT RESOURCE

An account of money owed by a party to another entity in exchange for goods or services that have been
delivered or used. A financial (account receivable account/account payable) aggregates the amounts of
one or more party accounts (billing or settlement) owned by a given party.

Resource model

© TM Forum 2017. All Rights Reserved. Page 39

Account Management API REST Specification

Lifecycle

The FinancialAccount lifecycle is tracked by the 'state' attribute. Typical lifecycle values are: Defined,
Active, Suspended, pending Update, pending Closed, Closed.
Note that an implementation of the specification may enrich the list of states depicted in the diagram. The
state machine specifying the typical state change transitions is provided below.

© TM Forum 2017. All Rights Reserved. Page 40

Account Management API REST Specification

Field descriptions

FinancialAccount fields

creditLimit A money (Money). The maximum amount of money that may be charged on an
account.

description A string. Detailed description of the party account.

href A string. Unique reference of the account.

id A string. Unique identifier of the account.

lastModified A date time (DateTime). Date of last modification of the account.

name A string. Name of the account.

state A string. Contains the lifecycle state such as: Active, Closed, Suspended and
so on.

type A string. A categorization of an account, such as individual, joint, and so forth,

whose instances share some of the same characteristics. Note: for flexibility we
use a String here but an implementation may use an enumeration with a limited
list of valid values.

© TM Forum 2017. All Rights Reserved. Page 41

Account Management API REST Specification

relatedParty A list of related party references (RelatedPartyRef [*]). A related party defines
party or party role linked to a specific entity.

taxExemption A list of account tax exemptions (AccountTaxExemption [*]). Proof of freedom

from taxes imposed by a taxing jurisdiction.

contact A list of contacts (Contact [*]). An individual or an organization used as a

contact point for a given account and accessed via some contact medium.

accountBalance A list of account balances (AccountBalance [*]). Balances linked to the

account.

accountRelationship A list of account relationships (AccountRelationship [*]). Significant connection

between accounts. For instance an aggregating account for a list of shop
branches each having its own billing account.

AccountBalance sub-resource

Balances linked to the account.

amount A money (Money). Balance amount.

type A string. Type of the balance : deposit balance, disputed balance, loyalty
balance, receivable balance...

validFor A time period. Balance validity period.

AccountRelationship sub-resource

Significant connection between accounts. For instance an aggregating account for a list of shop branches
each having its own billing account.

relationshipType A string. Type of relationship.

validFor A time period. Validity period of that relationship.

account An account reference (AccountRef). An account may be a party account or a

financial account.

AccountTaxExemption sub-resource

Proof of freedom from taxes imposed by a taxing jurisdiction.

certificateNumber A string. Identifier of a document that shows proof of exemption from taxes for
the taxing jurisdiction.

issuingJurisdiction A string. Name of the taxing jurisdiction for which taxes are exempt.

reason A string. Reason of the tax exemption.

validFor A time period. Period for which the exemption is valid.

Contact sub-resource

© TM Forum 2017. All Rights Reserved. Page 42

Account Management API REST Specification

An individual or an organization used as a contact point for a given account and accessed via some
contact medium.

contactName A string. A displayable name for that contact.

contactType A string. Type of contact (primary, secondary...).

partyRoleType A string. Identifies what kind of party role type is linked to the contact (a
account manager...).

validFor A time period. Validity period of that contact.

contactMedium A list of contact mediums (ContactMedium [*]). Indicates the contact medium
that could be used to contact the party.

relatedParty A related party reference (RelatedPartyRef). A related party defines party or

party role linked to a specific entity.

ContactMedium sub-resource

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

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).

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.

© TM Forum 2017. All Rights Reserved. Page 43

Account Management API REST Specification

street2 A string. Complementary street description.

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

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 positive floating point number.

AccountRef relationship

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

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.

RelatedPartyRef relationship

RelatedParty reference. A related party defines party or party role linked to a specific 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.

validFor A time period. Validity period of the related party.

Json representation sample

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

{
"creditLimit": "a Money ...",
"description": "This financial account ...",
"href": "[Link]
"id": "4055",
"lastModified": "2017-05-03T00:00",
"name": "Travel account",
"state": "Active",
"type": "Global",
"relatedParty": [
{
"href": "[Link]

© TM Forum 2017. All Rights Reserved. Page 44

Account Management API REST Specification

"id": "2110",
"name": "John Doe",
"role": "owner",
"validFor": {
"startDateTime": "2017-05-01T00:00",
"endDateTime": "2017-11-29T00:00"
}
}
],
"taxExemption": [
{
"certificateNumber": "45678909876",
"issuingJurisdiction": "Prefecture",
"reason": "VIP",
"validFor": {
"startDateTime": "2017-05-06T00:00",
"endDateTime": "2017-11-29T00:00"
}
}
],
"contact": [
{
"contactName": "Rachel Douglas",
"contactType": "secondary",
"partyRoleType": "CustomerAccountRepresentative",
"validFor": {
"startDateTime": "2017-04-29T00:00",
"endDateTime": "2017-11-29T00:00"
},
"contactMedium": [
{
"preferred": true,
"type": "PostalAddress",
"validFor": {
"startDateTime": "2017-05-03T00:00",
"endDateTime": "2017-11-29T00:00"
},
"characteristic": [
{
"name": "Colour",
"value": "pink"
},
{
"name": "Memory",
"value": "32"
}
]
}
],
"relatedParty": {
"href": "[Link]
"id": "8202",
"name": "John Doe",
"role": "bill receiver",
"validFor": {
"startDateTime": "2017-04-30T00:00",

© TM Forum 2017. All Rights Reserved. Page 45

Account Management API REST Specification

"endDateTime": "2017-11-29T00:00"
}
}
}
],
"accountBalance": [
{
"amount": 58.7,
"type": "DepositBalance",
"validFor": {
"startDateTime": "2017-05-02T00:00",
"endDateTime": "2017-11-29T00:00"
}
}
],
"accountRelationship": [
{
"relationshipType": "linked",
"validFor": {
"startDateTime": "2017-04-29T00:00",
"endDateTime": "2017-11-29T00:00"
},
"account": {
"description": "This account ...",
"href": "[Link]
"id": "9531",
"name": "Paradise Account"
}
}
]
}

BILLING CYCLE SPECIFICATION RESOURCE

A detailed description of when to initiate a billing cycle and the various sub steps of a billing cycle.

Resource model

© TM Forum 2017. All Rights Reserved. Page 46

Account Management API REST Specification

Field descriptions

BillingCycleSpecification fields

billingDateShift An integer. An offset of a billing/settlement date. The offset is expressed as

number of days with regard to the start of the billing/settlement period.

billingPeriod A string. A billing time period. It can be recurring, for example: week, month,
quarter of year, year.

chargeDateOffset An int (int). An offset of a date through which charges previously received by
the billing system will appear on the bill. The offset is expressed as number of
days with regard to the start of the BillingPeriod.

creditDateOffset An int (int). An offset of a date through which credits previously received by
the billing system will appear on the bill. The offset is expressed as number of
days with regard to the start of the BillingPeriod.

description A string. An explanation regarding this billing cycle specification.

frequency A string. Frequency of the billing cycle (monthly for instance).

href A string. Reference of the billing cycle specification.

id A string. Unique identifier of the billing cycle specification.

mailingDateOffset An integer. An offset of a customer bill mailing date. The offset is expressed
as number of days with regard to the start of the BillingPeriod.

name A string. A short descriptive name.

paymentDueDateOffset An integer. An offset of a payment due date. The offset is expressed as

number of days with regard to the start of the BillingPeriod.

validFor A time period. The period for which the billing specification cycle is valid.

Json representation sample

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

{
"billingDateShift": 20,
"billingPeriod": "a string ...",
"chargeDateOffset": "a int ...",
"creditDateOffset": "a int ...",
"description": "This billing cycle specification ...",
"frequency": "monthly",
"href": "[Link]
"id": "3353",
"mailingDateOffset": 53,
"name": "Monthly billing on the 15",
"paymentDueDateOffset": 45,
"validFor": {
"startDateTime": "2017-05-06T00:00",

© TM Forum 2017. All Rights Reserved. Page 47

Account Management API REST Specification

"endDateTime": "2017-11-29T00:00"
}
}

BILL FORMAT RESOURCE

A detailed description of the way in which a bill is presented.

Resource model

Field descriptions

BillFormat fields

description A string. An explanatory text for this bill format.

href A string. Reference of the bill format.

id A string. Unique identifier of the bill format.

name A string. A short descriptive name.

Json representation sample

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

{
"description": "This bill format ...",
"href": "[Link]
"id": "4962",
"name": "Summary invoice"
}

BILL PRESENTATION MEDIA RESOURCE

A mean of communicating a bill, supported by the associated bill format. For example, post mail, email,
web page.

Resource model

© TM Forum 2017. All Rights Reserved. Page 48

Account Management API REST Specification

Field descriptions

BillPresentationMedia fields

description A string. An explanatory text describing this bill presentation media.

href A string. Reference of the bill presentation media.

id A string. Unique identifier of the bill presentation media.

name A string. A short descriptive name.

Json representation sample

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

{
"description": "This bill presentation media ...",
"href": "[Link]
"id": "5458",
"name": "Email"
}

Notification Resource Models

10 notifications are defined for this API

Notifications related to PartyAccount:

- PartyAccountAttributeValueChangeNotification
- PartyAccountStateChangeNotification

Notifications related to BillingAccount:

- BillingAccountAttributeValueChangeNotification
- BillingAccountStateChangeNotification

Notifications related to SettlementAccount:

- SettlementAccountAttributeValueChangeNotification
- SettlementAccountStateChangeNotification

Notifications related to FinancialAccount:

- FinancialAccountCreationNotification

© TM Forum 2017. All Rights Reserved. Page 49

Account Management API REST Specification

- FinancialAccountAttributeValueChangeNotification
- FinancialAccountStateChangeNotification
- FinancialAccountRemoveNotification

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 occurence (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).

PARTY ACCOUNT ATTRIBUTE VALUE CHANGE NOTIFICATION

Notification sent when changing an attribute of a PartyAccount resource.

Json representation sample

We provide below the json representation of an example of a

'PartyAccountAttributeValueChangeNotification' notification object

© TM Forum 2017. All Rights Reserved. Page 50

Account Management API REST Specification

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"PartyAccountAttributeValueChangeNotification",
"event": {
"partyAccount" :
{-- SEE PartyAccount RESOURCE SAMPLE --}
}
}

PARTY ACCOUNT STATE CHANGE NOTIFICATION

Notification sent when changing the state of a PartyAccount resource.

Json representation sample

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

notification object

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"PartyAccountStateChangeNotification",
"event": {
"partyAccount" :
{-- SEE PartyAccount RESOURCE SAMPLE --}
}
}

BILLING ACCOUNT ATTRIBUTE VALUE CHANGE NOTIFICATION

Notification sent when changing an attribute of a BillingAccount resource.

Json representation sample

We provide below the json representation of an example of a

'BillingAccountAttributeValueChangeNotification' notification object

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"BillingAccountAttributeValueChangeNotification",
"event": {
"billingAccount" :
{-- SEE BillingAccount RESOURCE SAMPLE --}
}
}

BILLING ACCOUNT STATE CHANGE NOTIFICATION

© TM Forum 2017. All Rights Reserved. Page 51

Account Management API REST Specification

Notification sent when changing the state of a BillingAccount resource.

Json representation sample

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

notification object

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"BillingAccountStateChangeNotification",
"event": {
"billingAccount" :
{-- SEE BillingAccount RESOURCE SAMPLE --}
}
}

SETTLEMENT ACCOUNT ATTRIBUTE VALUE CHANGE NOTIFICATION

Notification sent when changing an attribute of a SettlementAccount resource.

Json representation sample

We provide below the json representation of an example of a

'SettlementAccountAttributeValueChangeNotification' notification object

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"SettlementAccountAttributeValueChangeNotification",
"event": {
"settlementAccount" :
{-- SEE SettlementAccount RESOURCE SAMPLE --}
}
}

SETTLEMENT ACCOUNT STATE CHANGE NOTIFICATION

Notification sent when changing the state of a SettlementAccount resource.

Json representation sample

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

notification object.

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"SettlementAccountStateChangeNotification",
"event": {
"settlementAccount" :
{-- SEE SettlementAccount RESOURCE SAMPLE --}

© TM Forum 2017. All Rights Reserved. Page 52

Account Management API REST Specification

}
}

FINANCIAL ACCOUNT CREATION NOTIFICATION

Notification sent when a new FinancialAccount resource is created.

Json representation sample

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

notification object.

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"FinancialAccountCreationNotification",
"event": {
"financialAccount" :
{-- SEE FinancialAccount RESOURCE SAMPLE --}
}
}

FINANCIAL ACCOUNT ATTRIBUTE VALUE CHANGE NOTIFICATION

Notification sent when changing an attribute of a FinancialAccount resource.

Json representation sample

We provide below the json representation of an example of a

'FinancialAccountAttributeValueChangeNotification' notification object

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"FinancialAccountAttributeValueChangeNotification",
"event": {
"financialAccount" :
{-- SEE FinancialAccount RESOURCE SAMPLE --}
}
}

FINANCIAL ACCOUNT STATE CHANGE NOTIFICATION

Notification sent when changing the state of a FinancialAccount resource.

Json representation sample

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

notification object.

© TM Forum 2017. All Rights Reserved. Page 53

Account Management API REST Specification

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"FinancialAccountStateChangeNotification",
"event": {
"financialAccount" :
{-- SEE FinancialAccount RESOURCE SAMPLE --}
}
}

FINANCIAL ACCOUNT REMOVE NOTIFICATION

Notification sent when removing a FinancialAccount resource.

Json representation sample

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

notification object.

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"FinancialAccountRemoveNotification",
"event": {
"financialAccount" :
{-- SEE FinancialAccount RESOURCE SAMPLE --}
}
}

© TM Forum 2017. All Rights Reserved. Page 54

Account 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 PARTY ACCOUNT

LIST PARTY ACCOUNTS

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

© TM Forum 2017. All Rights Reserved. Page 55

Account Management API REST Specification

Description

This operation list party account 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 PartyAccount resources.

Retrieving all party accounts of type 'Business' with 'due' status. The result items are shrunk to show only
the id, name and the credit limit (fields=id,name,creditLimit)

Request

GET /accountManagement/partyAccount?fields=id,name,creditLimit&status=due
Accept: application/json

Response

200

[
{
"creditLimit": "50000",
"id": "9473",
"name": "Administration Account"
},
{
"creditLimit": "1000000",
"id": "9899",
"name": "Bahamas Account"
}
]

RETRIEVE PARTY ACCOUNT

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

This operation retrieves a party account 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.

© TM Forum 2017. All Rights Reserved. Page 56

Account Management API REST Specification

Usage Samples

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

Request

GET /accountManagement/partyAccount/6698
Accept: application/json

Response

200

{
"creditLimit": "10000",
"description": "This party account ...",
"href": "[Link]
"id": "6698",
"lastModified": "2017-05-03T00:00",
"name": "Administration account",
"state": "Active",
"type": "Business",
"paymentStatus": "Due",
"billStructure": {
"presentationMedia": [
{
"href": "[Link]
"id": "5499",
"name": "Email"
}
],
"format": {
"href": "[Link]
"id": "9847",
"name": "Summary invoice"
},
"cycleSpecification": {
"dateShift": 43,
"frequency": "monthly",
"href": "[Link]
"id": "4706",
"name": "Monthly billing"
}
},
"paymentPlan": [
{
"numberOfPayments": 10,
"paymentFrequency": "monthly",
"priority": 2,
"status": "Effective",
"totalAmount": 543.8,
"type": "regular",

© TM Forum 2017. All Rights Reserved. Page 57

Account Management API REST Specification

"validFor": {
"startDateTime": "2017-05-01T00:00",
"endDateTime": "2017-11-29T00:00"
},
"paymentMethod": {
"href": "[Link]
"id": "2942",
"name": "family payment"
}
}
],
"financialAccount": {
"href": "[Link]
"id": "5860",
"name": "Partnership account",
"accountBalance": {
"amount": 55.79,
"type": "DepositBalance",
"validFor": {
"startDateTime": "2017-05-06T00:00",
"endDateTime": "2017-11-29T00:00"
}
}
},
"defaultPaymentMethod": {
"href": "[Link]
"id": "8509",
"name": "professional payment"
},
"relatedParty": [
{
"href": "[Link]
"id": "9653",
"name": "John Doe",
"role": "seller",
"validFor": {
"startDateTime": "2017-05-05T00:00",
"endDateTime": "2017-11-29T00:00"
}
}
],
"taxExemption": [
{
"certificateNumber": "45678909876",
"issuingJurisdiction": "Embassy",
"reason": "VIP",
"validFor": {
"startDateTime": "2017-04-29T00:00",
"endDateTime": "2017-11-29T00:00"
}
}
],
"contact": [
{
"contactName": "Anna Cristal",
"contactType": "primary",

© TM Forum 2017. All Rights Reserved. Page 58

Account Management API REST Specification

"partyRoleType": "Publisher",
"validFor": {
"startDateTime": "2017-05-02T00:00",
"endDateTime": "2017-11-29T00:00"
},
"contactMedium": [
{
"preferred": true,
"type": "TelephoneNumber",
"validFor": {
"startDateTime": "2017-05-01T00:00",
"endDateTime": "2017-11-29T00:00"
},
"characteristic": [
{
"name": "Colour",
"value": "pink"
},
{
"name": "Memory",
"value": "64"
}
]
}
],
"relatedParty": {
"href": "[Link]
"id": "5755",
"name": "Richard Cole",
"role": "bill responsible",
"validFor": {
"startDateTime": "2017-05-04T00:00",
"endDateTime": "2017-11-29T00:00"
}
}
}
],
"accountBalance": [
{
"amount": 53.41,
"type": "DepositBalance",
"validFor": {
"startDateTime": "2017-05-05T00:00",
"endDateTime": "2017-11-29T00:00"
}
}
],
"accountRelationship": [
{
"relationshipType": "contains",
"validFor": {
"startDateTime": "2017-05-04T00:00",
"endDateTime": "2017-11-29T00:00"
},
"account": {
"description": "This account ...",

© TM Forum 2017. All Rights Reserved. Page 59

Account Management API REST Specification

"href": "[Link]
"id": "2126",
"name": "Travel Account"
}
}
]
}

CREATE PARTY ACCOUNT

POST /partyAccount
Description

This operation creates a party account entity.

Mandatory and Non Mandatory Attributes

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

Non Mandatory Attributes Default Value Rule

creditLimit
description
lastModified
state
type
paymentStatus
billStructure
paymentPlan
financialAccount
defaultPaymentMethod
relatedParty
taxExemption
contact
accountBalance
accountRelationship

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

© TM Forum 2017. All Rights Reserved. Page 60

Account Management API REST Specification

[Link] Current date

[Link] "Bill issuer choice"
[Link] "Standard invoice"
[Link] "Electronic invoice"
currencyCode "National currency"

Usage Samples

Here's an example of a request for creating a PartyAccount resource. In this example the request only
passes mandatory attributes.

Request

POST /accountManagement/partyAccount
Content-Type: application/json

{
"name": "Administration account"
}

Response

201

{
"href": "[Link]
"id": "6698",
"name": "Administration account"
}

PATCH PARTY ACCOUNT

PATCH /partyAccount/{id}
Description

This operation allows partial updates of a party account 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

© TM Forum 2017. All Rights Reserved. Page 61

Account Management API REST Specification

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

Patchable Attributes Rule

creditLimit
description
lastModified
name
state
type
paymentStatus
billStructure
paymentPlan
financialAccount
defaultPaymentMethod
relatedParty
taxExemption
contact
accountRelationship

Non Patchable Attributes Rule

id
href
accountBalance
creditLimit
description
lastModified
name
state
type
paymentStatus
billStructure
paymentPlan
financialAccount
defaultPaymentMethod
relatedParty
taxExemption
contact
accountRelationship

Usage Samples

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

Changing the credit limit and the description of the account (using json-merge)

Request

© TM Forum 2017. All Rights Reserved. Page 62

Account Management API REST Specification

PATCH /accountManagement/partyAccount/42
Content-Type: application/merge-patch+json

{
"description": "Premium credit limit",
"creditLimit": "5000"
}

Response

201

{ Similar JSON as in GET response with credit limit and description changed }

DELETE PARTY ACCOUNT

DELETE /partyAccount/{id}
Note: this operation is available only to ADMIN API users

Description

This operation deletes a party account entity.

Usage Samples

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

Request

DELETE /accountManagement/partyAccount/42

Response

204

OPERATIONS ON BILLING ACCOUNT

LIST BILLING ACCOUNTS

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

© TM Forum 2017. All Rights Reserved. Page 63

Account Management API REST Specification

Description

This operation list billing account 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 BillingAccount resources.

List all billing accounts using Canadian currency. The result items are shrunk to show only the id and
name (fields=id,name)

Request

GET /accountManagement/billingAccount?fields=id,name&currencyCode=CAD
Accept: application/json

Response

200

[
{
"id": "42",
"name": "Lakes Agency Account"
},
{
"id": "43",
"name": "Santa Claus Donate Account"
}
]

RETRIEVE BILLING ACCOUNT

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

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

© TM Forum 2017. All Rights Reserved. Page 64

Account Management API REST Specification

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

Request

GET /accountManagement/billingAccount/4835
Accept: application/json

Response

200

{
"paymentStatus": "Due",
"creditLimit": "a Money ...",
"description": "This billing account ...",
"href": "[Link]
"id": "4835",
"lastModified": "2017-05-03T00:00",
"name": "Home Account",
"state": "Active",
"type": "Business",
"billStructure": {
"presentationMedia": [
{
"href": "[Link]
"id": "7176",
"name": "Paper"
}
],
"format": {
"href": "[Link]
"id": "5195",
"name": "Summary invoice"
},
"cycleSpecification": {
"dateShift": 75,
"frequency": "monthly",
"href": "[Link]
"id": "1266",
"name": "Annual billing"
}
},
"paymentPlan": [
{
"numberOfPayments": 4,
"paymentFrequency": "monthly",
"priority": 4,
"status": "Effective",
"totalAmount": 543.8,
"type": "special",
"validFor": {
"startDateTime": "2017-05-06T00:00",

© TM Forum 2017. All Rights Reserved. Page 65

Account Management API REST Specification

"endDateTime": "2017-11-29T00:00"
},
"paymentMethod": {
"href": "[Link]
"id": "8829",
"name": "family payment"
}
}
],
"financialAccount": {
"href": "[Link]
"id": "1163",
"name": "Partnership account",
"accountBalance": {
"amount": 57.68,
"type": "DepositBalance",
"validFor": {
"startDateTime": "2017-05-03T00:00",
"endDateTime": "2017-11-29T00:00"
}
}
},
"defaultPaymentMethod": {
"href": "[Link]
"id": "8092",
"name": "family payment"
},
"relatedParty": [
{
"href": "[Link]
"id": "3332",
"name": "John Doe",
"role": "user",
"validFor": {
"startDateTime": "2017-04-30T00:00",
"endDateTime": "2017-11-29T00:00"
}
}
],
"taxExemption": [
{
"certificateNumber": "98765432345",
"issuingJurisdiction": "Prefecture",
"reason": "VIP",
"validFor": {
"startDateTime": "2017-05-06T00:00",
"endDateTime": "2017-11-29T00:00"
}
}
],
"contact": [
{
"contactName": "Charles Chopin",
"contactType": "secondary",
"partyRoleType": "Publisher",
"validFor": {

© TM Forum 2017. All Rights Reserved. Page 66

Account Management API REST Specification

"startDateTime": "2017-05-02T00:00",
"endDateTime": "2017-11-29T00:00"
},
"contactMedium": [
{
"preferred": true,
"type": "Email",
"validFor": {
"startDateTime": "2017-05-06T00:00",
"endDateTime": "2017-11-29T00:00"
},
"characteristic": [
{
"name": "Colour",
"value": "white"
},
{
"name": "Memory",
"value": "64"
}
]
}
],
"relatedParty": {
"href": "[Link]
"id": "3665",
"name": "Richard Cole",
"role": "customer",
"validFor": {
"startDateTime": "2017-05-06T00:00",
"endDateTime": "2017-11-29T00:00"
}
}
}
],
"accountBalance": [
{
"amount": 54.88,
"type": "ReceivableBalance",
"validFor": {
"startDateTime": "2017-05-01T00:00",
"endDateTime": "2017-11-29T00:00"
}
}
],
"accountRelationship": [
{
"relationshipType": "contains",
"validFor": {
"startDateTime": "2017-05-04T00:00",
"endDateTime": "2017-11-29T00:00"
},
"account": {
"description": "This account ...",
"href": "[Link]
"id": "4807",

© TM Forum 2017. All Rights Reserved. Page 67

Account Management API REST Specification

"name": "Paradise Account"

}
}
]
}

CREATE BILLING ACCOUNT

POST /billingAccount
Note: this operation is available only to ADMIN API users

Description

This operation creates a billing account entity.

Mandatory and Non Mandatory Attributes

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

Non Mandatory Attributes Default Value Rule

paymentStatus
creditLimit
description
lastModified
state
type
billStructure
paymentPlan
financialAccount
defaultPaymentMethod
relatedParty
taxExemption
contact
accountBalance
accountRelationship

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

© TM Forum 2017. All Rights Reserved. Page 68

Account Management API REST Specification

[Link] Current date

[Link] "Bill issuer choice"
[Link] "Standard invoice"
[Link] "Electronic invoice"
currencyCode "National currency"

Usage Samples

Here's an example of a request for creating a BillingAccount resource. In this example the request only
passes mandatory attributes.

Request

POST /accountManagement/billingAccount
Content-Type: application/json

{
"name": "Home Account"
}

Response

201

{
"href": "[Link]
"id": "4835",
"name": "Home Account"
}

PATCH BILLING ACCOUNT

PATCH /billingAccount/{id}
Description

This operation allows partial updates of a billing account 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

© TM Forum 2017. All Rights Reserved. Page 69

Account Management API REST Specification

The tables below provide the list of patchable and non patchable attributes, including constraint rules on
their usage.
Notice that patching is possible only for 'admin' API users.

Patchable Attributes Rule

[Link]
[Link]
[Link]
paymentStatus
creditLimit
description
lastModified
name
state
type
billStructure
paymentPlan
financialAccount
defaultPaymentMethod
relatedParty
taxExemption
contact
accountRelationship

Non Patchable Attributes Rule

id
href
accountBalance
paymentStatus
creditLimit
description
lastModified
name
state
type
billStructure
paymentPlan
financialAccount
defaultPaymentMethod
relatedParty
taxExemption
contact
accountRelationship

Usage Samples

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

Changing the currency code (using json-patch)

© TM Forum 2017. All Rights Reserved. Page 70

Account Management API REST Specification

Request

PATCH /accountManagement/billingAccount/42
Content-Type: application/json-patch+json

{
"path": "/currencyCode",
"value": "USD",
"op": "replace"
}

Response

201

{ Similar JSON as in GET response with currency code changed}

DELETE BILLING ACCOUNT

DELETE /billingAccount/{id}
Note: this operation is available only to ADMIN API users

Description

This operation deletes a billing account entity.

Usage Samples

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

Request

DELETE /accountManagement/billingAccount/42

Response

204

OPERATIONS ON SETTLEMENT ACCOUNT

© TM Forum 2017. All Rights Reserved. Page 71

Account Management API REST Specification

LIST SETTLEMENT ACCOUNTS

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

This operation list settlement account 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 SettlementAccount resources.

List all settlement accounts connected to a given party account. The result items are shrunk to show only
the id and name (fields=id,name).

Request

GET /accountManagement/settlementAccount?fields=id,name&[Link]=7876543
Accept: application/json

Response

200

[
{
"id": "42",
"name": "API Usage Account"
},
{
"id": "43",
"name": "Storage Usage Account"
}
]

RETRIEVE SETTLEMENT ACCOUNT

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

This operation retrieves a settlement account entity.

Attribute selection is enabled for all first level attributes.

© TM Forum 2017. All Rights Reserved. Page 72

Account Management API REST Specification

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 SettlementAccount resource.

Request

GET /accountManagement/settlementAccount/6202
Accept: application/json

Response

200

{
"paymentStatus": "Due",
"creditLimit": "a Money ...",
"description": "This settlement account ...",
"href": "[Link]
"id": "6202",
"lastModified": "2017-05-03T00:00",
"name": "Per Usage Account",
"state": "active",
"type": "Business",
"billStructure": {
"presentationMedia": [
{
"href": "[Link]
"id": "7422",
"name": "Paper"
}
],
"format": {
"href": "[Link]
"id": "3588",
"name": "Detailed invoice"
},
"cycleSpecification": {
"dateShift": 20,
"frequency": "monthly",
"href": "[Link]
"id": "5190",
"name": "Annual billing"
}
},
"paymentPlan": [
{
"numberOfPayments": 4,

© TM Forum 2017. All Rights Reserved. Page 73

Account Management API REST Specification

"paymentFrequency": "bimonthly",
"priority": 4,
"status": "Effective",
"totalAmount": 543.8,
"type": "regular",
"validFor": {
"startDateTime": "2017-05-04T00:00",
"endDateTime": "2017-11-29T00:00"
},
"paymentMethod": {
"href": "[Link]
"id": "1547",
"name": "family payment"
}
}
],
"financialAccount": {
"href": "[Link]
"id": "4503",
"name": "Travel account",
"accountBalance": {
"amount": 55.91,
"type": "ReceivableBalance",
"validFor": {
"startDateTime": "2017-04-30T00:00",
"endDateTime": "2017-11-29T00:00"
}
}
},
"defaultPaymentMethod": {
"href": "[Link]
"id": "3135",
"name": "family payment"
},
"relatedParty": [
{
"href": "[Link]
"id": "2981",
"name": "Gustave Flaubert",
"role": "owner",
"validFor": {
"startDateTime": "2017-05-06T00:00",
"endDateTime": "2017-11-29T00:00"
}
}
],
"taxExemption": [
{
"certificateNumber": "45678909876",
"issuingJurisdiction": "Embassy",
"reason": "VIP",
"validFor": {
"startDateTime": "2017-05-06T00:00",
"endDateTime": "2017-11-29T00:00"
}
}

© TM Forum 2017. All Rights Reserved. Page 74

Account Management API REST Specification

],
"contact": [
{
"contactName": "Ludwig Borgia",
"contactType": "secondary",
"partyRoleType": "CustomerAccountRepresentative",
"validFor": {
"startDateTime": "2017-04-30T00:00",
"endDateTime": "2017-11-29T00:00"
},
"contactMedium": [
{
"preferred": true,
"type": "TelephoneNumber",
"validFor": {
"startDateTime": "2017-05-06T00:00",
"endDateTime": "2017-11-29T00:00"
},
"characteristic": [
{
"name": "Colour",
"value": "blue"
},
{
"name": "Memory",
"value": "64"
}
]
}
],
"relatedParty": {
"href": "[Link]
"id": "4985",
"name": "Gustave Flaubert",
"role": "vendor",
"validFor": {
"startDateTime": "2017-05-06T00:00",
"endDateTime": "2017-11-29T00:00"
}
}
}
],
"accountBalance": [
{
"amount": 51.77,
"type": "DepositBalance",
"validFor": {
"startDateTime": "2017-04-29T00:00",
"endDateTime": "2017-11-29T00:00"
}
}
],
"accountRelationship": [
{
"relationshipType": "linked",
"validFor": {

© TM Forum 2017. All Rights Reserved. Page 75

Account Management API REST Specification

"startDateTime": "2017-05-04T00:00",
"endDateTime": "2017-11-29T00:00"
},
"account": {
"description": "This account ...",
"href": "[Link]
"id": "2553",
"name": "Paradise Account"
}
}
]
}

CREATE SETTLEMENT ACCOUNT

POST /settlementAccount
Note: this operation is available only to ADMIN API users

Description

This operation creates a settlement account entity.

Mandatory and Non Mandatory Attributes

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

Non Mandatory Attributes Default Value Rule

paymentStatus
creditLimit
description
lastModified
state
type
billStructure
paymentPlan
financialAccount
defaultPaymentMethod
relatedParty
taxExemption
contact
accountBalance
accountRelationship

© TM Forum 2017. All Rights Reserved. Page 76

Account Management API REST Specification

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

[Link] Current date
[Link] "Bill issuer choice"
[Link] "Standard invoice"
[Link] "Electronic invoice"
currencyCode "National currency"

Usage Samples

Here's an example of a request for creating a SettlementAccount resource. In this example the request
only passes mandatory attributes.

Request

POST /accountManagement/settlementAccount
Content-Type: application/json

{
"name": "Per Usage Account"
}

Response

201

{
"href": "[Link]
"id": "6202",
"name": "Per Usage Account"
}

PATCH SETTLEMENT ACCOUNT

PATCH /settlementAccount/{id}
Description

This operation allows partial updates of a settlement account 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

© TM Forum 2017. All Rights Reserved. Page 77

Account Management API REST Specification

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.
Notice that patching is possible only for 'admin' API users.

Patchable Attributes Rule

[Link]
[Link]
[Link]
paymentStatus
creditLimit
description
lastModified
name
state
type
billStructure
paymentPlan
financialAccount
defaultPaymentMethod
relatedParty
taxExemption
contact
accountRelationship

Non Patchable Attributes Rule

id
href
accountBalance
paymentStatus
creditLimit
description
lastModified
name
state
type
billStructure
paymentPlan
financialAccount
defaultPaymentMethod
relatedParty
taxExemption
contact
accountRelationship

Usage Samples

© TM Forum 2017. All Rights Reserved. Page 78

Account Management API REST Specification

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

Changing the currency code (using json-patch)

Request

PATCH /accountManagement/settlementAccount/42
Content-Type: application/json-patch+json

{
"path": "/currencyCode",
"value": "USD",
"op": "replace"
}

Response

201

{ Similar JSON as in GET response with currency code changed}

DELETE SETTLEMENT ACCOUNT

DELETE /settlementAccount/{id}
Note: this operation is available only to ADMIN API users

Description

This operation deletes a settlement account entity.

Usage Samples

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

Request

DELETE /accountManagement/settlementAccount/42

Response

204

© TM Forum 2017. All Rights Reserved. Page 79

Account Management API REST Specification

OPERATIONS ON FINANCIAL ACCOUNT

LIST FINANCIAL ACCOUNTS

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

This operation list financial account 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 FinancialAccount resources.

Request

GET /accountManagement/financialAccount
Accept: application/json

Response

200

[
{
"creditLimit": "a Money ...",
"description": "This financial account ...",
"href": "[Link]
"id": "4055",
"lastModified": "2017-05-03T00:00",
"name": "Travel account",
"state": "Active",
"type": "Global",
"relatedParty": [
{
"href": "[Link]
"id": "2110",
"name": "John Doe",
"role": "owner",
"validFor": {
"startDateTime": "2017-05-01T00:00",
"endDateTime": "2017-11-29T00:00"
}
}
],
"taxExemption": [

© TM Forum 2017. All Rights Reserved. Page 80

Account Management API REST Specification

{
"certificateNumber": "45678909876",
"issuingJurisdiction": "Prefecture",
"reason": "VIP",
"validFor": {
"startDateTime": "2017-05-06T00:00",
"endDateTime": "2017-11-29T00:00"
}
}
],
"contact": [
{
"contactName": "Rachel Douglas",
"contactType": "secondary",
"partyRoleType": "CustomerAccountRepresentative",
"validFor": {
"startDateTime": "2017-04-29T00:00",
"endDateTime": "2017-11-29T00:00"
},
"contactMedium": [
{
"preferred": true,
"type": "PostalAddress",
"validFor": {
"startDateTime": "2017-05-03T00:00",
"endDateTime": "2017-11-29T00:00"
},
"characteristic": [
{
"name": "Colour",
"value": "pink"
},
{
"name": "Memory",
"value": "32"
}
]
}
],
"relatedParty": {
"href": "[Link]
"id": "8202",
"name": "John Doe",
"role": "bill receiver",
"validFor": {
"startDateTime": "2017-04-30T00:00",
"endDateTime": "2017-11-29T00:00"
}
}
}
],
"accountBalance": [
{
"amount": 58.7,
"type": "DepositBalance",
"validFor": {

© TM Forum 2017. All Rights Reserved. Page 81

Account Management API REST Specification

"startDateTime": "2017-05-02T00:00",
"endDateTime": "2017-11-29T00:00"
}
}
],
"accountRelationship": [
{
"relationshipType": "linked",
"validFor": {
"startDateTime": "2017-04-29T00:00",
"endDateTime": "2017-11-29T00:00"
},
"account": {
"description": "This account ...",
"href": "[Link]
"id": "9531",
"name": "Paradise Account"
}
}
]
}
]

RETRIEVE FINANCIAL ACCOUNT

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

This operation retrieves a financial account 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 FinancialAccount resource.

Request

GET /accountManagement/financialAccount/4055
Accept: application/json

Response

200

© TM Forum 2017. All Rights Reserved. Page 82

Account Management API REST Specification

{
"creditLimit": "a Money ...",
"description": "This financial account ...",
"href": "[Link]
"id": "4055",
"lastModified": "2017-05-03T00:00",
"name": "Travel account",
"state": "Active",
"type": "Global",
"relatedParty": [
{
"href": "[Link]
"id": "2110",
"name": "John Doe",
"role": "owner",
"validFor": {
"startDateTime": "2017-05-01T00:00",
"endDateTime": "2017-11-29T00:00"
}
}
],
"taxExemption": [
{
"certificateNumber": "45678909876",
"issuingJurisdiction": "Prefecture",
"reason": "VIP",
"validFor": {
"startDateTime": "2017-05-06T00:00",
"endDateTime": "2017-11-29T00:00"
}
}
],
"contact": [
{
"contactName": "Rachel Douglas",
"contactType": "secondary",
"partyRoleType": "CustomerAccountRepresentative",
"validFor": {
"startDateTime": "2017-04-29T00:00",
"endDateTime": "2017-11-29T00:00"
},
"contactMedium": [
{
"preferred": true,
"type": "PostalAddress",
"validFor": {
"startDateTime": "2017-05-03T00:00",
"endDateTime": "2017-11-29T00:00"
},
"characteristic": [
{
"name": "Colour",
"value": "pink"
},
{
"name": "Memory",

© TM Forum 2017. All Rights Reserved. Page 83

Account Management API REST Specification

"value": "32"
}
]
}
],
"relatedParty": {
"href": "[Link]
"id": "8202",
"name": "John Doe",
"role": "bill receiver",
"validFor": {
"startDateTime": "2017-04-30T00:00",
"endDateTime": "2017-11-29T00:00"
}
}
}
],
"accountBalance": [
{
"amount": 58.7,
"type": "DepositBalance",
"validFor": {
"startDateTime": "2017-05-02T00:00",
"endDateTime": "2017-11-29T00:00"
}
}
],
"accountRelationship": [
{
"relationshipType": "linked",
"validFor": {
"startDateTime": "2017-04-29T00:00",
"endDateTime": "2017-11-29T00:00"
},
"account": {
"description": "This account ...",
"href": "[Link]
"id": "9531",
"name": "Paradise Account"
}
}
]
}

CREATE FINANCIAL ACCOUNT

POST /financialAccount
Note: this operation is available only to ADMIN API users

Description

This operation creates a financial account entity.

© TM Forum 2017. All Rights Reserved. Page 84

Account Management API REST Specification

Mandatory and Non Mandatory Attributes

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

creditLimit
description
lastModified Automatically
generated
state
type
relatedParty
taxExemption
contact
accountBalance
accountRelationship

Additional Rules

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

Context Mandatory Sub-Attributes

taxExemption issuingJurisdiction, validFor
accountRelationship relationshipType, validFor
contact contactType, validFor
ownerParty id, name
accountBalance type, amount, validFor, status
paymentPlan status, amount, paymentFrequency, validFor, paymentMethod

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
href Automatically generated
lastModified Automatically generated

Usage Samples

Here's an example of a request for creating a FinancialAccount resource. In this example the request only
passes mandatory attributes.

© TM Forum 2017. All Rights Reserved. Page 85

Account Management API REST Specification

Request

POST /accountManagement/financialAccount
Content-Type: application/json

{
"name": "Travel account"
}

Response

201

{
"href": "[Link]
"id": "4055",
"lastModified": "2017-05-03T00:00",
"name": "Travel account"
}

PATCH FINANCIAL ACCOUNT

PATCH /financialAccount/{id}
Description

This operation allows partial updates of a financial account 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

creditLimit
description
name
state
type
relatedParty
taxExemption
contact

© TM Forum 2017. All Rights Reserved. Page 86

Account Management API REST Specification

accountBalance
accountRelationship

Non Patchable Attributes Rule

id
href
lastModified
creditLimit
description
name
state
type
relatedParty
taxExemption
contact
accountBalance
accountRelationship

Usage Samples

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

Request

PATCH /accountManagement/financialAccount/4055
Content-Type: application/merge-patch+json

{
"name": "new name"
}

Response

201

{
"creditLimit": "a Money ...",
"description": "This financial account ...",
"href": "[Link]
"id": "4055",
"lastModified": "2017-05-03T00:00",
"name": "new name",
"state": "Active",
"type": "Global",
"relatedParty": [
{
"href": "[Link]
"id": "2110",
"name": "John Doe",

© TM Forum 2017. All Rights Reserved. Page 87

Account Management API REST Specification

"role": "owner",
"validFor": {
"startDateTime": "2017-05-01T00:00",
"endDateTime": "2017-11-29T00:00"
}
}
],
"taxExemption": [
{
"certificateNumber": "45678909876",
"issuingJurisdiction": "Prefecture",
"reason": "VIP",
"validFor": {
"startDateTime": "2017-05-06T00:00",
"endDateTime": "2017-11-29T00:00"
}
}
],
"contact": [
{
"contactName": "Rachel Douglas",
"contactType": "secondary",
"partyRoleType": "CustomerAccountRepresentative",
"validFor": {
"startDateTime": "2017-04-29T00:00",
"endDateTime": "2017-11-29T00:00"
},
"contactMedium": [
{
"preferred": true,
"type": "PostalAddress",
"validFor": {
"startDateTime": "2017-05-03T00:00",
"endDateTime": "2017-11-29T00:00"
},
"characteristic": [
{
"name": "Colour",
"value": "pink"
},
{
"name": "Memory",
"value": "32"
}
]
}
],
"relatedParty": {
"href": "[Link]
"id": "8202",
"name": "John Doe",
"role": "bill receiver",
"validFor": {
"startDateTime": "2017-04-30T00:00",
"endDateTime": "2017-11-29T00:00"
}

© TM Forum 2017. All Rights Reserved. Page 88

Account Management API REST Specification

}
}
],
"accountBalance": [
{
"amount": 58.7,
"type": "DepositBalance",
"validFor": {
"startDateTime": "2017-05-02T00:00",
"endDateTime": "2017-11-29T00:00"
}
}
],
"accountRelationship": [
{
"relationshipType": "linked",
"validFor": {
"startDateTime": "2017-04-29T00:00",
"endDateTime": "2017-11-29T00:00"
},
"account": {
"description": "This account ...",
"href": "[Link]
"id": "9531",
"name": "Paradise Account"
}
}
]
}

DELETE FINANCIAL ACCOUNT

DELETE /financialAccount/{id}
Note: this operation is available only to ADMIN API users

Description

This operation deletes a financial account entity.

Usage Samples

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

Request

DELETE /accountManagement/financialAccount/42

© TM Forum 2017. All Rights Reserved. Page 89

Account Management API REST Specification

Response

204

OPERATIONS ON BILLING CYCLE SPECIFICATION

LIST BILLING CYCLE SPECIFICATIONS

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

This operation lists billing cycle 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

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

Retrieving all billing cycle specifications. The result items are shrunk to show only the id and name
(fields=id,name)

Request

GET /accountManagement/billingCycleSpecification?fields=id,name
Accept: application/json

Response

200

[
{
"id": "9473",
"name": "bimonthly"
},
{
"id": "9473",
"name": "monthly"
},
{
"id": "9899",
"name": "weekly"

© TM Forum 2017. All Rights Reserved. Page 90

Account Management API REST Specification

}
]

RETRIEVE BILLING CYCLE SPECIFICATION

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

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

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

Request

GET /accountManagement/billingCycleSpecification/3353
Accept: application/json

Response

200

{
"billingDateShift": 20,
"billingPeriod": "a string ...",
"chargeDateOffset": "a int ...",
"creditDateOffset": "a int ...",
"description": "This billing cycle specification ...",
"frequency": "monthly",
"href": "[Link]
"id": "3353",
"mailingDateOffset": 53,
"name": "Monthly billing on the 15",
"paymentDueDateOffset": 45,
"validFor": {
"startDateTime": "2017-05-06T00:00",
"endDateTime": "2017-11-29T00:00"
}
}

CREATE BILLING CYCLE SPECIFICATION

© TM Forum 2017. All Rights Reserved. Page 91
Account Management API REST Specification

POST /billingCycleSpecification
Note: this operation is available only to ADMIN API users

Description

This operation creates a billing cycle specification entity.

Mandatory and Non Mandatory Attributes

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

billingDateShift
billingPeriod
chargeDateOffset
creditDateOffset
description
frequency
mailingDateOffset
paymentDueDateOffset
validFor

Usage Samples

Here's an example of a request for creating a BillingCycleSpecification resource. In this example the
request only passes mandatory attributes.

Request

POST /accountManagement/billingCycleSpecification
Content-Type: application/json

{
"name": "Monthly billing on the 15"
}

Response

201

{
"href": "[Link]

© TM Forum 2017. All Rights Reserved. Page 92

Account Management API REST Specification

"id": "3353",
"name": "Monthly billing on the 15"
}

PATCH BILLING CYCLE SPECIFICATION

PATCH /billingCycleSpecification/{id}
Description

This operation allows partial updates of a billing cycle specification 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

billingDateShift
billingPeriod
chargeDateOffset
creditDateOffset
description
frequency
mailingDateOffset
name
paymentDueDateOffset
validFor

Non Patchable Attributes Rule

id
href
billingDateShift
billingPeriod
chargeDateOffset
creditDateOffset
description
frequency
mailingDateOffset
name
paymentDueDateOffset
validFor

© TM Forum 2017. All Rights Reserved. Page 93

Account Management API REST Specification

Usage Samples

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

Changing the frequency (using json-merge)

Request

PATCH /accountManagement/billingCycleSpecification/42
Content-Type: application/merge-patch+json

{
"frequency": "bimonthly"
}

Response

201

{ Similar JSON as in GET response with frequency changed }

DELETE BILLING CYCLE SPECIFICATION

DELETE /billingCycleSpecification/{id}
Note: this operation is available only to ADMIN API users

Description

This operation deletes a billing cycle specification entity.

Usage Samples

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

Request

DELETE /accountManagement/billingCycleSpecification/42

Response

204

© TM Forum 2017. All Rights Reserved. Page 94

Account Management API REST Specification

OPERATIONS ON BILL FORMAT

LIST BILL FORMATS

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

This operation list bill format 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 BillFormat resources.

Retrieving all bill formats. The result items are shrunk to show only the id and name (fields=id,name)

Request

GET /accountManagement/billFormat?fields=id,name
Accept: application/json

Response

200

[
{
"id": "42",
"name": "simple invoice"
},
{
"id": "43",
"name": "detailed invoice"
}
]

RETRIEVE BILL FORMAT

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

© TM Forum 2017. All Rights Reserved. Page 95

Account Management API REST Specification

This operation retrieves a bill format 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 BillFormat resource.

Request

GET /accountManagement/billFormat/4962
Accept: application/json

Response

200

{
"description": "This bill format ...",
"href": "[Link]
"id": "4962",
"name": "Summary invoice"
}

CREATE BILL FORMAT

POST /billFormat
Note: this operation is available only to ADMIN API users

Description

This operation creates a bill format entity.

Mandatory and Non Mandatory Attributes

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

description

© TM Forum 2017. All Rights Reserved. Page 96

Account Management API REST Specification

Usage Samples

Here's an example of a request for creating a BillFormat resource. In this example the request only
passes mandatory attributes.

Request

POST /accountManagement/billFormat
Content-Type: application/json

{
"name": "Summary invoice"
}

Response

201

{
"href": "[Link]
"id": "4962",
"name": "Summary invoice"
}

PATCH BILL FORMAT

PATCH /billFormat/{id}
Note: this operation is available only to ADMIN API users

Description

This operation allows partial updates of a bill format 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.
Notice that patching is possible only for 'admin' API users.

Patchable Attributes Rule

description

© TM Forum 2017. All Rights Reserved. Page 97

Account Management API REST Specification

name

Non Patchable Attributes Rule

id
href
description
name

Usage Samples

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

Changing the description (using json-merge)

Request

PATCH /accountManagement/billFormat/42
Content-Type: application/merge-patch+json

{
"description": "Detailed billing containing full phone numbers of calls"
}

Response

201

{ Similar JSON as in GET response with description changed }

DELETE BILL FORMAT

DELETE /billFormat/{id}
Note: this operation is available only to ADMIN API users

Description

This operation deletes a bill format entity.

Usage Samples

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

© TM Forum 2017. All Rights Reserved. Page 98

Account Management API REST Specification

Request

DELETE /accountManagement/billFormat/42

Response

204

OPERATIONS ON BILL PRESENTATION MEDIA

LIST BILL PRESENTATION MEDIAS

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

This operation list bill presentation media 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 BillPresentationMedia resources.

Retrieving all bill presentation formats. The result items are shrinked to show only the id and name
(fields=id,name)

Request

GET /accountManagement/billPresentationMedia?fields=id,name
Accept: application/json

Response

200

[
{
"id": "42",
"name": "signed mail"
},
{

© TM Forum 2017. All Rights Reserved. Page 99

Account Management API REST Specification

"id": "43",
"name": "postal"
},
{
"id": "44",
"name": "web"
}
]

RETRIEVE BILL PRESENTATION MEDIA

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

This operation retrieves a bill presentation media 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 BillPresentationMedia resource.

Request

GET /accountManagement/billPresentationMedia/5458
Accept: application/json

Response

200

{
"description": "This bill presentation media ...",
"href": "[Link]
"id": "5458",
"name": "Email"
}

CREATE BILL PRESENTATION MEDIA

POST /billPresentationMedia
Note: this operation is available only to ADMIN API users

© TM Forum 2017. All Rights Reserved. Page 100

Account Management API REST Specification

Description

This operation creates a bill presentation media entity.

Mandatory and Non Mandatory Attributes

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

description

Usage Samples

Here's an example of a request for creating a BillPresentationMedia resource. In this example the request
only passes mandatory attributes.

Request

POST /accountManagement/billPresentationMedia
Content-Type: application/json

{
"name": "Email"
}

Response

201

{
"href": "[Link]
"id": "5458",
"name": "Email"
}

PATCH BILL PRESENTATION MEDIA

PATCH /billPresentationMedia/{id}
Note: this operation is available only to ADMIN API users

Description

© TM Forum 2017. All Rights Reserved. Page 101

Account Management API REST Specification

This operation allows partial updates of a bill presentation media 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.
Notice that patching is possible only for 'admin' API users.

Patchable Attributes Rule

description
name

Non Patchable Attributes Rule

id
href
description
name

Usage Samples

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

Changing the name (using json-merge)

Request

PATCH /accountManagement/billPresentationMedia/42
Content-Type: application/merge-patch+json

{
"name": "secure post mail"
}

Response

201

{ Similar JSON as in GET response with name changed }

DELETE BILL PRESENTATION MEDIA

© TM Forum 2017. All Rights Reserved. Page 102

Account Management API REST Specification

DELETE /billPresentationMedia/{id}
Note: this operation is available only to ADMIN API users

Description

This operation deletes a bill presentation media entity.

Usage Samples

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

Request

DELETE /accountManagement/billPresentationMedia/42

Response

204

© TM Forum 2017. All Rights Reserved. Page 103

Account 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]

UNREGISTER LISTENER

© TM Forum 2017. All Rights Reserved. Page 104

Account Management API REST Specification

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.

Request

POST /client/listener

© TM Forum 2017. All Rights Reserved. Page 105

Account Management API REST Specification

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 2017. All Rights Reserved. Page 106

Account Management API REST Specification

ACKNOWLEDGMENTS

RELEASE HISTORY

Release Date Release led by: Description

Number

Release 1.0 04/15/2017 Pierre Gauthier First Release of the

TM Forum Document. Generated
pgauthier@[Link] from API Data Model. It is
a rebrand of the old Billing
Management specification
since its scope has been
enlarged to other
accounting aspects.

Release 11/21/2017 Adrienne Walcott Updated to reflect TM

17.0.1 Forum Approved Status

Version 1.0.1

CONTRIBUTORS TO DOCUMENT

Veronique Mauneau Orange

Johannes Minnaar Ericsson

Steve Bouch BT

George Glass BT

Jean-Luc Tymen Orange

Christian Koerner Infonova

Milan Patel Huawei

Jonathan Goldberg Amdocs

Josh Salomon Amdocs

© TM Forum 2017. All Rights Reserved. Page 107

Account Management API REST Specification

Pierre Gauthier TM Forum

John Morey Ciena

Cliff C Faurer AMKB Cloud

Mariano Belaunde Orange

© TM Forum 2017. All Rights Reserved. Page 108