How-to Guide - Soap API - Customers, Loyalty, and Account Balances

Customer API

Customer Name Search

This service allows to get a list of customers matching the search name criteria.

The response consists of a paged array list. The contents of the response include a list of values for each customer record, comprising the name, address and customer number.

At the end of the response is a list of the property names returned, in the same sequence as the value lists.

Request

Request Service Name

CustomerService

Request Operation

submitCustomerNameSearch

Request Endpoint

http://${Server.CRM_WS.Host}:${Server.CRM_WS.HttpPort}/axis2/services/CustomerService

Request Body

Element	Required / Optional	Type	Description
searchName	Mandatory	String	The customer name which to search.

Response

Response Headers

There are no response headers.

Response Body

Element	Type	Description
pagedArrayList	Complex Type	Includes a list of accounts for the requested name searched

Request & Response Examples

Request:

Search for customers with name starting with 'a':

<ns:submitCustomerNameSearch xmlns:ns="http://www.enactor.com/core">
<retail:customerNameSearchRequest xmlns:retail="http://www.enactor.com/retail"
    <retail:searchName>a</retail:searchName>
    <retail:types/>
</retail:customerNameSearchRequest>
</ns:submitCustomerNameSearch>

Response:

The example response includes two customer records - Miss Amelia and Mr Aspen:

<ns:submitCustomerNameSearchResponse xmlns:ns="http://www.enactor.com/core">
<core:pagedArrayList xmlns:core="http://www.enactor.com/core"rowsPerPage="0"
currentRowOffset="0" totalRows="0">
    <core:contents xsi:type="core:ListElement">
        <core:key xsi:type="retail:CustomerKey">100</core:key>
        <core:descriptionProperty>100</core:descriptionProperty>
        <core:data>
            <core:values>
                <core:arrayObject xsi:type="core:String">100</core:arrayObject>
                <core:arrayObject xsi:type="core:String">Amelia</core:arrayObject>
                <core:arrayObject xsi:type="core:String">Baldwin</core:arrayObject>
                <core:arrayObject xsi:type="core:String">Mrs</core:arrayObject>
                <core:arrayObject xsi:type="core:WrappedPrimitive">
                    <core:value xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xsi:type="xsd:dateTime">1987-02-03T00:00:00Z</core:value>
                </core:arrayObject>
                <core:arrayObject xsi:type="core:String">Enactor</core:arrayObject>
                <core:arrayObject xsi:type="core:String"/>
                <core:arrayObject xsi:type="core:WrappedNull"/>
                <core:arrayObject xsi:type="core:String">137 Newport Road</core:arrayObject>
                <core:arrayObject xsi:type="core:String"/>
                <core:arrayObject xsi:type="core:String"/>
                <core:arrayObject xsi:type="core:String">Carmel</core:arrayObject>
                <core:arrayObject xsi:type="core:String"/>
                <core:arrayObject xsi:type="core:String">SG14 3AG</core:arrayObject>
                <core:arrayObject xsi:type="core:String">TRUE</core:arrayObject>
            </core:values>
        </core:data>
        <core:description>customerNumber=100;</core:description>
    </core:contents>
    <core:contents xsi:type="core:ListElement">
    <core:key xsi:type="retail:CustomerKey">7004</core:key>
        <core:descriptionProperty>7004</core:descriptionProperty>
        <core:data>
            <core:values>
                <core:arrayObject xsi:type="core:String">7004</core:arrayObject>
                <core:arrayObject xsi:type="core:String">Aspen</core:arrayObject>
                <core:arrayObject xsi:type="core:String">Green</core:arrayObject>
                <core:arrayObject xsi:type="core:String">Mrs</core:arrayObject>
                <core:arrayObject xsi:type="core:WrappedPrimitive">
                    <core:value xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xsi:type="xsd:dateTime">1998-05-22T00:00:00+01:00</core:value>
                </core:arrayObject>
                <core:arrayObject xsi:type="core:String"/>
                <core:arrayObject xsi:type="core:String"/>
                <core:arrayObject xsi:type="core:WrappedNull"/>
                <core:arrayObject xsi:type="core:String">Dagkli</core:arrayObject>
                <core:arrayObject xsi:type="core:String"/>
                <core:arrayObject xsi:type="core:String"/>
                <core:arrayObject xsi:type="core:String">Thessaloniki</core:arrayObject>
                <core:arrayObject xsi:type="core:String"/>
                <core:arrayObject xsi:type="core:String">54621</core:arrayObject>
                <core:arrayObject xsi:type="core:String">FALSE</core:arrayObject>
            </core:values>
        </core:data>
        <core:description>customerNumber=7004;</core:description>
    </core:contents>
    <core:propertyNames>customerNumber</core:propertyNames>
    <core:propertyNames>customerName.forename</core:propertyNames>
    <core:propertyNames>customerName.surname</core:propertyNames>
    <core:propertyNames>customerName.title</core:propertyNames>
    <core:propertyNames>customerName.dateOfBirth</core:propertyNames>
    <core:propertyNames>organisation</core:propertyNames>
    <core:propertyNames>tradingName</core:propertyNames>
    <core:propertyNames>lastTransactionDate</core:propertyNames>
    <core:propertyNames>AddressJoin:street1</core:propertyNames>
    <core:propertyNames>AddressJoin:street2</core:propertyNames>
    <core:propertyNames>AddressJoin:street3</core:propertyNames>
    <core:propertyNames>AddressJoin:town</core:propertyNames>
    <core:propertyNames>AddressJoin:province</core:propertyNames>
    <core:propertyNames>AddressJoin:postCode</core:propertyNames>
    <core:propertyNames>hasLoyaltyAccounts</core:propertyNames>
