TM Forum Specification

Party Management
API REST Specification

TMF632
Release 19.0.0
June 2019

Latest Update: TM Forum Release 19.0.0 Member Evaluation

Version 4.0.0
IPR Mode: RAND

©TM Forum 2019. All Rights Reserved.

Party Management API REST Specification

NOTICE
Copyright © TM Forum 2019. All Rights Reserved.

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

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

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

Direct inquiries to the TM Forum office:

4 Century Drive, Suite 100

Parsippany, NJ 07054, USA
Tel No. +1 973 944 5100
Fax No. +1 973 944 5110
TM Forum Web Page: [Link]

© TM Forum 2019. All Rights Reserved Page 2 sur 62

Party Management API REST Specification

Table of Contents
NOTICE 2

Table of Contents 3

List of Tables 5

Introduction 6

Sample Use Cases 7

Support of polymorphism and extension patterns 9

RESOURCE MODEL 10

Managed Entity and Task Resource Models 10

Individual resource 10

Organization resource 24

Notification Resource Models 35

Individual Create Event 36

Individual Attribute Value Change Event 37

Individual State Change Event 37

Individual Delete Event 37

Organization Create Event 38

Organization Attribute Value Change Event 38

Organization State Change Event 39

Organization Delete Event 39

API OPERATIONS 40

Operations on Individual 41

List individuals 41

Retrieve individual 42

Create individual 47

Patch individual 48

© TM Forum 2019. All Rights Reserved Page 3 sur 62

Party Management API REST Specification

Delete individual 50

Operations on Organization 50

List organizations 50

Retrieve organization 51

Create organization 55

Patch organization 56

Delete organization 58

API Notifications 59

Register listener 59

Unregister listener 60

Publish Event to listener 60

Acknowledgements 62

VERSION History 62

Release History 62

© TM Forum 2019. All Rights Reserved Page 4 sur 62

Party Management API REST Specification

List of Tables
N/A

© TM Forum 2019. All Rights Reserved Page 5 sur 62

Party Management API REST Specification

Introduction
The following document is the specification of the REST API for Party Management. It includes the model definition
as well as all available operations. Possible actions are creating, updating and retrieving parties (individuals or
organizations), including filtering.

Party is an abstract concept that represents an individual (person) or an organization that has any kind of relation
with the enterprise.

Party is created to record an individual or an organization before the assignment of any role.

Party API manages the following data resource:

Individual

• Individual represents a single human being (a man, woman or child). The individual can be a customer, an
employee or any other person that the organization needs to store information about.
Organization

• Organization represents a group of people identified by shared interests or purpose. Examples include
business, department and enterprise. Because of the complex nature of many businesses, both organizations
and organization units are represented by the same data.
Party API performs the following operations on individuals and organizations:

• Retrieval of an individual or an organization

• List a collection of individuals or organization depending on filter criteria
• Partial update of an individual or an organization
• Creation of an individual or an organization
• Deletion of an individual or an organization
• Notification of events relating to an individual or an organization.

© TM Forum 2019. All Rights Reserved Page 6 sur 62

Party Management API REST Specification

Sample Use Cases

In order to illustrate JSON message we will use a Quote with following features:

To illustrate JSON representation of resources concerned by this API, we use the two use cases detailed below.

Use case 1 (UC1): An individual employee of an organization

© TM Forum 2019. All Rights Reserved Page 7 sur 62

Party Management API REST Specification

Use case 2 (UC2): a company (organization) with two departments (organizations)

© TM Forum 2019. All Rights Reserved Page 8 sur 62

Party Management API REST Specification

Support of polymorphism and extension patterns

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

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

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

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

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

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

© TM Forum 2019. All Rights Reserved Page 9 sur 62

Party Management API REST Specification

RESOURCE MODEL
Managed Entity and Task Resource Models

Individual resource
Individual represents a single human being (a man, woman or child). The individual can be a customer, an
employee or any other person that the organization needs to store information about.

Resource model

© TM Forum 2019. All Rights Reserved Page 10 sur 62

Party Management API REST Specification

© TM Forum 2019. All Rights Reserved Page 11 sur 62

Party Management API REST Specification

Lifecycle

Field descriptions

Individual fields

href A string. Hyperlink to access the organization.

id A string. Unique identifier of the organization.

aristocraticTitle A string. e.g. Baron, Graf, Earl,….

birthDate A date time (DateTime). Birth date.

countryOfBirth A string. Country where the individual was born.

deathDate A date time (DateTime). Date of death.

disability A list of disabilities (Disability [*]). Lack or inadequate strength or ability.

© TM Forum 2019. All Rights Reserved Page 12 sur 62

Party Management API REST Specification

familyName A string. Contains the non-chosen or inherited name. Also known as last name in the
Western context.

familyNamePrefix A string. Family name prefix.

formattedName A string. A fully formatted name in one string with all of its pieces in their proper place
and all of the necessary punctuation. Useful for specific contexts (Chinese, Japanese,
Korean,…).

fullName A string. Full name flatten (first, middle, and last names).

gender A string. Gender.

generation A string. e.g.. Sr, Jr, III (the third),….

givenName A string. First name of the individual.

individualIdentification A list of individual identifications (IndividualIdentification [*]). Represents our

registration of information used as proof of identity by an individual (passport, national
identity card, drivers license, social security number, birth certificate).

languageAbility A list of language abilities (LanguageAbility [*]). Ability of an individual to understand

or converse in a language.

legalName A string. Legal name or birth name (name one has for official purposes).

location A string. Temporary current location od the individual (may be used if the individual has
approved its sharing).

maritalStatus A string. Marital status (married, divorced, widow ...).

middleName A string. Middles name or initial.

nationality A string. Nationality.

otherName A list of other name individuals (OtherNameIndividual [*]). Keeps track of other names,
for example the old name of a woman before marriage or an artist name.

placeOfBirth A string. Reference to the place where the individual was born.

preferredGivenName A string. Contains the chosen name by which the individual prefers to be addressed.
Note: This name may be a name other than a given name, such as a nickname.

skill A list of skills (Skill [*]). Skills evaluated for an individual with a level and possibly with
a limited validity when an obsolescence is defined (Ex: the first-aid certificate first level
is limited to one year and an update training is required each year to keep the level).

status An individual state type (IndividualStateType). Status of the individual.

© TM Forum 2019. All Rights Reserved Page 13 sur 62

Party Management API REST Specification

title A string. Useful for titles (aristocratic, social,...) Pr, Dr, Sir, ...

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

creditRating A list of party credit profiles (PartyCreditProfile [*]). An individual might be evaluated
for its worthiness and this evaluation might be based on a credit rating given by a credit
agency.

externalReference A list of external references (ExternalReference [*]). External reference of the individual
or reference in other system.

