Clients can use this API to publish cases to their self-service portals. When publishing cases to a self-service portal, make sure to call the self-service endpoint e.g. https://[youraccount]portal.icasework.com/. This ensures that sensitive information and personally identifiable information (PII)—including names, contact details, and other personal data—cannot be used to look up cases.

Description

The GetCases request can return an XML or JSON feed as its response, where the response will include details relating to cases that have been flagged as publicly available. The details returned include the case reference; the case type, as defined in the service menu; the case label; the cases' classifications and group of each classification; the name of reportable attributes that have a value indexed for the case (but not the value of the reportable attribute); the method through which the request was received; the details (document name; document MIME type; and URL to retrieve the document) of case documents; the complexity rating of the case; the time that the case was created on the system.

This data feed can be used to publish a disclosure log on your website. This API is not intended to allow access to all information on these cases - if you need this, you should use the GetReport API instead.

This API requires that your system and the case type’s workflow have been specifically designed to allow the flagging of cases as a publicly available case.

The GetCases request is accessed via your self-service portal. Click here more details on here on how to publish cases.

The values for From or Days ; and Until or today; will define the time period of the search, so that only cases that were received on or between these dates will be returned. The case’s receipt date is used for this comparison; this can be different to the case’s creation datetime.

If a value for From is defined (where this value should be an XML date) then this will represent the starting period of the search; if a value for Days is defined, but a value for From is undefined, then the starting period of the case search will be Days days before today. Passing a value for From will define the starting period of the search and will take precedence; definition of the starting period using Days will then be ignored.

If no parameter is defined for Days and From then the starting period is today.

The Until parameter can define the end of the search period, so that only cases received between the starting period and on or until the date defined by the Until parameter will be returned. Cases received on the date defined by Until parameter can be returned if the starting period allows them to. You do not need to include an Until parameter if you are authenticating the request with an authentication token; if the Until parameter hasn’t been included in the request, then cases that were received between the starting period ( as defined by From or Days ) and today’s date will be returned.

If the parameter values relating to Days and From and Until are undefined; then only cases received today will be returned.

If the request is being authenticated using the Key/Signature method, then you need to also define the value for Until as a parameter of the request; otherwise you will receive a HTTP 403 forbidden request response.

To only return relevant cases in the response, additional parameters can be defined; so that only cases that meet the criteria of the request are to be returned.

Request Method

GET or POST

API service endpoints

UAT: https://uatportal.icasework.com/getcases?db=[youriCaseworkAccount]
eUAT / Production system: https://[youriCaseworkAccount]portal.icasework.com/getcases

Your iCasework account name will be supplied to you by your iCasework Account or Project Manager (see worked example below).

Request parameters and alternative authentication

The example below shows a typical GetCases API call that has been authenticated using the Key/Signature method.

When calling the service, you can authenticate using our signature based authentication method or with an authentication token; when using authentication token based authentication, it is not necessary to include a Key or Signature parameters in the request.

The signature hash required to authorise the call is based on the combination of the relevant secret key for the chosen Key parameter, along with the Until date parameter in XML format, appended in the order (Until date + secret key), then hashed using MD5 encoding. If the Until is not passed in the request; then the signature is an MD5 hash of today’s date in XML format + the secret associated with the API key defined in Key .

Example API call:

https://uatportal.icasework.com/getcases?db=demo&Key=e8c1e866f9b2w59d1d1a8d2f7&Signature=d164312de5ce37869760770f75981265&Type=InformationRequest&From=2016-09-01&Until=2016-09-21

NAME	Description	Example value	Required?