</core:pagedArrayList>
</ns:submitCustomerNameSearchResponse>

Customer Postcode Search

This service allows to get a list of customers matching the search postcode criteria.

The response consists of a paged array list. The contents of the response include a list of values for each customer record, comprising the name, address and customer number.At the end of the response is a list of the property names returned, in the same sequence as the value lists.

Request

Request Service Name

CustomerService

Request Operation

submitCustomerNameSearch

Request Endpoint

http://${Server.CRM_WS.Host}:${Server.CRM_WS.HttpPort}/axis2/services/CustomerService

Request Body

Element	Required / Optional	Type	Description
searchName	Mandatory	String	The postcode value to be searched.

Response

Response Headers

There are no response headers.

Response Body

Element	Type	Description
pagedArrayList	Complex Type	Includes a list of accounts for the requested name searched

Request & Response Examples

Request

Search for customers with name starting with 'sg14':

<ns:submitCustomerPostCodeSearch xmlns:ns="http://www.enactor.com/core">
<core:string xmlns:core=http://www.enactor.com/core>sg14</core:string>
</ns:submitCustomerPostCodeSearch>

Response:

The example response includes two customer records - Mr Ricky and Miss Amelia:

<ns:submitCustomerPostCodeSearchResponse xmlns:ns="http://www.enactor.com/core">
<core:pagedArrayList xmlns:core="http://www.enactor.com/core rowsPerPage="0 currentRowOffset="0" totalRows="0">
    <core:contents xsi:type="core:ListElement">
        <core:key xsi:type="retail:CustomerKey">00100</core:key>
        <core:descriptionProperty>00100</core:descriptionProperty>
        <core:data>
            <core:values>
                <core:arrayObject xsi:type="core:String">00100</core:arrayObject>
                <core:arrayObject xsi:type="core:String">Ricky</core:arrayObject>
                <core:arrayObject xsi:type="core:String">Gervais</core:arrayObject>
                <core:arrayObject xsi:type="core:String"/>
                <core:arrayObject xsi:type="core:WrappedNull"/>
                <core:arrayObject xsi:type="core:String"/>
                <core:arrayObject xsi:type="core:String"/>
                <core:arrayObject xsi:type="core:WrappedNull"/>
                <core:arrayObject xsi:type="core:String">137 Newport Road</core:arrayObject>
                <core:arrayObject xsi:type="core:String"></core:arrayObject>
                <core:arrayObject xsi:type="core:String"/>
                <core:arrayObject xsi:type="core:String"/>
                <core:arrayObject xsi:type="core:String"/>
                <core:arrayObject xsi:type="core:String">SG14 3AG</core:arrayObject>
                <core:arrayObject xsi:type="core:String">FALSE</core:arrayObject>
            </core:values>
        </core:data>
        <core:description>customerNumber=00100;</core:description>
    </core:contents>
    <core:contents xsi:type="core:ListElement">
        <core:key xsi:type="retail:CustomerKey">100</core:key>
        <core:descriptionProperty>100</core:descriptionProperty>
        <core:data>
            <core:values>
                <core:arrayObject xsi:type="core:String">100</core:arrayObject>
                <core:arrayObject xsi:type="core:String">Amelia</core:arrayObject>
                <core:arrayObject xsi:type="core:String">Baldwin</core:arrayObject>
                <core:arrayObject xsi:type="core:String">Mrs</core:arrayObject>
                <core:arrayObject xsi:type="core:WrappedPrimitive">
                    <core:value xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xsi:type="xsd:dateTime">1987-02-03T00:00:00Z</core:value>
                </core:arrayObject>
                <core:arrayObject xsi:type="core:String">Enactor</core:arrayObject>
                <core:arrayObject xsi:type="core:String"/>
                <core:arrayObject xsi:type="core:WrappedNull"/>
                <core:arrayObject xsi:type="core:String">137 Newport Road</core:arrayObject>
                <core:arrayObject xsi:type="core:String"/>
                <core:arrayObject xsi:type="core:String"/>
                <core:arrayObject xsi:type="core:String">Carmel</core:arrayObject>
                <core:arrayObject xsi:type="core:String"/>
                <core:arrayObject xsi:type="core:String">SG14 3AG</core:arrayObject>
                <core:arrayObject xsi:type="core:String">TRUE</core:arrayObject>
            </core:values>
        </core:data>
        <core:description>customerNumber=100;</core:description>
    </core:contents>
    <core:propertyNames>customerNumber</core:propertyNames>
    <core:propertyNames>customerName.forename</core:propertyNames>
    <core:propertyNames>customerName.surname</core:propertyNames>
    <core:propertyNames>customerName.title</core:propertyNames>
    <core:propertyNames>customerName.dateOfBirth</core:propertyNames>
    <core:propertyNames>organisation</core:propertyNames>
    <core:propertyNames>tradingName</core:propertyNames>
    <core:propertyNames>lastTransactionDate</core:propertyNames>
    <core:propertyNames>AddressJoin:street1</core:propertyNames>
    <core:propertyNames>AddressJoin:street2</core:propertyNames>
    <core:propertyNames>AddressJoin:street3</core:propertyNames>
    <core:propertyNames>AddressJoin:town</core:propertyNames>
    <core:propertyNames>AddressJoin:province</core:propertyNames>
    <core:propertyNames>AddressJoin:postCode</core:propertyNames>
    <core:propertyNames>hasLoyaltyAccounts</core:propertyNames>