partyCharacteristic A list of characteristics (Characteristic [*]). Describes a given characteristic of an object

or entity through a name/value pair.

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

taxExemptionCertificate A list of tax exemption certificates (TaxExemptionCertificate [*]). A tax exemption

certificate represents a tax exemption granted to a party (individual or organization) by
a tax jurisdiction which may be a city, state, country,... An exemption has a certificate
identifier (received from the jurisdiction that levied the tax) and a validity period. An
exemption is per tax types and determines for each type of tax what portion of the tax
is exempted (partial by percentage or complete) via the tax definition.

AttachmentRefOrValue sub-resource

An attachment by value or by reference.

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

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

href A string. URI for this Attachment.

id A string. Unique identifier for this particular attachment.

url A string. Uniform Resource Locator, is a web page address (a subset of URI).

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

href A string. URI for this Attachment.

id A string. Unique identifier for this particular attachment.

name A string. The name of the attachment.

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

© TM Forum 2019. All Rights Reserved Page 14 sur 62

Party Management API REST Specification

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

href A string. URI for this Attachment.

id A string. Unique identifier for this particular attachment.

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

name A string. The name of the attachment.

url A string. Uniform Resource Locator, is a web page address (a subset of URI).

isRef A boolean. If true, a reference is given.

content A string with base64 encoded characters. The actual contents of the attachment object,
if embedded, encoded as base64

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

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

Characteristic sub-resource

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

name A string. Name of the characteristic.

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

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

ContactMedium sub-resource

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

characteristic A medium characteristic (MediumCharacteristic). Any additional characteristic(s) of this

contact medium.

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

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

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

Disability sub-resource

Lack or inadequate strength or ability.

disabilityCode A string. Code of the disability.

© TM Forum 2019. All Rights Reserved Page 15 sur 62

Party Management API REST Specification

disabilityName A string. Name of the disability.

validFor A time period. A period of time, either as a deadline (endDateTime only) a

startDateTime only, or both.

ExternalReference sub-resource

External reference of the individual or reference in other system.

externalReferenceType A string. Type of the external reference.

name A string. External reference name.

IndividualIdentification sub-resource

Represents our registration of information used as proof of identity by an individual (passport, national identity
card, drivers license, social security number, birth certificate).

attachment An attachment ref or value (AttachmentRefOrValue). An attachment by value or by

reference.

identificationId A string. Identifier.

identificationType A string. Identification type (passport, national identity card, drivers license, social
security number, birth certificate).

issuingAuthority A string. Authority which has issued the identifier, such as: social security, town hall.

issuingDate A date time (DateTime). Date at which the identifier was issued.

validFor A time period. The period for which the identification information is valid.

LanguageAbility sub-resource

Ability of an individual to understand or converse in a language.

isFavouriteLanguage A boolean. A “true” value specifies whether the language is considered by the individual
as his favourite one.

languageCode A string. Language code (RFC 5646).

languageName A string. Language name.

listeningProficiency A string. Listening proficiency evaluated for this language.

readingProficiency A string. Reading proficiency evaluated for this language.

speakingProficiency A string. Speaking proficiency evaluated for this language.

© TM Forum 2019. All Rights Reserved Page 16 sur 62

Party Management API REST Specification

validFor A time period (TimePeriod). A period of time, either as a deadline (endDateTime only)
a startDateTime only, or both.

writingProficiency A string. Writing proficiency evaluated for this language.

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.

contactType A string. The type of contact, for example: phone number such as mobile, fixed home,
fixed office. postal address such as shipping instalation….

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.

socialNetworkId A string. Identifier as a member of a social network.

stateOrProvince A string. State or province.

street1 A string. Describes the street.

street2 A string. Complementary street description.

OtherNameIndividual sub-resource

Keeps track of other names, for example the old name of a woman before marriage or an artist name.

aristocraticTitle A string. e.g. Baron, Graf, Earl,….

familyName A string. Contains the non-chosen or inherited name. Also known as last name in the
Western context.

familyNamePrefix A string. Family name prefix.

formattedName A string. . A fully formatted name in one string with all of its pieces in their proper place
and all of the necessary punctuation. Useful for specific contexts (Chinese, Japanese,
Korean,…).

fullName A string. Full name flatten (first, middle, and last names).

generation A string. e.g. Sr, Jr….

© TM Forum 2019. All Rights Reserved Page 17 sur 62

Party Management API REST Specification

givenName A string. First name.

legalName A string. Legal name or birth name (name one has for official purposes).

middleName A string. Middle name or initial.

preferredGivenName A string. Contains the chosen name by which the person prefers to be addressed.
Note: This name may be a name other than a given name, such as a nickname.

title A string. Use for titles (aristrocatic, social, ...): Pr, Dr, Sir,....

validFor A time period. A period of time, either as a deadline (endDateTime only) a

startDateTime only, or both.

PartyCreditProfile sub-resource

An individual might be evaluated for its worthiness and this evaluation might be based on a credit rating given by a
credit agency.

creditAgencyName A string. Name of the credit agency giving the score.

creditAgencyType A string. Type of the credit agency giving the score.

ratingReference A string. Reference corresponding to the credit rating.

ratingScore An integer. A measure of a party’s creditworthiness calculated on the basis of a

combination of factors such as their income and credit history.

validFor A time period. A period of time, either as a deadline (endDateTime only) a

startDateTime only, or both.

Quantity sub-resource

An amount in a given unit.

amount A float. Numeric value in a given unit.

units A string. Unit.

RelatedParty sub-resource

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

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

href A string. Reference of the related entity.

id A string. Unique identifier of a related entity.

name A string. Name of the related entity.

© TM Forum 2019. All Rights Reserved Page 18 sur 62

Party Management API REST Specification

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

role A string. Role played by the related party.

Skill sub-resource

Skills evaluated for an individual with a level and possibly with a limited validity when an obsolescence is defined (Ex:
the first-aid certificate first level is limited to one year and an update training is required each year to keep the level).

comment A string. A free text comment linked to the evaluation done.

evaluatedLevel A string. Level of expertise in a skill evaluated for an individual.

skillCode A string. Code of the skill.

skillName A string. Name of the skill such as Java language,….

validFor A time period. A period of time, either as a deadline (endDateTime only) a

startDateTime only, or both.

TaxDefinition sub-resource

Reference of a tax definition. A tax is levied by an authorized tax jurisdiction. There are many different types of tax
(Federal Tax levied by the US Government, State Tax levied by the State of California,…).

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

id A string. Unique identifier of the tax.

name A string. Tax name.

taxType A string. Type of the tax.

TaxExemptionCertificate sub-resource

A tax exemption certificate represents a tax exemption granted to a party (individual or organization) by a tax
jurisdiction which may be a city, state, country,... An exemption has a certificate identifier (received from the
jurisdiction that levied the tax) and a validity period. An exemption is per tax types and determines for each type of
tax what portion of the tax is exempted (partial by percentage or complete) via the tax definition.

attachment An attachment ref or value (AttachmentRefOrValue). An attachment by value or by

reference.

id A string. Unique identifier of the certificate of the tax exemption.

taxDefinition A list of tax definitions (TaxDefinition [*]). Reference of a tax definition. A tax is levied
by an authorized tax jurisdiction. There are many different types of tax (Federal Tax
levied by the US Government, State Tax levied by the State of California,…).

© TM Forum 2019. All Rights Reserved Page 19 sur 62

Party Management API REST Specification

validFor A time period. A period of time, either as a deadline (endDateTime only) a

startDateTime only, or both.

Json representation sample

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

{
"id": "42",
"href": "[Link]
"@type": "individual",
"gender": "female",
"placeOfBirth": "",
"countryOfBirth": "United States",
"nationality": "American",
"maritalStatus": "married",
"birthDate": "1967-09-26T05:00:00.246Z",
"deathDate": "",
"title": "",
"aristocraticTitle": "",
"generation": "",
"givenName": "Jane",
"preferredGivenName": "Lamborgizzia",
"familyNamePrefix": "",
"familyName": "Lamborgizzia",
"legalName": "Smith",
"middleName": "JL",
"fullName": "Jane Smith ep Lamborgizzia",
"formattedName": "Jane Smith ep Lamborgizzia",
"location": "",
"status": "validated",
"externalReference": [
{
"name": "[Link]
"externalReferenceType": "facebookId"
},
{
"name": "[Link]
"externalReferenceType": "googleId"
}
],
"partyCharacteristic": [
{
"name": "hobby",
"value": "Modern Jazz",
"valueType": "string"
},
{
"name": "hobby",
"value": "Cinema",
"valueType": "string"
},
{
"name": "childrenNumber",

© TM Forum 2019. All Rights Reserved Page 20 sur 62

Party Management API REST Specification

"value": "1",
"valueType": "number"
}
],
"otherName": [
{
"title": "",
"aristocraticTitle": "",
"generation": "",
"givenName": "Jane",
"preferredGivenName": "",
"familyNamePrefix": "",
"familyName": "Smith",
"legalName": "",
"middleName": "",
"fullName": "",
"formattedName": "",
"validFor": {
"startDateTime": "1967-09-26T00:00:00.246Z",
"endDateTime": "2015-06-15T00:00:00.246Z"
}
}
],
"individualIdentification": [
{
"identificationType": "passport",
"identificationId": "51DD1234",
"issuingAuthority": "US Government",
"issuingDate": "2017-10-22T07:49:25.246Z",
"validFor": {
"startDateTime": "2017-10-22T07:49:25.246Z",
"endDateTime": "2027-10-21T07:49:25.246Z"
},
"attachment": [
{
"id": "321",
"href": "/documentManagement/v4/attachment/321",
"attachmentType": "passportCopy",
"isRef": true,
"name": "[Link]",
"description": "Scanned copy of the passport"
}
]
}
],
"taxExemptionCertificate": [
{
"id": "555",
"validFor": {
"startDateTime": "2018-10-22T07:49:25.246Z",
"endDateTime": ""
},
"taxDefinition": [
{
"id": "96",
© TM Forum 2019. All Rights Reserved Page 21 sur 62
Party Management API REST Specification

"name": "value-added tax",

"taxType": "federalVat"
}
],
"attachment": {
"id": "666",
"href": "/documentManagement/v4/attachment/666",
"attachmentType": "documentCopy",
"isRef": true,
"name": "[Link]",
"description": "Electronic version of the tax exemption certificate",
"mimeType": "application/pdf",
"size": {
"amount": 130,
"name": "bytes"
},
"url": "[Link]
}
}
],
"creditRating": [
{
"creditAgencyName": "Experian",
"creditAgencyType": "externalAgency",
"ratingReference": "ref123",
"ratingScore": 680,
"validFor": {
"startDateTime": "2018-10-22T07:49:25.246Z",
"endDateTime": ""
}
}
],
"relatedParty": [
{
"id": "128",
"href": "[Link]
"role": "employee",
"name": "Coffee Do Brazil Fair Trade Marketing Department",
"@referredType": "organization"
}
],
"contactMedium": [
{
"preferred": true,
”mediumType”: “email”,
"validFor": {
"startDateTime": "2017-03-15T07:49:25.246Z",
"endDateTime": ""
},
"characteristic": {
"emailAddress": "[Link]@[Link]"
}
},
{
"preferred": false,
© TM Forum 2019. All Rights Reserved Page 22 sur 62
Party Management API REST Specification

" mediumType": "postalAddress",

"validFor": {
"startDateTime": "2017-03-15T07:49:25.246Z",
"endDateTime": ""
},
"characteristic": {
"city": "Morristown",
"country": "USA",
"postcode": "07960",
"stateOrProvince": "New Jersey",
"street1": "240 Headquarters Plazza",
"street2": "East Tower - 10th Floor"
}
}
],
"disability": [
{
"disabilityCode": "BLD",
"disabilityName": "Blind",
"validFor": {
"startDateTime": "1967-09-26T07:49:25.246Z",
"endDateTime": ""
}
}
],
"languageAbility": [
{
"languageCode": "FR",
"languageName": "French",
"isFavouriteLanguage": "true",
"writingProficiency": "advanced",
"readingProficiency": "advanced",
"speakingProficiency": "intermediate",
"listeningProficiency": "intermediate",
"validFor": {
"startDateTime": "2018-10-22T07:49:25.246Z",
"endDateTime": ""
}
},
{
"languageCode": "SP",
"languageName": "Spanish",
"isFavouriteLanguage": "false",
"writingProficiency": "scholar",
"readingProficiency": "scholar",
"speakingProficiency": "scholar",
"listeningProficiency": "scholar",
"validFor": {
"startDateTime": "2018-10-22T07:49:25.246Z",
"endDateTime": ""
}
}
],
"skill": [
{
© TM Forum 2019. All Rights Reserved Page 23 sur 62
Party Management API REST Specification

"skillCode": "SK001",
"skillName": "marketing",
"evaluatedLevel": "Advanced",
"comment": "Ten years experience",
"validFor": {
"startDateTime": "2018-10-22T07:49:25.246Z",
"endDateTime": ""
}
},
{
"skillCode": "SK002",
"skillName": "Project Management",
"evaluatedLevel": "newbie",
"comment": "First work experience",
"validFor": {
"startDateTime": "2018-10-22T07:49:25.246Z",
"endDateTime": ""
}
}
]
}

Organization resource
Organization represents a group of people identified by shared interests or purpose. Examples include business,
department and enterprise. Because of the complex nature of many businesses, both organizations and organization
units are represented by the same data.