NAME	Description	Example value	Required?
Key	A valid API key set up in your case management system	8b9a7b4b6567ee449dff949db	No
Signature	If the `Until` parameter is passed in the request; then the signature is an MD5 hash of `Until` date in XML format + the secret associated with the API key defined in `Key` e.g. MD5(2016-03-048b9a7b4b6567ee449dff949db) if the value of `Until` is “2016-03-04” If the `Until` is not passed in the request; then the signature is an MD5 hash of today’s date in XML format + the secret associated with the API key defined in `Key`	45000101e5a442775da3cbc6f4bd7030	No
CaseId	Only return cases that have a matching Case ID to this value	9924133	No
ExternalId	Only return cases that have a matching external ID	XR1223333	No
Type	Only return public cases that are of this type; not passing a parameter will return all publicly available cases. Ask your iCasework support representative for the value to use to return cases of a specific type.	IR10163	No
Format	Controls the output format of the API. Options are "xml" or "json"; if no parameter is defined then the response will be output in XML format. If the format of the response is to be xml then it is also possible to return the response in an XSL stylesheet format.	xml	No
XSL	If the `Format` parameter is not equal to “json” then the response can be returned as an XSL sheet; you should pass the name of the XSL sheet to use for the transformation of XML. There is an XSL sheet on your system, called “CSV”, that you can use to transform the XML response and receive the data in a CSV format.	CSV	No
Days	Can define the beginning period with respect to todays date; an integer value is expected, which would represent X days before today. If I wanted to request the details of cases returned 40 days before today, then you would pass “30” as the value of this parameter; if the request was made on 2023-10-02, then only cases received on or since 2023-09-02 would be returned	30	No
From	The beginning of the time period in XML date format, defining the earliest received date of cases to be returned in the response, e.g. `2016-05-01` will only return cases that were received on or after May 1^st2016	2012-05-01	No
Until	The date until when you want a list of cases, in XML date format, e.g. 2016-03-04	2016-03-04	No
Classification	If passed, this will be used to restrict the output to only include cases with this classification.	“CAMHS”	No
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.	“ReceiptDate”	No
Keywords	Specify a keywords to filter on, so that only cases with the keyword appearing in the case’s label or case’s details; or where the keyword has been indexed as the value of at least one of the case’s reportable attributes; or the keyword is one of the case’s classifications will be returned	“urgent”	No
fromseq	Used to control pagination of the request, e.g. fromseq=0 will start displaying the results from the beginning of the full set returned	“3”	No
toseq	Used to control pagination of the request, e.g. toseq=10 will stop displaying the results at the 11th record (counting 0) of the full set returned	“10”	No

Example

Request

<https://example.icasework.com/getcases>

[
    {
    "Type": "IR10163",
    "Days":"300"
    "Until":"2023-02-11"
    "Order":"ReceiptDate"
    "Classification":"CAMHS"
    "Format":"json"
    }
]

<?xml version="1.0" encoding="UTF-8" ?>
<root>
  <row>
    <Type>IR10163</Type>
    <Days>300</Days>
    <Until>2023-02-11</Until>
    <Order>ReceiptDate</Order>
    <Classification>CAMHS</Classification>
  </row>
</root>

<?xml version="1.0" encoding="UTF-8" ?>
<root>
  <row>
    <Type>IR10163</Type>
    <Days>300</Days>
    <Until>2023-02-11</Until>
    <Order>ReceiptDate</Order>
    <Classification>CAMHS</Classification>
    <XSL>CSV</XSL>
  </row>
</root>

Response

[
    {
        "CaseId": "9924133",
        "CaseType": "Freedom of Information request",
        "CaseLabel": "FOI - x",
        "ExternalId": "1223333",
        "ContactMethod": "Online Form",
        "ExternalId": "1223333",
        "DateReceived": "2023-01-23",
        "TimeCreated": "2023-01-23T15:11:33",
        "Status": "All information sent (closed)"
    },
    {
        "CaseId": "9923149",
        "CaseType": "Freedom of Information request",
        "CaseLabel": "FOI - x",
        "ContactMethod": "Online Form",
        "DateReceived": "2023-01-19",
        "TimeCreated": "2023-01-19T12:55:47",
        "Status": "All information sent (closed)"
    },
    {
        "CaseId": "9923148",
        "CaseType": "Freedom of Information request",
        "CaseLabel": "FOI - test10",
        "ContactMethod": "Online Form",
        "DateReceived": "2023-01-19",
        "TimeCreated": "2023-01-19T12:55:40",
        "Status": "All information sent (closed)",
        "Rating": "Standard"
    },
    {
        "CaseId": "9923346",
        "CaseType": "Freedom of Information request",
        "CaseLabel": "FOI - x",
        "ContactMethod": "Email",
        "DateReceived": "2023-01-19",
        "TimeCreated": "2023-01-19T12:49:09",
        "Status": "All information sent (closed)",
        "Rating": "Standard"
    },
    {
        "CaseId": "9923339",
        "CaseType": "Freedom of Information request",
        "CaseLabel": "FOI - c",
        "ContactMethod": "Online Form",
        "DateReceived": "2023-01-19",
        "TimeCreated": "2023-01-19T12:47:53",
        "Status": "All information sent (closed)",
        "Rating": "Standard"
    },
    {
        "CaseId": "9923134",
        "CaseType": "Freedom of Information request",
        "CaseLabel": "FOI - x",
        "ContactMethod": "Online Form",
        "DateReceived": "2023-01-19",
        "TimeCreated": "2023-01-19T12:44:45",
        "Status": "All information sent (closed)",
        "Rating": "Standard"
    },
    {
        "CaseId": "9923033",
        "CaseType": "Freedom of Information request",
        "CaseLabel": "FOI - x",
        "ContactMethod": "Online Form",
        "DateReceived": "2023-01-19",
        "TimeCreated": "2023-01-19T12:37:55",
        "Status": "All information sent (closed)",
        "Rating": "Standard"
    }
]

