MiCOURT REST API Overview

The MiCOURT REST API provides developers access to court and case data for courts that have a JIS case management product. The following information provides an overview of some of the key concepts and instructions for interacting with the API.

Terms of Use

{coming soon}

API Reference

Our APIs are organized around REST principles. While this document attempts to cover the basics that are specific to our API, we expect that you have some familiarity with REST concepts and understand how to consume a web service.

Requests & Responses

The MiCOURT REST API attempts to use appropriate HTTP verbs for each request action:

HTTP Method	Description
GET		Request to retrieve resources
POST		Request to create resources
PATCH		Request to update resources
PUT		Request to replace resources

For the responses, we use standard HTTP response codes. Response codes in the 2xx range generally indicate a successful request, codes in the 4xx range indicate a problem with the request, and codes in the 5xx range indicate a problem on our end. JSON is returned by all API responses (including errors).

HTTP Status Code		Description
200 OK				Request has succeeded
201 Created			Request has succeeded and resulted in a new resource being created
400 Bad Request			Request has failed and should be modified
401 Unauthorized		Request failed user/client authentication
403 Forbidden			Request was understood but is being refused
405 Method Not Allowed		Method specified in the request is not allowed for this resource
500 Internal Server Error	Server encountered an unexpected error

Errors

In instances where a 4xx or 5xx is returned, the response body will contain additional details for use in troubleshooting what went wrong.

{
	"type": A URI reference that identifies the problem type
	"title": A short, human-readable summary of the problem type
	"detail": A human-readable explanation specific to this occurrence of the problem
	"status": The HTTP status code for this occurence of the problem
}

Linking

The MiCOURT REST APIs use URL links to reference self resources and related resources. This allows developers to build URL's for additional resources based on the results returned. Our technique for denoting hypertext references is to append "Link" to a field name. Here is an example from the Case resource:

{
	"self": "/case-product/v3/1/cases/2019-1234567-OM", 
	"kind": "Case", 
	"caseDocketId": "2019-1234567-OM", 
	... 
	"participantsLink": "/case-product/v3/1/cases/2019-1234567-OM/participants", 
	... 
	"judgeLink": "/person-product/v3/1/professionals/12345/judge"
}

Authorization

All endpoints in the MiCOURT REST API require client authorization. That means that in addtion to a subscription key, you'll also be required to send an OAuth2 access token in your request header. This token is obtained from the MiCOURT Identity provider and is described in the Authorization Token section below.

Subscription Key

In order to make an API request, you'll need to subscribe to a package. That package subscription is associated to your MiCOURT developer account and represents your permission to call an API. When you subscribe to a package, a subscription key will be generated. That key will be included in each request in the Jis-Api-Subscription-Key request header.

To get a subscription key, visit the Packages page and choose a package. To get started, select the Starter package (which doesn't require approval, but has limited functionality). Review the terms of service and select Subscribe. If you've chosen one of the non-Starter packages, you'll receive an email notification when your request is approved.

You can find the subscription key in your developer profile.  You'll see that there are two subscription keys provided for each package subscription. You are free to use either in your API requests. While JIS does not mandate key rotation, it is a good security practice to rotate and regenerate keys on a regular basis. So if you are using the primary key, you can switch to using the secondary key, regenerate the primary key, and then switch back to the new primary key at the next rotation interval. You can regenerate those keys yourself within your developer profile.

Authorization Token

The MiCOURT REST API uses the OAuth2 client credentials grant type to authorize API requests. That means that a bearer access token must be provided in the Authorization request header in every request. To obtain that token, you'll need to make a call to the MiCOURT Identity token endpoint, providing your client_id and client_secret.

You'll be given your client_id and client_secret after you register an application and request access to court data. Once approved, JIS will generate and associate court claims to those credentials.

To request an access token, make a POST request tohttps://login.courts.michigan.gov/connect/token with anapplication/x-www-form-urlencoded Content-Type request header and the following request body:

client_id={your client ID}&client_secret={your client secret}&grant_type=client_credentials

The response body will contain the token details:

{
	"access_token": {token},
	"expires_in": {number of seconds token is valid},
	"token_type": "Bearer",
	"scope": {list of scopes}
}

Use the access_token value in the Authorization header in your API requests.

Permissions

The access token that you generate with your client credentials will have certain policies (permissions) associated with it. These policies are required in order to run certain API resources. These permissions are configured by JIS.  They are:

Policy			Description
Case Read		Read case information
Case Write		Create and edit case information
View Suppressed		View non-public cases
View Adoption		View adoption cases

API Flow

Many of the APIs that return case data are specific to a court or set of courts. In order to perform requests on those operations, you'll need to obtain a court key. The court key is a numeric key that represents either a single court tenant (location) or a set of court tenants. Some GET endpoints allow for court keys with multiple court tenants, but all POST endpoints require a court key that has a single court tenant (so it knows where to put the data).

To obtain a court key, use the Court API's courtkeys resource. Make a POST request to that resource and provide a single court tenant or a list of court tenants in the body. If successful, the response will contain the court key.

If you use a court key with multiple tenants and the resource you are attempting to use does not allow for performing an action against multiple court tenants, then you will receive a 400 Bad Request.