Resource model

© TM Forum 2019. All Rights Reserved Page 24 sur 62

Party Management API REST Specification

© TM Forum 2019. All Rights Reserved Page 25 sur 62

Party Management API REST Specification

Lifecycle

Field descriptions

Organization fields

href A string. Hyperlink to access the organization.

id A string. Unique identifier of the organization.

existsDuring A time period. A period of time, either as a deadline (endDateTime only) a

startDateTime only, or both.

isHeadOffice A boolean. If value is true, the organization is the head office.

isLegalEntity A boolean. If value is true, the organization is a legal entity known by a national
referential.

© TM Forum 2019. All Rights Reserved Page 26 sur 62

Party Management API REST Specification

name A string. Organization name (department name for example).

nameType A string. Type of the name : Co, Inc, Ltd,….

organizationChildRelationship A list of organization child relationships (OrganizationChildRelationship [*]).

Child references of an organization in a structure of organizations.

organizationIdentification A list of organization identifications (OrganizationIdentification [*]). Represents

our registration of information used as proof of identity by an organization.

organizationParentRelationship An organization parent relationship (OrganizationParentRelationship). Parent

references of an organization in a structure of organizations.

organizationType A string. Type of Organization (company, department...).

otherName A list of other name organizations (OtherNameOrganization [*]). Keeps track of

other names, for example the old name of an organization.

status An organization state type (OrganizationStateType). Status of the organization.

tradingName A string. Name that the organization (unit) trades under.

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

creditRating A list of party credit profiles (PartyCreditProfile [*]). An individual might be

evaluated for its worthiness and this evaluation might be based on a credit rating
given by a credit agency.

externalReference A list of external references (ExternalReference [*]). External reference of the

individual or reference in other system.

partyCharacteristic A list of characteristics (Characteristic [*]). Describes a given characteristic of an

object or entity through a name/value pair.

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

taxExemptionCertificate A list of tax exemption certificates (TaxExemptionCertificate [*]). A tax

exemption certificate represents a tax exemption granted to a party (individual
or organization) by a tax jurisdiction which may be a city, state, country,... An
exemption has a certificate identifier (received from the jurisdiction that levied
the tax) and a validity period. An exemption is per tax types and determines for
each type of tax what portion of the tax is exempted (partial by percentage or
complete) via the tax definition.

© TM Forum 2019. All Rights Reserved Page 27 sur 62

Party Management API REST Specification

AttachmentRefOrValue sub-resource

An attachment by value or by reference.

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

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

href A string. URI for this Attachment.

id A string. Unique identifier for this particular attachment.

url A string. Uniform Resource Locator, is a web page address (a subset of URI).

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

href A string. URI for this Attachment.

id A string. Unique identifier for this particular attachment.

name A string. The name of the attachment.

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

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

href A string. URI for this Attachment.

id A string. Unique identifier for this particular attachment.

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

name A string. The name of the attachment.

url A string. Uniform Resource Locator, is a web page address (a subset of URI).

isRef A boolean. If true, a reference is given.

content A string with base64 encoded characters. The actual contents of the attachment object,
if embedded, encoded as base64.

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

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

Characteristic sub-resource

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

name A string. Name of the characteristic.

© TM Forum 2019. All Rights Reserved Page 28 sur 62

Party Management API REST Specification

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

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

ContactMedium sub-resource

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

characteristic A medium characteristic (MediumCharacteristic). Any additional characteristic(s) of this

contact medium.

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

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

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

ExternalReference sub-resource

External reference of the individual or reference in other system.

externalReferenceType A string. Type of the external reference.

name A string. External reference name.

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.

contactType A string. The type of contact, for example: phone number such as mobile, fixed home,
fixed office. postal address such as shipping instalation….

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.

socialNetworkId A string. Identifier as a member of a social network.

stateOrProvince A string. State or province.

street1 A string. Describes the street.

© TM Forum 2019. All Rights Reserved Page 29 sur 62

Party Management API REST Specification

street2 A string. Complementary street description.

OrganizationChildRelationship sub-resource

Child references of an organization in a structure of organizations.

organization An organization reference (OrganizationRef).

relationshipType A string. Type of the relationship. Could be juridical, hierarchical, geographical,

functional for example.

OrganizationIdentification sub-resource

Represents our registration of information used as proof of identity by an organization.

attachment An attachment ref or value (AttachmentRefOrValue). An attachment by value or by

reference.

identificationId A string. Identifier.

identificationType A string. Type of identification information used to identify the company in a country
or internationally.

issuingAuthority A string. Authority which has issued the identifier (chamber of commerce...).

issuingDate A date time (DateTime). Date at which the identifier was issued.

validFor A time period. The period for which the identification information is valid.

OrganizationParentRelationship sub-resource

Parent references of an organization in a structure of organizations.

organization An organization reference (OrganizationRef).

relationshipType A string. Type of the relationship. Could be juridical, hierarchical, geographical,

functional for example.

OtherNameOrganization sub-resource

Keeps track of other names, for example the old name of an organization.

name A string. Organization name (department name for example).

nameType A string. Co. , Inc. , Ltd. , Pty Ltd. , Plc; , Gmbh.

tradingName A string. The name that the organization trades under.

validFor A time period. A period of time, either as a deadline (endDateTime only) a

startDateTime only, or both.

© TM Forum 2019. All Rights Reserved Page 30 sur 62

Party Management API REST Specification

PartyCreditProfile sub-resource

An individual might be evaluated for its worthiness and this evaluation might be based on a credit rating given by a
credit agency.

creditAgencyName A string. Name of the credit agency giving the score.

creditAgencyType A string. Type of the credit agency giving the score.

ratingReference A string. Reference corresponding to the credit rating.

ratingScore An integer. A measure of a party’s creditworthiness calculated on the basis of a

combination of factors such as their income and credit history.

validFor A time period. A period of time, either as a deadline (endDateTime only) a

startDateTime only, or both.

Quantity sub-resource

An amount in a given unit.

amount A float. Numeric value in a given unit.

units A string. Unit.

RelatedParty sub-resource

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

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

href A string. Reference of the related entity.

id A string. Unique identifier of a related entity.

name A string. Name of the related entity.

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

role A string. Role played by the related party.

TaxDefinition sub-resource

Reference of a tax definition. A tax is levied by an authorized tax jurisdiction. There are many different types of tax
(Federal Tax levied by the US Government, State Tax levied by the State of California,…).

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

id A string. Unique identifier of the tax.

name A string. Tax name.

© TM Forum 2019. All Rights Reserved Page 31 sur 62

Party Management API REST Specification

taxType A string. Type of the tax.

TaxExemptionCertificate sub-resource

