FOIAXpress Request Data API Guide

Introduction

FOIAXpress provides a Request Data API, which allows Request data to be retrieved for use in other applications. Users can define criteria for which requests they need information about, and receive either a count of how many requests meet the criteria or a list of the field data from the Requests meeting the customized filter criteria.

There are some restrictions on which fields can be used for filters and what field data can be retrieved. These details are provided in the following sections.

In This Document

This document is divided into the following sections:

• Configuration: Enabling the API in your application.

• Authentication: Establishing a session.

• GetRequestCount: Details on the GetRequestCount API, which returns a count of requests based on specified conditions.

• GetRequests: Using the GetRequests method, which retrieves one or more field values from FOIAXpress requests.

Configuration

To enable the API, add the following to your web.config file in the <system.webServer>

section:

NOTE: You can exclude one or more of these entries if you are not planning to use the method. For example, if only using the GetRequestCount method, only GetApiToken and GetRequestCount are required.

<location path="apiex/RequestData/GetApiToken">
<system.web>
<authorization>
<allow users="*" />
</authorization>
</system.web>
</location>
<location path="apiex/RequestData/GetRequestCount">
<system.web>
<authorization>
<allow users="*" />
</authorization>
</system.web>
</location>
<location path="apiex/RequestData/GetRequests">
<system.web>
<authorization>
<allow users="*" />
</authorization>
</system.web>
</location>
<location path="apiex/RequestData/CreateRequest">
<system.web>
<authorization>
<allow users="*" />
</authorization>
</system.web>
</location>
<location path="apiex/RequestData/GetRequestStatus">
<system.web>
<authorization>
<allow users="*" />
</authorization>
</system.web>
</location>
<location path="apiex/RequestData/UploadDocuments">
<system.web>
<authorization>
<allow users="*" />
</authorization>
</system.web>
</location>
<location path="apiex/RequestData/UpdateRequest">
<system.web>
<authorization>
<allow users="*" />
</authorization>
</system.web>
</location>

Authentication

Before calling other methods, the application needs to establish a session using the ApplicationURL/apiex/requestdata/GetApiToken method. This can be any user account with the appropriate permissions, but as a best practice we recommend using a unique account created for the application accessing the API. The body of this request should be:

{
"UserName": "Example", "Password": "Example"
}

The method returns an empty string if successful, and an error if it does not create a session for the user due to invalid credentials, etc.

GetRequestCount

This API method, located at ApplicationURL/apiex/requestdata/getrequestcount, returns an integer value that represents a count of requests in FOIAXpress based on one or more “where” conditions. GetRequestCount accepts a JSON parameter in the following format:

{
“WhereClauseFields”: []
}

WhereClauseFields is an array containing WhereClauseField objects. A WhereClauseField is defined as:

{
"FieldName": "",
"Operator": "",
"Value": ""6
}

Supported Fields

The following Request fields are supported as the FieldName property:

Operator Property Values

The operator property allows you to specify what requests will be counted by the method. The Operator property can use the following values:

Supported Operators By Field

Not every field supports the use of every operator. The following table shows which operators are usable for each field and includes definitions for Request Status codes:

Example JSON Object

Here is an example of a JSON object that could be used with this API method:

{
"WhereClauseFields": [
{"FieldName": "RequestTypeName", "Operator": "=", "Value": "FOIA"},
{"FieldName": "ReceivedDateFrom", "Operator": ">=", "Value": "01/01/2020"},
{"FieldName": "RequestStatus", "Operator": "=", "Value": "Closed"}
]
}

Here is an example of this input tested in Postman™:

By passing an empty array, the user can get a count of every request in the application:

The following example shows the “IN” operator in use:

The following example shows the “CONTAINS” operator in use:

GetRequests

GetRequests is located at ApplicationURL/apiex/requestdata/getrequests, and allows users to get one or more field values from requests in FOIAXpress. This API method accepts a JSON object in the following format:

{
"StartRow": "",
"EndRow": "",
"SortBy": "",
"Columns": [""],
"WhereClauseFields”: []
}

Definitions

The elements in the GetRequest method are described in the following table:

Examples

The following is an example of a GetRequest method:
{
"StartRow": 1,
"EndRow": 1000,
"SortBy": "VisibleRequestId",
"Columns": ["VisibleRequestId", "RequestStatus"], "WhereClauseFields": [
{"FieldName": "RequestTypeName", "Operator": "=", "Value": "FOIA"}
]
}

An example of a response to this request might look like:
[
{
"VisibleRequestId": "20-FOI-00012", "RequestStatus": "Closed"
},
{
"VisibleRequestId": "20-FOI-00013",
"RequestStatus": "Closed"
},
…
]

Here is an example of what this input might look like when tested in Postman™:

Similar to GetRequestCount, passing an empty WhereClauseField array returns all the requests (up to the EndRow specified):

Here’s an example where “SortBy” is not applied: