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

REST API

ManageMyRequests 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 ManageMyRequests 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 requires 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 ManageMyRequests. The createcase service resides at the following URL end-point
https://portal.icasework.com/services/youraccountid/createcase?Type=InformationRequest

There are three predefined types that can be used to create cases through this interface:
InformationRequest
SubjectAccess
DisclosureRequest

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 three 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=InformationRequest&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


General parameters
Name Value
RequestDate The date the request was received, in XML date-time format
RequestMethod How the request 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. If no code is passed, the case will be assigned to the generic 'Unallocated Casework' team where it can be re-assigned further.
Details Details of the Information request, Subject Access request or Disclosure request

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 Subject Access and Disclosure requests

In addition, the Subject Access request and Disclosure request forms allows requests to be registered by an agent or representative acting on behalf of the person making the requests. 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.RepresentativeType The relationship of the agent to the customer, e.g. Solicitor, Parent etc.


Additional parameters for Disclosure requests
Name Value
Investigation Describe the nature of the investigation (e.g. citing any relevant statutory authority to obtain the information).
Emergency Whether the request is an emergency
ReasonPrejudice Whether the information is required because without it the prevention or detection of crime will be prejudiced
ReasonOffenders Whether the information is required because without it the apprehension or prosecution of offenders will be prejudiced
ReasonTax Whether the information is required because without it the assessment or collection of any tax or duty will be prejudiced
ReasonLegal Whether the information is required because the data is necessary for the purpose of, or in connection with, legal proceedings or is otherwise necessary for the purpose of establishing, exercising or defending legal rights.
ReasonAct Whether the information is required because disclosure is required by an Act of Parliament
Act Act of Parliament
ActYear Act year
ActSection Act section

Add case notes

The addcasenotes service can be used to submit notes or comments against an existing case in ManageMyRequests. 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 ManageMyRequests 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 ManageMyRequests to records of the same case in another system. Once a case is linked in this way, the case can be accessed using the external reference number as well as the ManageMyRequests 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 ManageMyRequests 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 ManageMyRequests. 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
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 ManageMyRequests. 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(InformationRequest, SubjectAccessRequest, DisclosureRequest)
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 ManageMyRequests. 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 ManageMyRequests 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

Case studies
liverpool logo southwark logo harrow logo