A tax exemption certificate represents a tax exemption granted to a party (individual or organization) by a tax
jurisdiction which may be a city, state, country,... An exemption has a certificate identifier (received from the
jurisdiction that levied the tax) and a validity period. An exemption is per tax types and determines for each type of
tax what portion of the tax is exempted (partial by percentage or complete) via the tax definition.

attachment An attachment ref or value (AttachmentRefOrValue). An attachment by value or by

reference.

id A string. Unique identifier of the certificate of the tax exemption.

taxDefinition A list of tax definitions (TaxDefinition [*]). Reference of a tax definition. A tax is levied
by an authorized tax jurisdiction. There are many different types of tax (Federal Tax
levied by the US Government, State Tax levied by the State of California,…).

validFor A time period. A period of time, either as a deadline (endDateTime only) a

startDateTime only, or both.

OrganizationRef relationship

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

href A string. Reference of the related entity.

id A string. Unique identifier of a related entity.

name A string. Name of the related entity.

Json representation sample

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

{
"id": "128",
"href": "[Link]
"@type": "organization",
"isLegalEntity": true,
"isHeadOffice": true,
"organizationType": "company",
"existsDuring": {
"startDateTime": "2015-10-22T08:31:52.026Z",
"endDateTime": ""
},
"tradingName": "Coffee Do Brazil Fair Trade",
"name": "",
"nameType": "inc",
"status": "validated",
"externalReference": [
{
© TM Forum 2019. All Rights Reserved Page 32 sur 62
Party Management API REST Specification

"name": "[Link]
"externalReferenceType": "internetSite"
}
],
"partyCharacteristic": [
{
"name": "number of employees",
"value": "125",
"valueType": "number"
},
{
"name": "market segment",
"value": "Food wholesale",
"valueType": "string"
}
],
"otherName": {
"nameType": "inc",
"tradingName": "General Coffee",
"name": "",
"validFor": {
"startDateTime": "2015-10-22T08:31:52.026Z",
"endDateTime": "2017-10-22T08:31:52.026Z"
}
},
"organizationIdentification": [
{
"identificationType": "commercialRegistration",
"identificationId": "12345678",
"issuingAuthority": "US Government",
"issuingDate": "2015-10-22T08:31:52.028Z",
"validFor": {
"startDateTime": "2015-10-22T08:31:52.028Z",
"endDateTime": ""
},
"attachment": [
{
"@referredType": "Attachment",
"name": "[Link]",
"description": "Electronic version of the tax exemption certificate",
"mimeType": "application/pdf",
"url": "[Link]
}
]
}
],
"taxExemptionCertificate": [
{
"id": "999",
"validFor": {
"startDateTime": "2018-10-22T08:31:52.028Z",
"endDateTime": ""
},
"taxDefinition": [
{
© TM Forum 2019. All Rights Reserved Page 33 sur 62
Party Management API REST Specification

"id": "97",
"name": "value-added tax"
}
],
"attachment": {
"id": "777",
"href": "/documentManagement/v4/attachment/777",
"attachmentType": "documentCopy",
"isRef": true,
"name": "TaxExemptionCertificate",
"description": "Electronic version of the tax exemption certificate",
}
}
],
"creditRating": [
{
"creditAgencyName": "Experian",
"creditAgencyType": "externalAgency",
"ratingReference": "ref456",
"ratingScore": 400,
"validFor": {
"startDateTime": "2018-10-22T08:31:52.028Z",
"endDateTime": ""
}
}
],
"relatedParty": [
{
"id": "54",
"href": "[Link]
"name": "Carlos Mafalda",
"role": "director",
"@referredType": "individual"
},
{
"id": "42",
"href": "[Link]
"name": "Jane Lamborgizzia",
"role": "employer",
"@referredType": "individual"
}
],
"contactMedium": [
{
"preferred": true,
“mediumType” “email”,
"validFor": {
"startDateTime": "2018-10-22T08:31:52.028Z",
"endDateTime": ""
},
"characteristic": {
"emailAddress": "[Link]@[Link]"
}
},

© TM Forum 2019. All Rights Reserved Page 34 sur 62

Party Management API REST Specification

{
"preferred": false,
“mediumType” “postalAddress”,
"validFor": {
"startDateTime": "2018-10-22T08:31:52.028Z",
"endDateTime": ""
},
"characteristic": {
"city": "Morristown",
"country": "USA",
"postcode": "07960",
"stateOrProvince": "New Jersey",
"street1": "240 Headquarters Plazza",
"street2": "East Tower 10th Floor"
}
}
],
"organizationParentRelationship": {
"relationshipType": "juridical",
"organization": {
"id": "800",
"href": "[Link]
}
},
"organizationChildRelationship": [
{
"relationshipType": "juridical",
"organization": {
"id": "149",
"href": "[Link]
}
},
{
"relationshipType": "juridical",
"organization": {
"id": "150",
"href": "[Link]
}
}
]
}

Notification Resource Models

8 notifications are defined for this API

Notifications related to Individual:

- IndividualCreateEvent
- IndividualAttributeValueChangeEvent
- IndividualStateChangeEvent
- IndividualDeleteEvent

© TM Forum 2019. All Rights Reserved Page 35 sur 62

Party Management API REST Specification

Notifications related to Organization:

- OrganizationCreateEvent
- OrganizationAttributeValueChangeEvent
- OrganizationStateChangeEvent
- OrganizationDeleteEvent

The notification structure for all notifications in this API follow the pattern depicted by the figure below.
A notification event resource (depicted by "SpecificEvent" placeholder) is a sub class of a generic Event structure
containing at least an id of the event occurrence (eventId), an event timestamp (eventTime), and the name of the
resource (eventType).

This notification structure owns an event payload structure ("SpecificEventPayload" placeholder) linked to the
resource concerned by the notification using the resource name as access field ("resourceName" placeholder).

Individual Create Event

Notification IndividualCreateEvent case for resource Individual

Json representation sample

We provide below the json representation of an example of an 'IndividualCreateEvent' notification event object.

© TM Forum 2019. All Rights Reserved Page 36 sur 62

Party Management API REST Specification

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"IndividualCreateEvent",
"event": {
"individual" :
{-- SEE Individual RESOURCE SAMPLE --}
}
}

Individual Attribute Value Change Event

Notification IndividualAttributeValueChangeEvent case for resource Individual.

Json representation sample

We provide below the json representation of an example of an 'IndividualAttributeValueChangeEvent' notification

event object.

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"IndividualAttributeValueChangeEvent",
"event": {
"individual" :
{-- SEE Individual RESOURCE SAMPLE --}
}
}

Individual State Change Event

Notification IndividualStateChangeEvent case for resource Individual.

Json representation sample

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

object.

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"IndividualStateChangeEvent",
"event": {
"individual" :
{-- SEE Individual RESOURCE SAMPLE --}
}
}

