Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Scroll Ignore

Hide If
special@authenticated
Note
titleTo access this API specification you wil need to be logged in

To login with your TM Forum account please click on the Login button below

Button Hyperlink
titleLogin
typeprimary
urlhttps://projects.tmforum.org/wiki/login.action?os_destination=%2Fdisplay%2FAPI%2FOpen%2BAPI%2BTable

Don't have an account? You can register by clicking here:

Button Hyperlink
titleRegister
typeprimary
urlhttps://www.tmforum.org/user-registration/
targettrue

Show If
special@authenticated

Managed Entity and Task Resource Models

Customer Resource

The customer resource is the main entity to access to customer information.
This entity contains mainly financial information about the customer: touch point to customer account(s) and credit profiles.
Below is a representation of the Customer resource in JSON format.

{
"id": "c1234",
"href": "http://serverlocation:port/customerManagement/customer/c1234",
"name": "DisplayName",
"status": "Active",
"description": "Description string",
"validFor": {
"startDateTime": "2013-06-19T04:00:00.0Z",
"endDateTime": "2013-04-19T20:42:23.0Z"
},
"customerRank": "3",
"relatedParty": {
"id": "1",
"href": "http://serverlocation:port/partyManagement/individual/1",
"role": "customer",
"name": "John Doe"
},
"characteristic": [
{
"name": "characteristicname1",
"value": "characteristicvalue1"
},
{
"name": "characteristicname2",
"value": "characteristicvalue2"
}
],
"contactMedium": [
{
"type": "Email",
"validFor": {
"startDateTime": "2013-04-19T20:42:23.0Z"
},
"medium": {
"emailAddress": "[email protected]"
}
},
{
"type": "PostalAddress",
"validFor": {
"startDateTime": "2013-04-19T20:42:23.0Z"
},
"medium": {
"city": "Wien",
"country": "Austria",
"postcode": "1020",
"stateOrProvince": "Quebec",
"street1": "Lassallestrasse7",
"street2": ""
}
},
{
"type": "TelephoneNumber",
"validFor": {
"startDateTime": "2013-04-19T20:42:23.0Z"
},
"medium": {
"type": "mobile",
"number": "+436641234567"
}
},
{
"preferred": true,
"type": "TelephoneNumber",
"validFor": {
"startDateTime": "2013-04-19T20:42:23.0Z"
},
"medium": {
"type": "business",
"number": "+436641234567"
}
}
],
"customerAccount": [
{
"id": "1",
"href": "http://serverlocation:port/customerManagement/customerAccount/1",
"name": "CustomerAccount1",
"description": "CustomerAccountDesc1",
"status": "Active"
},
{
"id": "2",
"href": "http://serverlocation:port/customerManagement/customerAccount/2",
"name": "CustomerAccount2",
"description": "CustomerAccountDesc2",
"status": "Active"
}
],
"customerCreditProfile": [
{
"creditProfileDate": "2013-04-19T20:42:23.0Z",
"validFor": {
"startDateTime": "2013-04-19T20:42:23.0Z",
"endDateTime": "2013-06-19T04:00:00.0Z"
},
"creditRiskRating": 1,
"creditScore": 1
},
{
"creditProfileDate": "2013-04-19T20:42:23.0Z",
"validFor": {
"startDateTime": "2013-04-19T20:42:23.0Z",
"endDateTime": "2013-06-19T04:00:00.0Z"
},
"creditRiskRating": 1,
"creditScore": 1
}
],
"paymentMean": [
{
"id": "45",
"href": "http://serverlocation:port/customerManagement/paymentMean/45",
"name": "my favourite payment mean"
},
{
"id": "64",
"href": "http://serverlocation:port/customerManagement/paymentMean/64",
"name": "my credit card payment mean"
}
]
}


Field Descriptions :
Characteristic: describes the characteristics of the individual or the organization such as individual hobbies, center of interests.

Field

Description

name

Name of the characteristic

value

Value of the characteristic


ContactMedium: indicates the contact medium that could be used to contact the customer.

Field

Description

preferred

If true, indicates that is the preferred contact medium

type

Email address, telephone number, postal address

