UsefulFeedback! provides a range of REST style web-services that allow both update and query operations such as case creation, adding case notes or retrieving case details to be invoked remotely.
The REST services are provided as http or ideally https end-points that can be invoked directly with one or more parameters. Each service returns an XML document whose contents vary depending on the operation performed.
Authentication
The
UsefulFeedback! REST web-services require all requests to be made with valid access credentials. To invoke a service, a user must have both an API key as well as a Secret key.
To allocate access keys select the API Keys menu option from the Administration menu and follow the on-screen instructions. Each of the services then require that two parameters, Key and Signature are included with a call. The Key parameter should contain a valid API key to identify the user/system making the call. For increased security, the Signature parameter is made up of an MD5 hash of that user's secret key appended together with the value of the request data parameter and, in most cases (the create case service being the only exception) another parameter included in the call. For example, if a user is issued with the following keys:
API key:
0c54a5a5855483e04c26de1dc
Secret key:
1e4ecd8c836bbd7bc9ae4b5e6
Then when making calls to the REST Update external id web service this user should include the parameter
Key=0c54a5a5855483e04c26de1dc to identify themselves. To calculate their signature value they would append the Case Id value (53342 in this example) and the request date (e.g. 2010-01-01) to their secret key in the order case id + request date + secret key, i.e.
533422010-01-011e4ecd8c836bbd7bc9ae4b5e6 and that string should then be hashed using MD5 encoding. So the value of the Signature parameter passed to the web service would be:
Signature=44365b38db1a1f36df7f91067b873493
By including another parameter from the call in the signature hash, it ensures that the value of the secret key is kept hidden and the signature value required will change with every call made so the value cannot be captured and reused by unauthorised parties. Each REST web service uses a different input parameter as part of the expected signature hash, please see the individual service descriptions below to find the relevant parameter for each service.
Network address restrictions
To enforce further security restrictions for REST web service calls, it is possible to limit the use of each allocated key pair to requests made from certain specified IP addresses. When allocating a new key pair, a list of allowed IP addresses can be set so that the given key and secret key can only be used to validate requests made from one of those IPs. Requests made from any other address using that key pair will be denied. Key pairs without IP restrictions will be accepted on requests made from any IP address.
Case creation
This service can be used to create cases on
UsefulFeedback! The createcase service resides at the following URL end-point
https://portal.icasework.com/services/youraccountid/createcase?Type=Complaint
There are four predefined types that can be used to create cases through this interface:
| Complaint |
| Compliment |
| Query |
| Suggestion |
| Comment |
Further parameters are required but depend on the type of case that is being created, specified by the value of the Type parameter. Note however that many of the parameters listed are only available when explicitly enabled through the preferences screens in the Administration menu. Values passed for many parameters such as ContactMethod also need to match values configured through the Administration menu. Choosing a solution pre-configured for your industry will have provided you with a good starting point for these preferences.
All four of these form types share common parameters about customers which may be added or posted to the URLs:
https://portal.icasework.com/services/youraccountid/createcase?Type=Complaint&Customer.Surname=Smith.
Note that details passed for customers with a Customer.Id will update existing details held, if any.
Customer parameters
| Name |
Value |
| Customer.Id |
The customer's unique reference |
| Customer.Title |
The customer's title (Mr, Mrs, Ms etc) |
| Customer.FirstName |
The customer's first name |
| Customer.Surname |
The customer's surname |
| Customer.Organisation |
The organisation this customer belongs to, if any |
| Customer.Address |
The street component of the customer's address |
| Customer.Town |
The town component of the address |
| Customer.County |
The county, province or region component of the address |
| Customer.Country |
The country component of the address |
| Customer.Postcode |
The zip or postcode component of the address |
| Customer.Email |
The customer's email address |
| Customer.Phone |
The customer's landline phone number |
| Customer.Mobile |
The customer's mobile phone number |
| Customer.ContactMethod |
How the customer would prefer to be contacted (e.g. Email, Phone, Letter) |
| Customer.ContactTime |
What days or times of day the customer would prefer to be contacted if contact is made by telephone |
| Customer.ContactLanguage |
The ISO 639 two letter code for the customer's preferred contact language (e.g. fr, en, nl) |
| Customer.ContactConsent |
Whether the customer agrees to be contacted again in future |
| Customer.Category |
A category or type assigned to the customer |
| Customer.Gender |
The gender of the customer |
| Customer.EthnicOrigin |
The ethnicity of the customer |
| Customer.Sexuality |
The sexuality of the customer |
| Customer.Faith |
The faith of the customer |
| Customer.DateOfBirth |
The date of birth of the customer |
| Customer.AgeGroup |
The age group of the customer |
| Customer.Disability1 |
Any disability the customer may have |
| Customer.Disability2 |
Any disability the customer may have |
| Customer.Disability3 |
Any disability the customer may have |
| Customer.Disability4 |
Any disability the customer may have |
| Customer.Disability5 |
Any disability the customer may have |
| Customer.Disability6 |
Any disability the customer may have |
| Customer.Disability7 |
Any disability the customer may have |
| Customer.Disability8 |
Any disability the customer may have |
| Customer.Disability9 |
Any disability the customer may have |
General parameters
| Name |
Value |
| RequestDate |
The date the complaint was received, in XML date-time format |
| RequestMethod |
How the complaint was received, e.g. Email, Phone, Post |
| ExternalId |
An existing reference for the case. If passed, this will be stored and made available to search against. |
| Team |
The code of the team to assign this case to. Pass INBOX to assign the case to the generic 'Unallocated Casework' team where it can be re-assigned further. If no code is passed, the case will be closed immediately. |
| Details |
Details of the complaint, compliment, query, suggestion or comment |
When calling the Create case web service, the signature hash required to authorise the call is based on the combination of the calling user's secret key and the value of the RequestDate parameter passed in, appended in the order RequestDate + secret key then hashed using MD5 encoding. Unlike all other calls, there is no third parameter used to create the signature string for this service.
Additional parameters for complaints
In addition, the complaint form allows complaints to be registered by an agent or representative acting on behalf of the customer making the complaint. In this case, the following details of the agent can also be passed. Again, details passed for agents with a reference will update existing details held, if any.
Agent parameters
| Name |
Value |
| Agent.Id |
The agent's unique reference |
| Agent.Title |
The agent's title (Mr, Mrs, Ms etc) |
| Agent.FirstName |
The agent's first name |
| Agent.Surname |
The agent's surname |
| Agent.Organisation |
The organisation this agent belongs to, if any |
| Agent.Address |
The street component of the agent's address |
| Agent.Town |
The town component of the address |
| Agent.County |
The county, province or region component of the address |
| Agent.Country |
The country component of the address |
| Agent.Postcode |
The zip or postcode component of the address |
| Agent.Email |
The agent's email address |
| Agent.Phone |
The agent's landline phone number |
| Agent.Mobile |
The agent's mobile phone number |
| Agent.ContactMethod |
How the agent would prefer to be contacted (e.g. Email, Phone, Letter) |
| Agent.ContactTime |
What days or times of day the agent would prefer to be contacted if contact is made by telephone |
| Agent.ContactLanguage |
The ISO 639 two letter code for the agent's preferred contact language (e.g. fr, en, nl) |
| Agent.RepresentativeType |
The relationship of the agent to the customer, e.g. Solicitor, Parent etc. |
The following further parameters can also be passed for a complaint
Additional parameters
| Name |
Value |
| Category |
A general category to assign to the complaint (if supported by your configuration) |
| ContactedBeforeDetails |
Details of any previous contacts by this customer about the issue. |
| ActionRequested |
Action requested by the customer |
| ImmediateResolutionDetails |
Details of any actions taken so far |
Attached images and documents
The following parameters may be passed to attach images and or other documents. Multiple documents may be attached by using a number suffix such as Document1, Document2 etc:
Parameters
| Name |
Value |
Format |
| Document1.Name |
Name of the attached file |
Character (100) |
| Document1.MimeType |
Mime type of the attached file |
Character (100) |
| Document1.URL |
URL of the attached file |
Character (500) |
| Document1.URLPublic |
Whether the URL is available publicly. If not, a callback will try to retrieve the document from the URL given during submission of the web service. |
Boolean |
Add case notes
The addcasenotes service can be used to submit notes or comments against an existing case in
UsefulFeedback! Notes added will be shown when the case worker accesses the case and optionally, when the customer checks progress. The add case notes service resides at the following URL end-point
https://portal.icasework.com/services/youraccountid/addcasenotes
The service requires that the following parameters are passed. Either a CaseId or an ExternalId must be passed to allow the note to be attached to an existing case.
Parameters
| Name |
Value |
| Notes |
The text of the note to be added |
| Type |
The type of note being added |
| SelfServiceAccess |
Whether or not the note should be visible to the customer associated with the case (Set to true to allow customers to view the note) |
| CaseId |
The UsefulFeedback! reference number for the case |
| ExternalId |
The external reference number of the case from the originating system. |
| RequestDate |
The current date and time, in XML date-time format |
When calling the Add case notes web service, the signature hash required to authorise the call is based on the combination of the calling user's secret key and the value of either the CaseId or ExternalId parameters, whichever is used in the call along with the RequestDate value. The three should be appended in the order CaseId/ExternalId + RequestDate + secret key then hashed using MD5 encoding.
Update external id
This service can be used to link case records in
UsefulFeedback! to records of the same case in another system. Once a case in linked in this way, the case can be accessed using the external reference number as well as the
UsefulFeedback! case reference. The updateexternalid service resides at the following URL end-point
https://portal.icasework.com/services/youraccountid/updateexternalid
The service requires that the following parameters are populated with values in the call
Parameters
| Name |
Value |
| CaseId |
The UsefulFeedback! case reference number |
| ExternalId |
The external reference number to associate with the specified case |
| RequestDate |
The current date and time, in XML date-time format |
When calling the Update external id web service, the signature hash required to authorise the call is based on the combination of the calling user's secret key and the value of the CaseId parameter passed in along with the RequestDate, appended in the order CaseId + RequestDate + secret key then hashed using MD5 encoding.
Create or update customer details
This service can be used to create or update customer records on
UsefulFeedback! The updatecustomer service resides at the following URL end-point
https://portal.icasework.com/services/youraccountid/updatecustomer
Parameters
| Name |
Value |
| Id |
The customer's unique reference |
| Title |
The customer's title (Mr, Mrs, Ms etc) |
| FirstName |
The customer's first name |
| Surname |
The customer's surname |
| Organisation |
The organisation this customer belongs to, if any |
| Address |
The street component of the customer's address |
| Town |
The town component of the address |
| County |
The county, province or region component of the address |
| Country |
The country component of the address |
| Postcode |
The zip or postcode component of the address |
| Email |
The customer's email address |
| Phone |
The customer's landline phone number |
| Mobile |
The customer's mobile phone number |
| ContactMethod |
How the customer would prefer to be contacted (e.g. Email, Phone, Letter) |
| ContactTime |
What days or times of day the customer would prefer to be contacted if contact is made by telephone |
| ContactLanguage |
The ISO 639 two letter code for the customer's preferred contact language (e.g. fr, en, nl) |
| ContactConsent |
Whether the customer agrees to be contacted again in future |
| Category |
A category or type assigned to the customer |
| Gender |
The gender of the customer |
| EthnicOrigin |
The ethnicity of the customer |
| Sexuality |
The sexuality of the customer |
| Faith |
The faith of the customer |
| DateOfBirth |
The date of birth of the customer |
| AgeGroup |
The age group of the customer |
| Disability1 |
Any disability the customer may have |
| Disability2 |
Any disability the customer may have |
| Disability3 |
Any disability the customer may have |
| Disability4 |
Any disability the customer may have |
| Disability5 |
Any disability the customer may have |
| Disability6 |
Any disability the customer may have |
| Disability7 |
Any disability the customer may have |
| Disability8 |
Any disability the customer may have |
| Disability9 |
Any disability the customer may have |
| RequestDate |
The current date and time, in XML date-time format |
When calling the Create or update customer web service, the signature hash required to authorise the call is based on the combination of the calling user's secret key and the value of the Id parameter passed in along with the RequestDate, appended in the order Id + RequestDate + secret key then hashed using MD5 encoding.
Get cases output
This service can be used to get a list of cases using defined criteria from
UsefulFeedback. The getcases service resides at the following URL end-point:
https://portal.icasework.com/services/youraccountid/getcases
Parameters
| Name |
Value |
| Type |
The type of case(Complaint, Query, Compliment, Comment, Suggestion, Improvement project) |
| From |
The date from when you want a list of cases, in XML date-time format |
| Until |
The date until when you want a list of cases, in XML date-time format |
| Days |
This is an alternative to providing a From and Until |
| Classification |
If passed, this will be used to restrict the output to only include cases with this classification. |
| Order |
Can have the value of 'ReceiptDate' or 'CompletionDate' If passed, this will be used to order the output either by receipt date or completion date. |
| MaxCases |
If passed, this will be used to restrict the number of cases in the output (positive integer) |
| CaseId |
If passed, this will be used to restrict the output to only include a case with this valid iCasework case reference. |
When calling the Get cases output web service, the signature hash required to authorise the call is based on the combination of the calling user's secret key and the UntilDate, appended in the order UntilDate + secret key then hashed using MD5 encoding.
Get report output
This service can be used to export just about anything from
UsefulFeedback! Simply utilise our powerful Ad-hoc Reporting facility to export data relating to cases, tasks, correspondence or customers using defined criteria, then reference the report here. The getReport service resides at the following URL end-point:
https://portal.icasework.com/services/youraccountid/getreport
Parameters
| Name |
Value |
| ReportId |
The UsefulFeedback! ad-hoc report reference |
| RequestDate |
The current date and time, in XML date-time format |
When calling the Get report output web service, the signature hash required to authorise the call is based on the combination of the calling user's secret key and the value of the ReportId parameter passed in along with the RequestDate, appended in the order ReportId + RequestDate + secret key then hashed using MD5 encoding.