Individual Delete Event

Notification IndividualDeleteEvent case for resource Individual.
© TM Forum 2019. All Rights Reserved Page 37 sur 62
Party Management API REST Specification

Json representation sample

We provide below the json representation of an example of an 'IndividualDeleteEvent' notification event object.

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"IndividualDeleteEvent",
"event": {
"individual" :
{-- SEE Individual RESOURCE SAMPLE --}
}
}

Organization Create Event

Notification OrganizationCreateEvent case for resource Organization.

Json representation sample

We provide below the json representation of an example of an 'OrganizationCreateEvent' notification event object.

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"OrganizationCreateEvent",
"event": {
"organization" :
{-- SEE Organization RESOURCE SAMPLE --}
}
}

Organization Attribute Value Change Event

Notification OrganizationAttributeValueChangeEvent case for resource Organization.

Json representation sample

We provide below the json representation of an example of an 'OrganizationAttributeValueChangeEvent' notification

event object.

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"OrganizationAttributeValueChangeEvent",
"event": {
"organization" :
{-- SEE Organization RESOURCE SAMPLE --}
}
}

© TM Forum 2019. All Rights Reserved Page 38 sur 62

Party Management API REST Specification

Organization State Change Event

Notification OrganizationStateChangeEvent case for resource Organization.

Json representation sample

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

object.

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"OrganizationStateChangeEvent",
"event": {
"organization" :
{-- SEE Organization RESOURCE SAMPLE --}
}
}

Organization Delete Event

Notification OrganizationDeleteEvent case for resource Organization.

Json representation sample

We provide below the json representation of an example of an ‘OrganizationDeleteEvent’ notification event object.

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"OrganizationDeleteEvent",
"event": {
"organization" :
{-- SEE Organization RESOURCE SAMPLE --}
}
}

© TM Forum 2019. All Rights Reserved Page 39 sur 62

Party Management API REST Specification

API OPERATIONS
Document only allows following operations:

Operation on Entities Uniform API Operation Description

Query Entities GET individual GET must be used to retrieve a

representation of a resource.
GET organization

Create Entity POST individual POST must be used to create a

new resource
POST organization

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

update a resource
PATCH organization

Remove an Entity DELETE individual DELETE must be used to

remove a resource
DELETE organization

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

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

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

Notifications are also described in a subsequent section.

© TM Forum 2019. All Rights Reserved Page 40 sur 62

Party Management API REST Specification

Operations on Individual

List individuals

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

This operation list individual 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 Individual resources. Retrieving all individuals with validated status and
credit store equal to 700. The result items are shrinked to show only the id, the family name and the given name.

Request

GET /serverRoot/tmf-
api/party/v4/individual?fields=id,familyName,givenName&status=validated&[Link]=700
Accept: application/json

Response

200

[
{
"id": "42",
"@type": "individual",
"givenName": "Jane",
"familyName": "Lamborgizzia"
},
{
"id": "52",
"@type": "individual",
"givenName": "Paul",
"familyName": "Newman"
}
]

© TM Forum 2019. All Rights Reserved Page 41 sur 62

Party Management API REST Specification

Retrieve individual

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

This operation retrieves an individual 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 a sample of a request for retrieving an individual resource based on its id.

Request

GET /serverRoot/tmf-api/party/v4/individual/42
Accept: application/json

Response

200

{
"id": "42",
"href": "[Link]
"@type": "individual",
"gender": "female",
"placeOfBirth": "",
"countryOfBirth": "United States",
"nationality": "American",
"maritalStatus": "married",
"birthDate": "1967-09-26T05:00:00.246Z",
"deathDate": "",
"title": "",
"aristocraticTitle": "",
"generation": "",
"givenName": "Jane",
"preferredGivenName": "Lamborgizzia",
"familyNamePrefix": "",
"familyName": "Lamborgizzia",
"legalName": "Smith",
"middleName": "JL",
"fullName": "Jane Smith ep Lamborgizzia",
"formattedName": "Jane Smith ep Lamborgizzia",
"location": "",
"status": "validated",
"externalReference": [
{
"name": "[Link]
© TM Forum 2019. All Rights Reserved Page 42 sur 62
Party Management API REST Specification

"externalReferenceType": "facebookId"
},
{
"name": "[Link]
"externalReferenceType": "googleId"
}
],
"partyCharacteristic": [
{
"name": "hobby",
"value": "Modern Jazz",
"valueType": "string"
},
{
"name": "hobby",
"value": "Cinema",
"valueType": "string"
},
{
"name": "childrenNumber",
"value": "1",
"valueType": "number"
}
],
"otherName": [
{
"title": "",
"aristocraticTitle": "",
"generation": "",
"givenName": "Jane",
"preferredGivenName": "",
"familyNamePrefix": "",
"familyName": "Smith",
"legalName": "",
"middleName": "",
"fullName": "",
"formattedName": "",
"validFor": {
"startDateTime": "1967-09-26T00:00:00.246Z",
"endDateTime": "2015-06-15T00:00:00.246Z"
}
}
],
"individualIdentification": [
{
"identificationType": "passport",
"identificationId": "51DD1234",
"issuingAuthority": "US Government",
"issuingDate": "2017-10-22T07:49:25.246Z",
"validFor": {
"startDateTime": "2017-10-22T07:49:25.246Z",
"endDateTime": "2027-10-21T07:49:25.246Z"
},
"attachment": [
{
© TM Forum 2019. All Rights Reserved Page 43 sur 62
Party Management API REST Specification

"id": "321",
"href": "/documentManagement/v4/attachment/321",
"attachmentType": "passportCopy",
"isRef": true,
"name": "PassportCopy",
"description": "Scanned copy of the passport",
}
]
}
],
"taxExemptionCertificate": [
{
"id": "555",
"validFor": {
"startDateTime": "2018-10-22T07:49:25.246Z",
"endDateTime": ""
},
"taxDefinition": [
{
"id": "96",
"name": "value-added tax",
"taxType": "federalVat"
}
],
"attachment": {
"@referredType": "Attachment",
"name": "[Link]",
"description": "Electronic version of the tax exemption certificate",
"mimeType": "application/pdf",
"url": "[Link]
}
}
],
"creditRating": [
{
"creditAgencyName": "Experian",
"creditAgencyType": "externalAgency",
"ratingReference": "ref123",
"ratingScore": 680,
"validFor": {
"startDateTime": "2018-10-22T07:49:25.246Z",
"endDateTime": ""
}
}
],
"relatedParty": [
{
"id": "128",
"href": "[Link]
"role": "employee",
"name": "Coffee Do Brazil Fair Trade Marketing Department",
"@referredType": "organization"
}
],
"contactMedium": [
© TM Forum 2019. All Rights Reserved Page 44 sur 62
Party Management API REST Specification

{
"preferred": true,
" mediumType": "email",
"validFor": {
"startDateTime": "2017-03-15T07:49:25.246Z",
"endDateTime": ""
},
"characteristic": {
"emailAddress": "[Link]@[Link]"
}
},
{
"preferred": false,
" mediumType": "postalAddress",
"validFor": {
"startDateTime": "2017-03-15T07:49:25.246Z",
"endDateTime": ""
},
"characteristic": {
"city": "Morristown",
"country": "USA",
"postcode": "07960",
"stateOrProvince": "New Jersey",
"street1": "240 Headquarters Plazza",
"street2": "East Tower - 10th Floor"
}
}
],
"disability": [
{
"disabilityCode": "BLD",
"disabilityName": "Blind",
"validFor": {
"startDateTime": "1967-09-26T07:49:25.246Z",
"endDateTime": ""
}
}
],
"languageAbility": [
{
"languageCode": "FR",
"languageName": "French",
"isFavouriteLanguage": "true",
"writingProficiency": "advanced",
"readingProficiency": "advanced",
"speakingProficiency": "intermediate",
"listeningProficiency": "intermediate",
"validFor": {
"startDateTime": "2018-10-22T07:49:25.246Z",
"endDateTime": ""
}
},
{
"languageCode": "SP",
"languageName": "Spanish",
© TM Forum 2019. All Rights Reserved Page 45 sur 62
Party Management API REST Specification

"isFavouriteLanguage": "false",
"writingProficiency": "scholar",
"readingProficiency": "scholar",
"speakingProficiency": "scholar",
"listeningProficiency": "scholar",
"validFor": {
"startDateTime": "2018-10-22T07:49:25.246Z",
"endDateTime": ""
}
}
],
"skill": [
{
"skillCode": "SK001",
"skillName": "marketing",
"evaluatedLevel": "Advanced",
"comment": "Ten years experience",
"validFor": {
"startDateTime": "2018-10-22T07:49:25.246Z",
"endDateTime": ""
}
},
{
"skillCode": "SK002",
"skillName": "Project Management",
"evaluatedLevel": "newbie",
"comment": "First work experience",
"validFor": {
"startDateTime": "2018-10-22T07:49:25.246Z",
"endDateTime": ""
}
}
]
}