validFor

The time period that the contact medium is valid for


Customer: A person or organization that buys products and services from the enterprise or receives free offers or services. This is modeled as a Party playing the role of Customer. A Customer is a type of PartyRole.

Field

Description

customerRank

Relative importance of this customer compared to other customers

description

Detailed description of the customer

href

Unique reference of the customer

id

Unique identifier of the customer

name

Displayable name

status

Used to track the lifecycle status, e.g. existing, prospective or former customers

validFor

To manage startDate and endDate of customer states


CustomerAccount: Is used to represent an account for the customer to manage the billing aspects.

Field

Description

description

Detailed description of the customer account

href

Unique reference of the customer account

id

Unique identifier of the customer account

name

Name of the customer account

status

The condition of the account, such as due, paid, in arrears, in collection


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

Field

Description

creditProfileDate

The date the profile was established.

creditRiskRating

This is an integer whose value is used to rate the risk

creditScore

A measure of a person's or organization's creditworthiness calculated on the basis of a combination of factors such as their income and credit history.

validFor

The period for which the profile is valid.


Medium: describes the contact medium that could be used to contact the customer

Field

Description

city

City

country

Country

emailAddress

Full email address in standard format

type

Type of medium (fax, mobile phone…)

number

Phone number

postcode

Postcode

stateOrProvice

State or province

street1

Describes the street

street2

Complementary street description


PaymentMean: defines a specific mean of payment (e.g. direct debit with all details associated).

Field

Description

id

Unique identifier of the payment mean

href

Reference of the payment mean

name

Name of the payment mean



RelatedParty: Defines party or partyRole linked to a specific entity.

Field

Description

id

Unique identifier of related party

href

Reference of the relatedParty, could be a party reference or a partyRole reference

role

Role of the related party

name

Name of the related party

validFor

The period for which the related party is valid


UML Model:
Image Modified

Customer Account Resource

The customer account resource is used to represent an account for the customer to manage billing aspects.
Customer account can contain customer tax exemption, related accounts, contact information, customer relation, account balances and payment plans.
Below is a representation of the Customer Account resource in JSON format.

{
"id": "ca1234",
"href": "http://serverlocation:port/customerManagement/customerAccount/ca1234",
"lastModified": "2014-09-24T18:27:37.059899Z",
"name": "sampleaccount",
"accountType": "Residential",
"status": "in progress",
"description": "Description string",
"creditLimit": 1212121,
"pin": "pin0",
"receivableBalance": 52.3,
"customerAccountTaxExemption": [
{
"issuingJurisdiction": "SampleJurisdiction",
"certificateNumber": "CATaxExemption1",
"reason": "Reason",
"validFor": {
"startDateTime": "2013-04-19T16:42:23.0Z",
"endDateTime": "2013-06-19T00:00:00.0Z"
}
},
{
"issuingJurisdiction": "SampleJurisdiction",
"certificateNumber": "CATaxExemption1",
"reason": "Reason",
"validFor": {
"startDateTime": "2013-04-19T16:42:23.0Z",
"endDateTime": "2013-06-19T00:00:00.0Z"
}
}
],
"customerAccountRelationship": [
{
"relationshipType": "Type xx",
"validFor": {
"startDateTime": "2013-04-19T16:42:23.0Z",
"endDateTime": "2013-06-19T00:00:00.0Z"
},
"customerAccount": [
{
"id": "1",
"href": "http://serverlocation:port/customerManagement/customerAccount/1",
"name": "CustomerAccount1",
"description": "CustomerAccountDesc1"
}
]
}
],
"contact": [
{
"contactType": "primary",
"validFor": {
"startDateTime": "2013-04-19T16:42:23.0Z",
"endDateTime": "2013-06-19T00:00:00.0Z"
},
"contactName": "DisplayName",
"partyRoleType": "CustomerAccountRepresentative",
"contactMedium": [
{
"type": "Email",
"medium": {
"emailAddress": "[email protected]"
}
},
{
"type": "PostalAddress",
"medium": {
"city": "Wien",
"country": "Austria",
"postcode": "1020",
"stateOrProvince": "Quebec",
"street1": "Lassallestrasse7"
}
},
{
"type": "TelephoneNumber",
"medium": {
"type": "mobile",
"number": "+436641234567"
}
},
{
"preferred": true,
"type": "TelephoneNumber",
"medium": {
"type": "business",
"number": "+436641234567"
}
}
],
"relatedParty": {
"id": "1",
"href": "http://serverlocation:port/partyManagement/individual/1",
"role": "customer"
}
}
],
"customer": {
"id": "1",
"href": "http://serverlocation:port/customerManagement/customer/1",
"name": "Customer1",
"description": "CustomerDesc1"
},
"customerAccountBalance": [
{
"type": "ReceivableBalance",
"amount": 52.3,
"validFor": {
"startDateTime": "2013-04-19T16:42:23.0Z",
"endDateTime": "2013-06-19T00:00:00.0Z"
},
"status": "Due"
},
{
"type": "DepositBalance",
"amount": 52.3,
"validFor": {
"startDateTime": "2013-04-19T16:42:23.0Z",
"endDateTime": "2013-06-19T00:00:00.0Z"
},
"status": "Paid"
}
],
"paymentPlan": [
{
"status": "Effective",
"type": "Type1",
"priority": 1,
"amount": 15.3,
"paymentFrequency": "monthly",
"numberOfPayments": 4,
"validFor": {
"startDateTime": "2013-04-19T16:42:23.0Z",
"endDateTime": "2013-06-19T00:00:00.0Z"
}
},
{
"status": "Ineffective",
"type": "Type2",
"priority": 2,
"amount": 20,
"paymentFrequency": "monthly",
"numberOfPayments": 2,
"validFor": {
"startDateTime": "2013-04-19T16:42:23.0Z",
"endDateTime": "2013-06-19T00:00:00.0Z"
},
"paymentMean": {
"id": "70",
"href": "http://serverlocation:port/customerManagement/paymentMean/70"
}
}
]
}