</core:pagedArrayList>
</ns:submitCustomerPostCodeSearchResponse>

Account Balance API

Loyalty Account Search

This service allows to get a list of loyalty accounts matching a customer.

This response is also returned as a Paged array list (though normally there would be only one record returned).

The values list has three values: the Customer loyalty account number, account type and status.

Now that the customer loyalty account number has been found, it may be submitted to the account balance enquiry service to retrieve the account details.

Request

Request Service Name

AccountBalanceService

Request Operation

submitLoyaltyAccountSearch

Request Endpoint

 http://${Server.CRM_WS.Host}:${Server.CRM_WS.HttpPort}/axis2/servicesAccountBalanceService

Request Body

Element	Required / Optional	Type	Description
submitLoyaltyAccountSearch	Mandatory	Complex Type	The root request element.
value	Mandatory	String	The customer number for which loyalty accounts are to be searched.

Response

Response Headers

There are no response headers.

Response Body

Element	Type	Description
pagedArrayList	Complex Type	Includes a list of loyalty accounts for the requested customer number.

Request & Response Examples

Request

Search for loyalty accounts of the customer with the customer ID of '100':

<ns:submitLoyaltyAccountSearch
xmlns:ns="http://www.enactor.com/retail/AccountBalanceService">
<core:string xmlns:core="http://www.enactor.com/core">100</core:string>
</ns:submitLoyaltyAccountSearch>

Response

The example response includes two loyalty account records for the customer ID of '100'.

