Using Attribute APIs to get and Modify Customer Attributes

The purpose of this article is to provide the steps needed for someone to access attribute information for a customer, as well as how to go about modifying values for those attributes. To help illustrate the various concepts covered in this article the following attribute definition and instance example will be referenced:

Customer Account Example:

• Customer Account Number: 00123456
• CuCustomer ID: 1015
• Assigned Attributes:
  • Customer.EmployeeTest:
    • EmailAddress: test@idibilling.com

Attribute Definition Tree:

This is the attribute tree including default values.

• Customer.EmployeeTest:
  • EmailAddress: NULL
  • TimesDelinquent: 0
  • 18YearsOrOlder: true

Get the Attribute Tree for a Customer

Determine Customer ID

To determine the CustomerID, the internal ID that is used to link a customer to objects, you can perform a customer search using the customer account number.

API: Customer Service – Customer Search

• Environment: Name of the environment you are working in.
• AccountNumbers: List of Account number of the customer accounts you are attempting to lookup

Important Response Information:

• CustomerID: This field is the customer internal ID for future API Calls.

Determine Attribute Property ID

To determine the attribute property id that is the root of the definition associated to the specific customer, the user must make use of the Customer Lookup operation in the Customer Service.

API: Customer Service – Customer Lookup

Important Request Information:

• Environment: Name of the environment you are working in.
• CustomerID: The customer internal ID found in the previous step for the target customer.

Important Response Information:

• AttributePropertyID: This field is the root property internal ID of the attribute definition that will be used in future API Calls.

Determine AttributeTree Including Default Values

The most common way of accomplishing this is through an attribute definition tree lookup using the RootPropertyID of the target customer attribute.

API: Data Service – Attribute Definition Tree

Example Call: https://api.idibilling.com/data/{version}/{environment}/CoreDataService/AttributeDefinitionTree()?$filter=RootPropertyID eq {AttributePropertyID}

Important Request Information:

• environment: Name of the environment you are working in.
• AttributePropertyID: The AttributePropertyID found in the previous step for the target attribute.

Example Response:

Sample response will be an array of attributes in the tree. Due to the large number of properties on an attribute object, only the properties that are needed for the next steps are shown.:

[{
	PropertyID: 10102,
	Name: Customer.EmployeeTest,
	DisplayName: Customer.EmployeeTest,
	DefaulValue: NULL,
	…
},{
	PropertyID: 10103,
	Name: EmailAddress,
	DisplayName: EmailAddress,
	DefaulValue: NULL,
	…
},{
	PropertyID: 10104,
	Name: TimesDelinquent,
	DisplayName: TimesDelinquent,
	DefaulValue: 0,
	…
},{
	PropertyID: 10105,
	Name: 18YearsOrOlder,
	DisplayName: 18YearsOrOlder,
	DefaulValue: true,
	…
}]

Getting Customer Attributes

The most common way of accomplishing this is through an extended information item lookup using the CustomerID of the target customer.

API: Customer Service – Extended Information Item

Example Call: https://api.idibilling.com/data/{version}/{environment}/CoreDataService/ExtendedInformationItem()?$filter=ObjectID eq {CustomerID} & ObjectType eq ‘Customer’

Important Request Information:

• Environment: Name of the environment you are working in.
• ObjectID: The customer internal ID found in the previous steps for the target customer.

Example Response:

[{
	Key:EmailAddress,
	ObjectID: 1015,
	ObjectType: Customer,
	Value: test@idibilling.com
}]

Build the Complete Customer Attribute Tree

To build the complete customer attribute tree you will need to merge together the results from the AttributeTree and ExtendedInformationItem searches. To merge the AttributeTree and ExtendedInformationItem start by finding the corresponding ‘Name’ and ‘DefaultValue’ properties on the AttributeTree response and create a list of ExtendedInformationItems. When creating the ExtendedInfromationItem use the ‘Name’ and ‘DefaultValue’ properties as the ‘Key’ and ‘Value’ properties respectively. For any matching entries between the ‘Key’ Name and ‘Name’ properties on the ExtendedInformationItem list already retrieved use the value from this response instead of the ‘DefaultValue’. The following example shows the attribute tree and the result of ExtendedInfromationItems after they have been merged together:

Attribute Tree value:

[{
	PropertyID: 10102,
	Name: Customer.EmployeeTest,
	DisplayName: Customer.EmployeeTest,
	DefaulValue: NULL,
	…
},{
	PropertyID: 10103,
	Name: EmailAddress,
	DisplayName: EmailAddress,
	DefaulValue: NULL,
	…
},{
	PropertyID: 10104,
	Name: TimesDelinquent,
	DisplayName: TimesDelinquent,
	DefaulValue: 0,
	…
},{
	PropertyID: 10105,
	Name: 18YearsOrOlder,
	DisplayName: 18YearsOrOlder,
	DefaulValue: true,
	…
}]

Completed Merged ExtendInformationItem List:

[{
	Key: Customer.EmployeeTest,
	ObjectID: 1015,
	ObjectType: Customer,
	Value: NULL
},{
	Key:EmailAddress
	ObjectID: 1015
	ObjectType: Customer
	Value: test@idibilling.com
},{
	Key: TimesDelinquent,
	ObjectID: 1015,
	ObjectType: Customer,
	Value: 0
},{
	Key: 18YearsOrOlder,
	ObjectID: 1015,
	ObjectType: Customer,
	Value: true
}]

Modifying Customer Attributes

Although it is possible to only update a single attribute using these API’s the best practice for a newly created customer is to update the entire attribute tree to ensure the Attributes are added to the Customer with the necessary default values.

API: Customer Service – Modify Extended Information

Important Request Information:

• environment: Name of the environment you are working in.
• ObjectID: Value from the ExtendedInfromationItem response.
• ObjectType: Value from the ExtendedInfromationItem response.
• ExtendedInformation: A set of ExtendedInformationItems created by merging the AttributeTree and ExtendedInfromationItem responses together.

Example Request:

{
ObjectID: 1015
      ObjectType: Customer,
      ExtendedInformation:
[{
			Key: Customer.EmployeeTest,
			ObjectID: 1015,
			ObjectType: Customer,
			Value: NULL
},{
	Key: EmailAddress,
	ObjectID: 1015,
	ObjectType: Customer,
	Value: test@idibilling.com
},{
	Key: TimesDelinquent,
	ObjectID: 1015,
	ObjectType: Customer,
	Value: 0
},{
	Key: 18YearsOrOlder,
	ObjectID: 1015,
	ObjectType: Customer,
	Value: true,
}]
}