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

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:

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

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

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

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:

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:

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.