<ns:submitLoyaltyAccountSearchResponse
xmlns:ns="http://www.enactor.com/retail/AccountBalanceService">
<core:pagedArrayList xmlns:core="http://www.enactor.com/core" rowsPerPage="1000"
currentRowOffset="0" totalRows="2">
    <core:contents xsi:type="core:ListElement">
        <core:key xsi:type="retail:CustomerLoyaltyAccountKey"
accountType="customerLoyaltyAccount">200</core:key>
        <core:descriptionProperty>accountId</core:descriptionProperty>
        <core:data>
            <core:values>
                <core:arrayObject xsi:type="core:String">200</core:arrayObject>
                <core:arrayObject
xsi:type="core:String">customerLoyaltyAccount</core:arrayObject>
                <core:arrayObject xsi:type="core:String">ACTIVE</core:arrayObject>
            </core:values>
        </core:data>
        <core:description>200</core:description>
    </core:contents>
    <core:contents xsi:type="core:ListElement">
        <core:key xsi:type="retail:CustomerLoyaltyAccountKey"
accountType="customerLoyaltyAccount">4</core:key>
        <core:descriptionProperty>accountId</core:descriptionProperty>
        <core:data>
            <core:values>
                <core:arrayObject xsi:type="core:String">4</core:arrayObject>
                <core:arrayObject
xsi:type="core:String">customerLoyaltyAccount</core:arrayObject>
                <core:arrayObject xsi:type="core:String">ACTIVE</core:arrayObject>
                </core:values>
        </core:data>
        <core:description>4</core:description>
    </core:contents>
    <core:propertyNames>accountId</core:propertyNames>
    <core:propertyNames>accountType</core:propertyNames>
    <core:propertyNames>status</core:propertyNames>
</core:pagedArrayList>
</ns:submitLoyaltyAccountSearchResponse>

Account Balance Enquiry

This service provides the requested balance of any customer loyalty account.

Request

Request Service Name

AccountBalanceService

Request Operation

submitAccountBalanceEnquiry

Request Endpoint

 http://${Server.CRM_WS.Host}:${Server.CRM_WS.HttpPort}/axis2/services/AccountBalanceService

Request Body

Element	Mandatory / Optional	Type	Description
accountType	Mandatory	String	Type of the account.
cardNumber	Mandatory	String	Card number associated with the account.
cardNumberHashed	Optional	String	Hashed value of the card number.
currencyId	Optional	String	ID of the currency used in the account.
locationId	Optional	String	ID of the location associated with the account.

Response

Response Headers

There are no Response Headers.

Response Body

Element	Type	Description
account	Complex	Object containing the account information.
customer	Complex	Object containing the customer details.
accountBalance	Complex	Object containing the account balance information.
accountId	String	ID of the account.
accountType	String	Type of the account.
accountBalance	Long	Balance amount of the account.
balanceDate	DateTime	Date and time which the balance was last updated in the account.
customerCard	Complex	Object containing customer card details.
customerGroup	Complex	Customer Group details to which customer belongs (0 to many).
customerLoyaltyAccountTotal	Complex	Object containing the loyalty account summary totals.

Following are the outcomes for Account Balance Service Enquiry:

Success: Account is found and Customer details are returned.
NoAccount: Card or Customer Account is not found; the POS will inform the user appropriately.
UnknownAccountType: Customer found but account type not recognised.
Fail: Other failure occurred during Account lookup. An error message will be displayed to the user.

Request & Response Examples

Request:

Enquiry of loyalty account balance with the card number of '14420000':

<ns:submitAccountBalanceEnquiry
xmlns:ns="http://www.enactor.com/retail/AccountBalanceService">
<retail:accountBalanceEnquiryRequest xmlns:retail="http://www.enactor.com/retail">
    <retail:accountType>customerLoyaltyAccount</retail:accountType>
    <retail:cardNumber>14420000</retail:cardNumber>
    <retail:currencyId>GBP</retail:currencyId>
    <retail:locationId>0005</retail:locationId>
    <retail:transactionBalance>0</retail:transactionBalance>
</retail:accountBalanceEnquiryRequest>
</ns:submitAccountBalanceEnquiry>

Response

Following is an example response that includes the loyalty account record for the customer loyalty card of '14420000':