Field Descriptions :
Contact: An individual or an organization used as a contact point for a CustomerAccount and accessed via some contact medium.

Field

Description

contactType

Type of contact: Primary, secondary…

validFor

Validity period of that contact

contactName

A displayable name for the contact

partyRoleType

Identifies what kind of partyRole type is linked to the contact (for instance customer account manager)


ContactMedium: indicates the contact medium that could be used to contact the customer.

Field

Description

preferred

If true, indicates that is the preferred contact medium

type

Email address, telephone number, postal address

validFor

The time period that the contact medium is valid for


Customer: A person or organization that buys products and services from the enterprise or receives free offers or services. This is modeled as a Party playing the role of Customer. A Customer is a type of PartyRole.

Field

Description

customerRank

Relative importance of this customer compared to other customers

description

Detailed description of the customer

href

Unique reference of the customer

id

Unique identifier of the customer

name

Displayable name

status

Used to track the lifecycle status, e.g. existing, prospective or former customers

validFor

To manage startDate and endDate of customer states


CustomerAccount: Is used to represent an account for the customer to manage the billing aspects.

Field

Description

accountType

A categorization of an account, such as individual, joint, and so forth, whose instances share some of the same characteristics.

creditLimit

The maximum amount of money that may be charged on an account.

description

Detailed description of the customer account

href

Unique reference of the customer account

id

Unique identifier of the customer account

lastModified

Date of last modification of customer account

name

Name of the customer account

pin

A multidigit personal identification number that is used

receivableBalance

Overall receivable balance for the customer account

status

The condition of the account, such as due, paid, in arrears, in collection


CustomerAccountRelationship: Significant connection between customer accounts

Field

Description

relationshipType

Type of relationship

validFor

Validity period of that relationship


CustomerAccountTaxExemption: Proof of freedom from taxes imposed by a taxing jurisdiction.

Field

Description

certificateNumber

Identifier of a document that shows proof of exemption from taxes for the taxing jurisdiction

issuingJuridiction

Name of the taxing jurisdiction for which taxes are exempt.

reason

Reason of the tax exemption

validFor

Period for which the exemption is valid


Medium: describes the contact medium that could be used to contact the customer

Field

Description

city

City

country