<?xml version="1.0" encoding="UTF-8"?>
<Cases>
    <Case>
        <CaseId>9924133</CaseId>
        <Type>Freedom of Information request</Type>
        <Label>FOI - x</Label>
        <RequestMethod>Online Form</RequestMethod>
        <ExternalId>1223333</ExternalId>
        <RequestDate>2023-01-23T15:11:33</RequestDate>
        <Status>All information sent (closed)</Status>
        <Attributes>
            <AdviceAndAssistance />
            <Details />
            <Foicaselabel />
            <Overrideemailaddress />
            <PublishInTheDisclosureLog />
            <RequestIsAbout />
            <Scheme />
            <SuitableForPublicationScheme />
        </Attributes>
        <Classifications>
            <Classification Group="CCG">CAMHS</Classification>
        </Classifications>
        <Documents>
            <Document Name="R (1).jfif" Type="image/jpeg">
                <![CDATA[https://uat.icasework.com/servlet/servlets.getImg?ref=7525901&bin=Y&auth=0&db=MS7p3CJj3hg3qw60COJljQ%3D%3D&access_token=V9rmxUIFWFVQ996Vs_fC8HksjVfI_doqWkhV7BYbnLoRotZosPAaSdOHW7CEFHol.PCF9aTNt-juvdeKSICfdKw%3D%3D]]>
            </Document>
            <Document Name="Screenshot 2023-08-24 170034" Type="image/png">
                <![CDATA[https://uat.icasework.com/servlet/servlets.getImg?ref=7534133&bin=Y&auth=0&db=MS7p3CJj3hg3qw60COJljQ%3D%3D&access_token=Yo-gvTHieistxL38MoWuvHJRQajBECHHsb2vRnaglLlyH5v0KNQNjbiqwX5-T_H8.J9cWARfrOIOXKbLUft94yA%3D%3D]]>
            </Document>
        </Documents>
    </Case>
    <Case>
        <CaseId>9923149</CaseId>
        <Type>Freedom of Information request</Type>
        <Label>FOI - x</Label>
        <RequestMethod>Online Form</RequestMethod>
        <RequestDate>2023-01-19T12:55:47</RequestDate>
        <Status>All information sent (closed)</Status>
        <Attributes>
            <AdviceAndAssistance />
            <Details />
            <Foicaselabel />
            <Overrideemailaddress />
            <PublishInTheDisclosureLog />
            <RequestIsAbout />
            <Scheme />
            <SuitableForPublicationScheme />
        </Attributes>
        <Classifications>
            <Classification Group="CCG">CAMHS</Classification>
            <Classification Group="CCG">EUR</Classification>
        </Classifications>
        <Documents />
    </Case>
    <Case>
        <CaseId>9923148</CaseId>
        <Type>Freedom of Information request</Type>
        <Label>FOI - test10</Label>
        <RequestMethod>Online Form</RequestMethod>
        <RequestDate>2023-01-19T12:55:40</RequestDate>
        <Status>All information sent (closed)</Status>
        <Attributes>
            <AdviceAndAssistance />
            <Details />
            <Foicaselabel />
            <InformationHeldByThirdParty />
            <InformationWillBe />
            <MarketingMaterials />
            <Overrideemailaddress />
            <Proposedresponse />
            <PublishInTheDisclosureLog />
            <RequestIsAbout />
            <Requestor-ValidId />
            <Scheme />
            <SuitableForPublicationScheme />
        </Attributes>
        <Classifications>
            <Classification Group="CCG">CAMHS</Classification>
        </Classifications>
        <Documents />
    </Case>
    <Case>
        <CaseId>9923346</CaseId>
        <Type>Freedom of Information request</Type>
        <Label>FOI - x</Label>
        <RequestMethod>Email</RequestMethod>
        <RequestDate>2023-01-19T12:49:09</RequestDate>
        <Status>All information sent (closed)</Status>
        <Attributes>
            <AdviceAndAssistance />
            <Details />
            <Foicaselabel />
            <InformationHeldByThirdParty />
            <Overrideemailaddress />
            <PublishInTheDisclosureLog />
            <RequestIsAbout />
            <Requestor-ValidId />
            <Scheme />
            <SuitableForPublicationScheme />
        </Attributes>
        <Classifications>
            <Classification Group="CCG">CAMHS</Classification>
        </Classifications>
        <Documents />
    </Case>
    <Case>
        <CaseId>9923339</CaseId>
        <Type>Freedom of Information request</Type>
        <Label>FOI - c</Label>
        <RequestMethod>Online Form</RequestMethod>
        <RequestDate>2023-01-19T12:47:53</RequestDate>
        <Status>All information sent (closed)</Status>
        <Attributes>
            <AdviceAndAssistance />
            <Details />
            <Foicaselabel />
            <InformationHeldByThirdParty />
            <Overrideemailaddress />
            <PublishInTheDisclosureLog />
            <RequestIsAbout />
            <Requestor-ValidId />
            <Scheme />
            <SuitableForPublicationScheme />
        </Attributes>
        <Classifications>
            <Classification Group="CCG">CAMHS</Classification>
        </Classifications>
        <Documents />
    </Case>
    <Case>
        <CaseId>9923134</CaseId>
        <Type>Freedom of Information request</Type>
        <Label>FOI - x</Label>
        <RequestMethod>Online Form</RequestMethod>
        <RequestDate>2023-01-19T12:44:45</RequestDate>
        <Status>All information sent (closed)</Status>
        <Attributes>
            <AdviceAndAssistance />
            <Details />
            <Foicaselabel />
            <InformationHeldByThirdParty />
            <Overrideemailaddress />
            <PublishInTheDisclosureLog />
            <RequestIsAbout />
            <Requestor-ValidId />
            <Scheme />
            <SuitableForPublicationScheme />
        </Attributes>
        <Classifications>
            <Classification Group="CCG">CAMHS</Classification>
        </Classifications>
        <Documents />
    </Case>
    <Case>
        <CaseId>9923033</CaseId>
        <Type>Freedom of Information request</Type>
        <Label>FOI - x</Label>
        <RequestMethod>Online Form</RequestMethod>
        <RequestDate>2023-01-19T12:37:55</RequestDate>
        <Status>All information sent (closed)</Status>
        <Attributes>
            <AdviceAndAssistance />
            <Details />
            <Foicaselabel />
            <InformationHeldByThirdParty />
            <InformationWillBe />
            <MarketingMaterials />
            <Overrideemailaddress />
            <Proposedresponse />
            <PublishInTheDisclosureLog />
            <RequestIsAbout />
            <Requestor-ValidId />
            <Scheme />
            <SuitableForPublicationScheme />
        </Attributes>
        <Classifications>
            <Classification Group="CCG">CAMHS</Classification>
        </Classifications>
        <Documents />
    </Case>
</Cases>


"CaseId","ExternalId","Type","Customer.Name","Customer.Id"," Agent.Name"," Agent.Id","RequestMethod","RequestDate","Status","DueDate","CaseWorker.Name","CaseWorker.Phone","CaseWorker.Email"
"9924133","1223333","Freedom of Information request","","","","","Online Form","2023-01-23","All information sent (closed)","","","",""

HTTP 400 responses

X-Application-Error-Code	X-Application-Error-Info	Troubleshooting tips

X-Application-Error-Code	X-Application-Error-Info	Troubleshooting tips
9000	Invalid HTTP Method.	Check the HTTP method; this should be a GET or POST
9001	Invalid period requested.	If `From` has been passed then check that it is in YYYY-MM-DD format. If `Until` has been passed then check that it is in YYYY-MM-DD format. If `Days` has been passed then check that it is an integer.

HTTP 403 responses

X-Application-Error-Code	X-Application-Error-Info	Troubleshooting tips

X-Application-Error-Code	X-Application-Error-Info	Troubleshooting tips
9021	Incorrect key or signature	Check the `Key` and `Signature` of the request
9021	Invalid token (6)	Check the authentication token is valid

getcases