© TM Forum 2019. All Rights Reserved Page 46 sur 62

Party Management API REST Specification

Create individual

POST /individual
Description

This operation creates an individual entity.

Mandatory and Non Mandatory Attributes

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

givenName
familyName

Non Mandatory Attributes Rule

aristocraticTitle
birthDate
countryOfBirth
deathDate
disability
familyNamePrefix
formattedName
fullName
gender
generation
individualIdentification
languageAbility
legalName
location
maritalStatus
middleName
nationality
otherName
placeOfBirth
preferredGivenName
skill
status
title
contactMedium
creditRating
externalReference
partyCharacteristic
relatedParty
taxExemptionCertificate
© TM Forum 2019. All Rights Reserved Page 47 sur 62
Party Management API REST Specification

Usage Samples

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

Request

POST /serverRoot/tmf-api/party/v4/individual
Content-Type: application/json
{
"givenName": "Jane",
"familyName": "Lamborgizzia"
}

Response

201

{
"id": "42",
"href": "[Link]
"@type": "individual",
"givenName": "Jane",
"familyName": "Lamborgizzia",
"status": "initialized"
}

Patch individual

PATCH /individual/{id}
Description

This operation allows partial updates of an individual 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.

© TM Forum 2019. All Rights Reserved Page 48 sur 62

Party Management API REST Specification

Patchable Attributes Rule

aristocraticTitle
birthDate
countryOfBirth
deathDate
disability
familyName
familyNamePrefix
formattedName
fullName
gender
generation
givenName
individualIdentification
languageAbility
legalName
location
maritalStatus
middleName
nationality
otherName
placeOfBirth
preferredGivenName
skill
status
title
contactMedium
creditRating
externalReference
partyCharacteristic
relatedParty
taxExemptionCertificate

Non Patchable Attributes Rule

id
href

Usage Samples

Here's an example of a request for patching an individual resource with change on following attribute (using json-
patch): maritalStatus

Request

© TM Forum 2019. All Rights Reserved Page 49 sur 62

Party Management API REST Specification

PATCH /serverRoot/tmf-api/party/v4/individual/42
Content-Type: application/merge-patch+json
{
"maritalStatus": "divorced"
}

Response

200

{ Similar JSON as in GET response with marital status changed }

Delete individual

DELETE /individual/{id}
Description

This operation deletes an individual entity.

Usage Samples

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

Request

DELETE /serverRoot/tmf-api/party/v4/individual/42

Response

204

Operations on Organization

List organizations

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

This operation list organization entities.

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

© TM Forum 2019. All Rights Reserved Page 50 sur 62

Party Management API REST Specification

Usage Samples

Here's an example of a request for retrieving organization resources. Retrieving all organizations with validated status
and with organization parent relationship id equal to 128. The result items are shrinked to show only the id, the
trading name and the name (fields=id,tradingName,name).

Request

GET /serverRoot/tmf-
api/party/v4/organization?fields=id,tradingName,name&status=validated&[Link]=128
Accept: application/json

Response

200

[
{
"id": "129",
"@type": "organization",
"tradingName": "Coffee Do Brazil Fair Trade",
"name": "Marketing Department"
},
{
"id": "130",
"@type": "organization",
"tradingName": "Coffee Do Brazil Fair Trade",
"name": "Operations Department"
}
]

Retrieve organization

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

This operation retrieves an organization 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 a sample of a request for retrieving an organization resource based on its id.

© TM Forum 2019. All Rights Reserved Page 51 sur 62

Party Management API REST Specification

Request

GET /serverRoot/tmf-api/party/v4/organization/128
Accept: application/json

Response

200

