select a site  ||  useful feedback!   |  manage my requests   |  hr casework   |  icasework

REST API

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.
Quick links
Contact us

Phone +44 (0)20 3514 9014
Enquiry form
Request a demo

Follow UsefulFeedback on Twitter
like this
iCasework ™ | Terms & conditions | SLA | Privacy Statement