Country

emailAddress

Full email address in standard format

type

Type of medium (fax, mobile phone…)

number

Phone number

postcode

Postcode

stateOrProvice

State or province

street1

Describes the street

street2

Complementary street description


PaymentMean: defines a specific mean of payment (e.g. direct debit with all details associated).

Field

Description

id

Unique identifier of the payment mean

href

Reference of the payment mean

name

Name of the payment mean


PaymentPlan: Defines a plan for payment (when a customer wants to spread his payments)

Field

Description

amount

Amount paid.

numberOfPayments

Number of payments used to spread the global payment.

paymentFrequency

Monthly, Bimonthly, …

priority

Priority of the payment plan

status

Status of the payment plan (effective, ineffective).

type

Type of payment plan

validFor

Validity period of the payment plan.


RelatedParty: Defines party or partyRole linked to a specific entity.

Field

Description

id

Unique identifier of related party

href

Reference of the relatedParty, could be a party reference or a partyRole reference

role

Role of the related party

name

Name of the related party

validFor

The period for which the related party is valid


CustomerAccountBalance: Balances linked to the customer account.

Field

Description

amount

Balance amount

status

Due, Paid, …

type

Deposit balance, Disputed balance, Loyalty balance, Receivable balance

validFor

Balance validity period


NOTE:

  • Customer credit profile is not a resource anymore, embedded in customer.
  • The customer tax exemption is not a resource anymore, embedded in customerAccount.
  • Each Payment plan has to be linked to a payment method -> paymentMean


UML model:
Image Modified

Payment Mean Resource

The payment mean resource is used to define a specific mean of payment (e.g. direct debit with all associated details).
Below are representations of the PaymentMean resource in JSON format.

{
"id": "45",
"href": "http://serverlocation:port/customerManagement/paymentMean/45",
"name": "My favourite payment mean",
"validFor": {
"startDateTime": "2013-04-19T16:42:23.0Z",
"endDateTime": "2013-06-19T00:00:00.0Z"
},
"type": "BankAccountDebit",
"bankAccount": {
"BIC": "PSSTFRPPPAR",
"domiciliation": "LaBanquePostale–75900ParixCedex15",
"IBAN": "FR4620061009010835927F33098",
"accountHolder": "Mr.GustaveFlaubert"
},
"relatedParty": {
"id": "1",
"href": "http://serverlocation:port/partyManagement/individual/1",
"role": "customer",
"name": "Gustave Flaubert"
}
}

{
"id": "70",
"href": "http://serverlocation:port/customerManagement/paymentMean/70",
"name": "My credit card payment mean",
"validFor": {
"startDateTime": "2013-04-19T16:42:23.0Z"
},
"type": "CreditCard",
"creditCard": {
"creditCardHolder": "Mr.GustaveFlaubert",
"type": "Visa",
"number": "xxxxx1234",
"expirationDate": "2014-09-30T00:00:00.0Z"
},
"relatedParty": {
"id": "1",
"href": "http://serverlocation:port/partyManagement/individual/1",
"role": "customer",
"name": "Gustave Flaubert"
}
}


Field Descriptions :
BankAccount: describes the information of a bank account.

Field

Description

iban

Is an international format to describe a bank account

bic

Identifier of the bank according to its international code

domiciliation

Address of the bank agency which manages the bank account

accountHolder

 


CreditCard: describes the credit card information.

Field

Description

creditCardHolder

Name of the credit card holder

type

Credit card type (Mastercard, Visa,…)

number

Card number

expirationDate

Expiration date of the card


PaymentMean: defines a specific mean of payment (e.g. direct debit with all details associated).

Field

Description

id

Unique identifier for the payment mean

href

Reference of the payment mean

name

Name of the payment mean

validFor

Payment mean validity period

type

Type of the payment mean


RelatedParty: Defines party or partyRole linked to a specific entity.

Field

Description

id

Unique identifier of related party

href

Reference of the relatedParty, could be a party reference or a partyRole reference

role

Role of the related party

name

Name of the related party

validFor

The period for which the related party is valid


UML model:
Image Modified

© TM Forum 2015. All Rights Reserved.