{
"id": "128",
"href": "[Link]
"@type": "organization",
"isLegalEntity": true,
"isHeadOffice": true,
"organizationType": "company",
"existsDuring": {
"startDateTime": "2015-10-22T08:31:52.026Z",
"endDateTime": ""
},
"tradingName": "Coffee Do Brazil Fair Trade",
"name": "",
"nameType": "inc",
"status": "validated",
"externalReference": [
{
"name": "[Link]
"externalReferenceType": "internetSite"
}
],
"partyCharacteristic": [
{
"name": "number of employees",
"value": "125",
"valueType": "number"
},
{
"name": "market segment",
"value": "Food wholesale",
"valueType": "string"
}
],
"otherName": {
"nameType": "inc",
"tradingName": "General Coffee",
"name": "",
"validFor": {
"startDateTime": "2015-10-22T08:31:52.026Z",
"endDateTime": "2017-10-22T08:31:52.026Z"
}
},
© TM Forum 2019. All Rights Reserved Page 52 sur 62
Party Management API REST Specification

"organizationIdentification": [
{
"identificationType": "commercialRegistration",
"identificationId": "12345678",
"issuingAuthority": "US Government",
"issuingDate": "2015-10-22T08:31:52.028Z",
"validFor": {
"startDateTime": "2015-10-22T08:31:52.028Z",
"endDateTime": ""
},
"attachment": [
{
"id": "421",
"href": "[Link]
"attachmentType": "documentCopy",
"isRef": true,
"name": "[Link]",
"description": "Scanned copy of the registration certificate" }
]
}
],
"taxExemptionCertificate": [
{
"id": "999",
"validFor": {
"startDateTime": "2018-10-22T08:31:52.028Z",
"endDateTime": ""
},
"taxDefinition": [
{
"id": "97",
"name": "value-added tax"
}
],
"attachment": {
"id": "777",
"href": "/documentManagement/v4/attachment/777",
"attachmentType": "documentCopy",
"isRef": true,
"name": "[Link]",
"description": "Electronic version of the tax exemption certificate”
}
}
],
"creditRating": [
{
"creditAgencyName": "Experian",
"creditAgencyType": "externalAgency",
"ratingReference": "ref456",
"ratingScore": 400,
"validFor": {
"startDateTime": "2018-10-22T08:31:52.028Z",
"endDateTime": ""
}
}
© TM Forum 2019. All Rights Reserved Page 53 sur 62
Party Management API REST Specification

],
"relatedParty": [
{
"id": "54",
"href": "[Link]
"name": "Carlos Mafalda",
"role": "director",
"@referredType": "individual"
},
{
"id": "42",
"href": "[Link]
"name": "Jane Lamborgizzia",
"role": "employer",
"@referredType": "individual"
}
],
"contactMedium": [
{
"preferred": true,
"mediumType": "email",
"validFor": {
"startDateTime": "2018-10-22T08:31:52.028Z",
"endDateTime": ""
},
"characteristic": {
"emailAddress": "[Link]@[Link]"
}
},
{
"preferred": false,
" mediumType": "postalAddress",
"validFor": {
"startDateTime": "2018-10-22T08:31:52.028Z",
"endDateTime": ""
},
"characteristic": {
"city": "Morristown",
"country": "USA",
"postcode": "07960",
"stateOrProvince": "New Jersey",
"street1": "240 Headquarters Plazza",
"street2": "East Tower 10th Floor"
}
}
],
"organizationParentRelationship": {
"relationshipType": "juridical",
"organization": {
"id": "800",
"href": "[Link]
}
},
"organizationChildRelationship": [
{
© TM Forum 2019. All Rights Reserved Page 54 sur 62
Party Management API REST Specification

"relationshipType": "juridical",
"organization": {
"id": "149",
"href": "[Link]
}
},
{
"relationshipType": "juridical",
"organization": {
"id": "150",
"href": "[Link]
}
}
]
}

Create organization

POST /organization
Description

This operation creates an organization entity.

Mandatory and Non Mandatory Attributes

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

tradingName

Non Mandatory Attributes Rule

existsDuring
isHeadOffice
isLegalEntity
name
nameType
organizationChildRelationship
organizationIdentification
organizationParentRelationship
organizationType
otherName
status
contactMedium
creditRating
externalReference

© TM Forum 2019. All Rights Reserved Page 55 sur 62

Party Management API REST Specification

partyCharacteristic
relatedParty
taxExemptionCertificate

Usage Samples

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

Request

POST /serverRoot/tmf-api/party/v4/organization
Content-Type: application/json
{
"tradingName": "Coffee Do Brazil Fair Trade"
}

Response

201

{
"id": "128",
"href": "[Link]
"@type": "organization",
"tradingName": "Coffee Do Brazil Fair Trade",
"status": "initialized"
}

Patch organization

PATCH /organization/{id}
Description

This operation allows partial updates of an organization 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 2019. All Rights Reserved Page 56 sur 62

Party 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

existsDuring
isHeadOffice
isLegalEntity
name
nameType
organizationChildRelationship
organizationIdentification
organizationParentRelationship
organizationType
otherName
status
tradingName
contactMedium
creditRating
externalReference
partyCharacteristic
relatedParty
taxExemptionCertificate

Non Patchable Attributes Rule

id
href

Usage Samples

Here's an example of a request for patching an organization resource with change on following attribute (using
json-patch): isLegalEntity

Request

PATCH /serverRoot/tmf-api/party/v4/organization/42
Content-Type: application/merge-patch+json

{
"isLegalEntity": true
}

Response

200

© TM Forum 2019. All Rights Reserved Page 57 sur 62

Party Management API REST Specification

{ Similar JSON as in GET response with isLegalEntity changed }

Delete organization

DELETE /organization/{id}
Description

This operation deletes an organization entity.

Usage Samples

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

Request

DELETE {apiRoot}/organization/128

Response

204

© TM Forum 2019. All Rights Reserved Page 58 sur 62

Party Management API REST Specification

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

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

Register listener
POST /hub
Description

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

Behavior

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

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

Usage Samples

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

Request

POST /api/hub
Accept: application/json

{"callback": "[Link]

Response

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

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

© TM Forum 2019. All Rights Reserved Page 59 sur 62

Party Management API REST Specification

Unregister listener
DELETE /hub/{id}
Description

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

Behavior

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

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

Usage Samples

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

Request

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

Response

204

Publish Event to listener

POST /client/listener
Description

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

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

Behavior

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

Usage Samples

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

© TM Forum 2019. All Rights Reserved Page 60 sur 62

Party Management API REST Specification

Request

POST /client/listener
Accept: application/json

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

Response

201

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

© TM Forum 2019. All Rights Reserved Page 61 sur 62

Party Management API REST Specification

Acknowledgements
VERSION History
Release Date Release led by: Description
Number

Release 1.0.0 09/06/2017 Sophie Bouleau First Release of the Document.

Orange
[Link]@orange.
com

Release 4.0.0 23/06/2019 Sophie Bouleau Schema-driven API with

Orange polymorphism pattern
[Link]@orange.
com Following Jira have been integrated:

• AP-1016
• AP-1017
• AP-1195
• AP-1282

Note: the version 4.0 is assigned to all

the APIs delivered in the release 19.0

Release History
Release Date Release led by: Description
Number

Release 14.5 09/06/2017 Sophie Bouleau Version 1.0 of the API REST
Orange
[Link]@[Link]

Release 19.0 23/06/2019 Sophie Bouleau Version 4.0 of the API REST
Orange
Note: the version 4.0 is assigned to all
[Link]@[Link]
the APIs delivered in the release 19.0

© TM Forum 2019. All Rights Reserved Page 62 sur 62