<ns:submitAccountBalanceEnquiryResponse
xmlns:ns="http://www.enactor.com/retail/AccountBalanceService">
<retail:accountBalanceEnquiryOutput xmlns:retail="http://www.enactor.com/retail">
    <retail:outcome name="Success"/>
    <retail:account xsi:type="retail:CustomerLoyaltyAccount">
        <retail:accountId>200</retail:accountId>
        <retail:accountType>customerLoyaltyAccount</retail:accountType>
        <retail:currencyId>GBP</retail:currencyId>
        <retail:status>ACTIVE</retail:status>
        <retail:accountOpenedDate>2021-11-01T00:00:00Z</retail:accountOpenedDate>
        <retail:customerNumber>100</retail:customerNumber>
        <retail:loyaltySchemeId>LOYALTY_UK</retail:loyaltySchemeId>
        <retail:tierCode>UK3</retail:tierCode>
        <retail:manualTierReview>false</retail:manualTierReview>
    </retail:account>
    <retail:customer>
        <retail:addresses>
            <retail:address>
                <retail:country>United Kingdom</retail:country>
                <retail:countryCodeId>GBR</retail:countryCodeId>
                <retail:isPreferred>true</retail:isPreferred>
                <retail:status>ACTIVE</retail:status>
                <retail:typeId>ADDRESS_HOME</retail:typeId>
                <retail:postCode>SG14 3AG</retail:postCode>
                <retail:street1>137 Newport Road</retail:street1>
                <retail:town>Carmel</retail:town>
                <retail:isTemplate>false</retail:isTemplate>
                <retail:referenceId/>
                <retail:lastUpdated>2024-02-14T05:22:35Z</retail:lastUpdated>
                <retail:addressReferenceId>bb36:1b2aadb5d71:ef5efbd7-:69b14aea4b151737</
retail:addressReferenceId>
            </retail:address>
        </retail:addresses>
        <retail:contactMethod>METHOD_EMAIL</retail:contactMethod>
        <retail:contactMethodNotes/>
        <retail:contactable>false</retail:contactable>
        <retail:maritalStatus/>
        <retail:nationality/>
        <retail:noChildren>0</retail:noChildren>
        <retail:customerNumber>100</retail:customerNumber>
        <retail:emailAddresses>
            <retail:emailAddress>rasangi.desilva@enactor.co.uk</retail:emailAddress>
            <retail:lastUpdated>2024-02-14T05:22:35Z</retail:lastUpdated>
            <retail:preferred>true</retail:preferred>
            <retail:restrictedReason/>
            <retail:status>ACTIVE</retail:status>
            <retail:typeId>EMAIL_HOME</retail:typeId>
            <retail:referenceId/>
            <retail:active>true</retail:active>
            <retail:emailAddressReferenceId>9ef7-:a8826dac381:785586d2-:8bf8ba3a4eb123e5</
retail:emailAddressReferenceId>
        </retail:emailAddresses>
        <retail:phoneNumbers>
            <retail:countryCode/>
            <retail:lastUpdated>2024-02-14T05:22:35Z</retail:lastUpdated>
            <retail:number>078 1839 3795</retail:number>
            <retail:preferred>true</retail:preferred>
            <retail:restrictedReason/>
            <retail:status>ACTIVE</retail:status>
            <retail:typeId>PHONE_MOBILE</retail:typeId>
            <retail:referenceId/>
            <retail:active>false</retail:active>
            <retail:phoneNumberReferenceId>1d56:1b2aadb5d71:ef5efbd7-:69b14aea4b151737</
