GET /customerManagement/customer/{ID}

Note that collections can be retrieved via GET /customerManagement/customer without ID. In that case an array of customers is returned. 
Description:

• This operation retrieves collection of customers (array) or only one customer when specifying the ID in the URI.
• Filtering is enabled on all attributes
• Attribute selection is enabled
• The resource represents one managed entity or a collection depending on the query pattern
• The identifier is a string that can consist of numbers, not necessarily alphanumeric

Behavior:

• Return Status Codes
  • 200 OK – the request was successful (includes criteria where the filtering condition didn't match to any records)
  • 400 Bad Request – Error
  • 404 If no record was found for the supplied criteria

  • 500 The server encountered an unexpected condition which prevented it from fulfilling the request

    REQUEST

    GET /customerManagement/customer/{ID}/?{fields=attributes}&{filtering expression} Accept: application/json

    RESPONSE

    Status:200 Content-Type: application/json { "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": "

• • abc@tmforum.com" } }, { "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", "accountStatus": "Active" }, { "id": "2", "href": "http://serverlocation:port/customerManagement/customerAccount/2", "name": "CustomerAccount2", "description": "CustomerAccountDesc2", "accountStatus": "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" } ] }

    
    If we need to retrieve only limited set of attributes and also filter the records based on certain filters then the below query pattern:

    REQUEST

    GET /customerManagement/customer/c1234?fields=id,name,status,customerAccount Accept: application/json

    RESPONSE

    Status: 200 Content-Type: application/json { "id": "c1234", "href": "http://serverlocation:port/customerManagement/customer/c1234", "name": "DisplayName", "status": "Active", "customerAccount": [ { "id": "1", "href": "http://serverlocation:port/customerManagement/customerAccount/1", "name": "CustomerAccount1", "description": "CustomerAccountDesc1", "accountStatus": "Active" }, { "id": "2", "href": "http://serverlocation:port/customerManagement/customerAccount/2", "name": "CustomerAccount2", "description": "CustomerAccountDesc2", "accountStatus": "Active" } ] }

    REQUEST

    GET /customerManagement/customer?fields=id,name ,validFor&status=Active&validFor.startDateTime.gt=2013-05-05 Accept: application/json

    RESPONSE

    Status: 200 Content-Type: application/json [ { "id": "c1234", "name": "DisplayName", "validFor": { "startDateTime": "2013-06-06T16:42:23.0Z", "endDateTime": "" } }, { "id": "c1234", "name": "DisplayName", "validFor": { "startDateTime": "2013-08-09T16:42:23.0Z", "endDateTime": "" } } ]

• • PUT /customerManagement/customer/{ID}

    This Uniform Contract operation is used to completely update the representation of a managed entity or a task.
    Description:
• This operation is used to completely update a customer
• The resource represents a managed entity.
• The identifier is a string that can consist of numbers, not necessarily alphanumeric

Behavior:

• Return Status Codes:
  • 200 Customer data modified successfully
  • 400 Bad Request Error
  • 404 If no record was found for the supplied criteria
  • 500 The server encountered an unexpected condition which prevented it from fulfilling the request

The below query pattern can be used to modify all the data for a single customer, if an attribute is not provided, the value of the attribute is deleted:

PATCH API/customerManagement/customer/{ID}

This Uniform Contract operation is used to partially update the representation of a managed entity or a task.
Description:

• Patch operation can be used partially update one or more customers
• The resource represents a managed entity or a collection
• The identifier is a string that can consist of numbers, not necessarily alphanumeric

Behavior:

• Return Status Codes:
  • 200 – Customer(s) data modified successfully
  • 400 – Bad Request Error
  • 404 - If no record was found for the supplied criteria
  • 500 - The server encountered an unexpected condition which prevented it from fulfilling the request

Patchable attributes:

Rules:

Update of single attributes. In the following the name and the customerRank are updated. The request just consists of the two attributes with its new values. The response includes all attributes.

PATCH update for an array

POST /customerManagement/customer

This Uniform Contract operation is used to create a customer.
Description:

• This operation is used to create one customer
• The identifier is a string that can consist of numbers, not necessarily alphanumeric
• The mandatory element(s) is/are
  • Customer Name
• The id is generated automatically

Behavior:

• Return Status Codes:
  • 201 Customer create successfully. The Content-Location Header must be set and can be used to retrieve the customer
  • 400 Bad Request Error

  • 500 The server encountered an unexpected condition which prevented it from fulfilling the request

    Attribute name	Mandatory	Default	Rule
    id	N	Automatically generated	If not given, the id is generated by the system. It is also possible to add an ID in the POST request, which is then used
    name	Y
    status	N
    description	N
    validFor	N
    customerRank	N
    party	N
    characteristic	N
    contactMedium	N
    customerAccount	N
    customerCreditProfile	N
    paymentMean	N

    
    Rules:

    Rule name	Rule/Pre Condition/Side Effects/Post Conditions
    relatedParty	ref is mandatory
    characteristic	name and value are mandatory
    contactMedium	type and medium are mandatory
    customerAccount	id, name and accountStatus are mandatory
    customerCreditProfile	creditProfileDate and validFor are mandatory
    paymentMean	Id, href are mandatory

    
    The below query pattern can be used to create a single customer only the mandatory attributes:

    REQUEST

    POST /customerManagement/customer/ Content-type: application/json { "name": "DisplayName" }

    RESPONSE

    Status:201 Content-Type: application/json Content-Location: http://serverlocation:port/customerManagement/customer/c123423243 { "id": "c123423243", "name": "DisplayName", "status": "New", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "" } }

    
    The below query pattern can be used to create a single customer with more attributes:

    REQUEST

    POST /customerManagement/customer/ Content-type: application/json { "name": "DisplayName", "customerRank": 3, "relatedParty": { "id": "1", "href": "http://serverlocation:port/partyManagement/individual/1" }, "contactMedium": [ { "type": "Email", "medium": { "emailAddress": "

• • abc@tmforum.com" } }, { "preferred": true, "type": "TelephoneNumber", "medium": { "type": "business", "number": "+436641234567" } } ], "customerCreditProfile": [ { "creditProfileDate": "2013-04-19T16:42:23-04:00", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "2013-06-19T00:00:00-04:00" }, "creditRiskRating": "1", "creditScore": "1" }, { "creditProfileDate": "2013-04-19T16:42:23-04:00", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "2013-06-19T00:00:00-04:00" }, "creditRiskRating": "1", "creditScore": "1" } ] }

    RESPONSE

    Status:201 Content-Type: application/json Content-Location: http://serverlocation:port/customerManagement/customer/c1234 { "id": "c1234", "name": "DisplayName", "status": "New", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "" }, "customerRank": 3, "relatedParty": { "id": "1", "href": "http://serverlocation:port/partyManagement/individual/1" }, "contactMedium": [ { "type": "Email", "medium": { "emailAddress": "

• • abc@tmforum.com" } }, { "preferred": true, "type": "TelephoneNumber", "medium": { "type": "business", "number": "+436641234567" } } ], "customerCreditProfile": [ { "creditProfileDate": "2013-04-19T16:42:23-04:00", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "2013-06-19T00:00:00-04:00" }, "creditRiskRating": "1", "creditScore": "1" }, { "creditProfileDate": "2013-04-19T16:42:23-04:00", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "2013-06-19T00:00:00-04:00" }, "creditRiskRating": "1", "creditScore": "1" } ]

• • }

• • DELETE /customerManagement/customer/{ID}

    This Uniform Contract operation is used to delete a managed entity or a task.
    Description:
• This operation is used to delete customer(s) using customer id(s)
• The resource represents a managed entity
• The identifier is a string that can consist of numbers, not necessarily alphanumeric

Behavior:

• Return Status Codes:
  • 204 – NO Content. Customer Deleted successfully
  • 400 – Bad Request Error
  • 404 – Customer Data Not Found
  • 500 - The server encountered an unexpected condition which prevented it from fulfilling the request

GET customerManagement/customerAccount/{ID}

Note that collections can be retrieved via GET /customerManagement /customerAccount with no {ID}
Description :

• This operation returns all customerAccounts, unless an ID is specified in which case a specific customerAccount resource would be returned.
• The resource instance being returned is a customerAccount or an array of customerAccounts if the query returns multiple resources
• Filtering is enabled on all customerAccount attributes.
• Attribute selection is enabled.
• The ID may be a string (or a string containing numbers).

Behavior :

• What status and exception codes are returned.
  • 200 OK – customer account was retrieved
  • 404 Not found when the supplied ID doesn't match a known customerAccount.
  • 500 Internal server Error
• Returns HTTP/1.1 status code 200 if the request was successful.
• Any other special return and/or exception codes.

Examples: Get request with one customer including all attributes in the response. Filtering and attribute selection is described in the examples following.

In order to address a specific query a list of customer, with only a subset of the attributes in the response, the query pattern would look like the following:

In order to address a specific query against the Primary customer account (having an id) of an hierarchical account structure and also to reflect the hierarchy, the query pattern in this case would be as follows:

In order to address a specific query against those customer accounts which have been modified after a certain date time, the query pattern in this case would be as follows:

PUT customerManagement/customerAccount/{ID}

PUT is not supported for customerAccount as any modification can be handled through PATCH API.

PATCH customerManagement/customerAccount/{ID}

Description :

• This Uniform Contract operation is used to partially update the representation of a customer account.
• Resource represents the customer account.
• Behavior :
• Update of customer account will be based on identifier( id)
• Update of customer account is allowed to all attributes except attributes which are set by backend and are read-only (id, lastModified, etc.)
• Update of name, accountType, status, creditLimit is allowed through PATCH API.
• After creation of customer accout using mandatory parameters(mentoned in POST API),Update / linking of customer[], financialcharge[], relatedParty[], paymentPlan[] should be possible through PATCH.
• Child customer account can also be linked/updated to the parent customer by updating customerAccountRelationship[] in customerAccount resource.
• The resource instance being returned is a customerAccount

Behavior :

• Returns HTTP/1.1 status code 200 if the request was successful.
• Returns HTTP/1.1 status code 400 (Bad request) if content is invalid (missing required attributes, …).
• 500 – Internal server Error

Note: -The requester cannot update the id. The lastModified attributes is updated automatically in the back-end.

Eg: PATCH for adding a new customerAccountTaxExemption to customer account.

PATCH of accountType in customerAccount resource

POST customerManagement/customerAccount/{ID}

Description :

• This Uniform Contract operation is used to create a customer account.
• Resource represents a managed entity.
• The resource instance being returned is a customerAccount
• Mandatory attributes that must be provided when you create the customer account :

Behavior :

• Returns HTTP/1.1 status code 201 if the request was successful.
• Returns HTTP/1.1 status code 400 (Bad request) if content is invalid (missing required attributes, …).
• 500 – Internal server Error

The requester cannot generate the id. The id and lastModified attributes are generated automatically in the back-end.
Required Attributes: Name, AccountType
Read-Only Attributes: id, lastModified, receivableBalance, customerAccountBalance

Rules:

Create a customer account only with mandatory attributes:

DELETE customerManagement/customerAccount/{ID}

Note customer account will be deleted via DELETE /customerAccount/{ID} and will not allow deletion of customers if no id is provided.
Description:

• This operation will delete the customer Account with the specified ID
• The return will be response code and will not have any resource.
• Attribute selection is disabled.
• The ID may be a string (or a string containing numbers).

Behavior :

• What status and exception codes are returned.
  • 404 Not found when the supplied ID doesn't match a known customerAccount.
  • Returns HTTP/1.1 status code 204 if the request was successful.
  • 500 – Internal server Error

The following example shows deletion of customer account with filtration criteria based on id.

GET customerManagement/paymentMean/{ID}

Note that collections can be retrieved via GET /customerManagement /paymentMean with no {ID}
Description :

• This operation returns all paymentMean, unless an ID is specified in which case a specific paymentMean resource would be returned.
• The resource instance being returned is a paymentMean or an array of paymentMean if the query returns multiple resources
• Filtering is enabled on all paymentMean attributes.
• Attribute selection is enabled.
• The ID may be a string (or a string containing numbers).

Behavior :

• What status and exception codes are returned.
  • 200 OK – paymentMean was retrieved
  • 404 Not found when the supplied ID doesn't match a known paymentMean.
  • 500 Internal server Error
• Returns HTTP/1.1 status code 200 if the request was successful.
• Any other special return and/or exception codes.

Examples: Get request with one payment mean including all attributes in the response. Filtering and attribute selection is described in the examples following.

PUT customerManagement/paymentMean/{ID}

PUT is not supported for paymentMean as any modification can be handled through PATCH API.

PATCH customerManagement/paymentmean/{ID}

Description :

• This Uniform Contract operation is used to partially update the representation of a payment mean.
• Resource represents the payment mean.
• Behavior :
• Update of paymentMean will be based on identifier( id)
• Update of paymentMean is allowed to all attributes except attributes which are set by backend and are read-only (id, href, etc.)
• Update of name, validFor is allowed through PATCH API.

Behavior :

• Returns HTTP/1.1 status code 200 if the request was successful.
• Returns HTTP/1.1 status code 400 (Bad request) if content is invalid (missing required attributes, …).

• 500 – Internal server Error

  Attribute name	Patchable	Rule
  id	N	Cannot be updated from outside
  href	N	Cannot be updated from outside
  name	Y
  validFor	Y

  Rule name	Rule/Pre Condition/Side Effects/Post Conditions

  
  Eg: PATCH for updating the name.

  REQUEST

  PATCH /customerManagement/customerAccount/{ID} Content-type: application/json-patch+json { "op": "update", "path": "/customerAccount/paymentMean", "value": { "name": "new name for my credit card" } }

  RESPONSE

  Status:200 Content-Type: application/json { JSON Resource Representation with every attributes }