retail:phoneNumberReferenceId>
        </retail:phoneNumbers>
        <retail:customerName>
            <retail:surname>Baldwin</retail:surname>
            <retail:forename>Amelia</retail:forename>
            <retail:initials>AB</retail:initials>
            <retail:title>Mrs</retail:title>
            <retail:sex>FEMALE</retail:sex>
            <retail:dateOfBirth>1987-02-03T00:00:00Z</retail:dateOfBirth>
        </retail:customerName>
        <retail:businessContactMethod>METHOD_PHONE</retail:businessContactMethod>
        <retail:preferredContactTime/>
        <retail:employeeKey/>
        <retail:lastUpdated>2024-02-14T05:22:35Z</retail:lastUpdated>
        <retail:customerType>RETAIL</retail:customerType>
        <retail:organisation>Enactor</retail:organisation>
        <retail:taxIdentification/>
        <retail:companyNumber/>
        <retail:createdBy/>
        <retail:createdAt/>
        <retail:status>Active</retail:status>
        <retail:source/>
        <retail:password/>
    </retail:customer>
    <retail:accountBalance>
        <retail:accountId>200</retail:accountId>
        <retail:accountType>customerLoyaltyAccount</retail:accountType>
        <retail:accountBalance>6028</retail:accountBalance>
        <retail:currencyId>GBP</retail:currencyId>
        <retail:balanceDate>2024-02-14T14:13:38Z</retail:balanceDate>
    </retail:accountBalance>
    <retail:customerCard>
        <retail:accountId>200</retail:accountId>
        <retail:status>CURRENT</retail:status>
        <retail:lastUpdated>2023-12-21T17:42:27.167Z</retail:lastUpdated>
        <retail:accountType>customerLoyaltyAccount</retail:accountType>
        <retail:pan>14420000</retail:pan>
        <retail:expiryDate/>
        <retail:nameOnCard/>
        <retail:createdOn>2021-11-01T00:00:00Z</retail:createdOn>
        <retail:validFrom/>
    </retail:customerCard>

Account Balance Update

This service allows sending an update request for the account balance of a given account.

Request

Request Service Name

AccountBalanceService

Request Operation

submitAccountBalanceUpdate

Request Endpoint

 http://${Server.CRM_WS.Host}:${Server.CRM_WS.HttpPort}/axis2/services/AccountBalanceService

Request Body

Element	Mandatory / Optional	Type	Description
transactionId	Mandatory	Long	ID of the transaction which the account balance is updated with.
deviceId	Optional	Complex Type	DeviceKey with the device ID.
originalTransactionDeviceId	Optional	Complex Type	DeviceKey with the device ID.
originalTransactionId	Optional	String	ID of the original transaction which the account balance is updated with.
locationId	Optional	String	ID of the location associated with the account.
accountId	Mandatory, if cardNumber is not assigned	String	ID of the account.
accountType	Mandatory	String	Type of the account.
cardNumber	Mandatory, if accountId is not assigned	String	Card number associated with the account.
updateAmount	Mandatory	Long	Amount that is to be updated to this account.
dateTimeUpdated	Mandatory	DateTime	Date and time of the update to this account.
expiryTime	Optional	DateTime	Expiry date and time of the account.
status	Optional	String	Status of the account.
currencyId	Optional	String	ID of the currency used in the account.

Response

Response Headers

There are no Response Headers.

Response Body

Element	Type	Description
outcome	Complex Type	The final status of the balance update process.
transactionId	Long	Unique ID for the transaction.
deviceId	Complex Type	DeviceKey with the device ID.
originalTransactionDeviceId	Complex Type	DeviceKey with the device ID.
originalTransactionId	String	ID of the original transaction which the account balance is updated with.
locationId	String	ID of the location associated with the account.
accountId	String	ID of the account.
accountType	String	Type of the account.
cardNumber	String	Card number associated with the account.
updateAmount	Long	Amount that is updated.
dateTimeUpdated	DateTime	Date and time of the update to this account.
expiryTime	DateTime	Expiry date and time of the account.
status	String	Status of the account.
customerAddress	Complex Type	This includes the customer address details.
customerName	Complex Type	This includes the customer name details.
currencyId	String	ID of the currency used in the account.
customerCard	Complex Type	A complex element with customer card details.
referenceId	String	Reference ID of the account balance update.
lastUpdated	DateTime	The date and time of the last update to the account.

Customer API​

Customer Name Search​

Response​

Request & Response Examples​

Customer Postcode Search​

Response​

Request & Response Examples​

Account Balance API​

Loyalty Account Search​

Request​

Response​

Request & Response Examples​

Account Balance Enquiry​

Request​

Response​

Request & Response Examples​

Account Balance Update​

Request​

Response​

Customer API

Customer Name Search

Response

Request & Response Examples

Customer Postcode Search

Response

Request & Response Examples

Account Balance API

Loyalty Account Search

Request

Response

Request & Response Examples

Account Balance Enquiry

Request

Response

Request & Response Examples

Account Balance Update

Request

Response