Table of Contents

API Specification for U.S. Courts

Version 1.10
Released: August 2013
Last Updated: August 2022


This documentation describes an API for accessing data from US courts, including from PACER.


What is a docket?

Court cases are organized into “dockets.” A new docket is created when a person sues another, files for bankruptcy, is prosecuted for a crime, or appeals a judgment. The docket is a list of public documents in the case. Every time a document is submitted to the judge, the document appears on the court “docket.” Every time the judge issues an order, it also appears on the docket. Typical cases have anywhere from a few docket entries to several thousand.

A docket entry usually consists of a date, a short summary, and a PDF file. Below is an example of a docket entry:

Docket Entry

The docket entry above contains a date, a document with filing number 459, a PDF attachment, and a summary. Note that the summary may contain HTML formatting.

What does the Docket Alarm API do?

Docket Alarm provides a single unified REST API to hundreds of US courts (including PACER), to retrieve docket metadata and the associated PDF court filings. By providing a single API and response schema, your application can access data from hundreds of courts with one API.

The API supports legal automation, research, and alerting workflows. There are over 675M tagged court dockets and OCRed PDF documents, with internal text searchable. Read more about boolean query support here. Motion analysis (motion type/outcome/importance) is available, contact for details on obtaining additional value-added metadata.

Docket Alarm’s connection to the USPTO (PTAB/TTAB, TSDR, PAIR), allows for automating IP portfolio analysis and other prosecution/litigation related workflows. See a full listing of available jurisdictions here.

Why You Need This API

The Docket Alarm API is quite powerful and customizable, but for many users, it’s overkill. We receive many inquiries about our API for projects that can be solved with a standard Docket Alarm subscription. The guidelines below can help you decide if your organization really needs access to the API, or can suffice with a standard Docket Alarm subscription.

Feel free to reach out to to get more information.

Docket Alarm Website Docket Alarm API
Business Development Use the website to create dozens of client lawsuit alerts. Use the API to create hundreds of client lawsuit alerts, especially if they are changing often.
Synchronizing Court Data Use the website to manually synchronize cases with your internal systems. Use the API to automatically synchronize cases with e.g., SharePoint, Filesite, iManage, Foundation, OpenText, etc.
Custom Dashboards Use the website if you need a beautiful dashboard for law firms and clients. Use the API to create truly bespoke interfaces that includes only the specific data that matters to your practice.
Legal Analytics Use the website for prebuilt analytics or the Analytics Workbench for customized analytics. Use the API only in very unique circumstances.
Bulk Downloads Use the website to download hundreds of documents. Use the API If you need to download many thousands or millions of court records.
Custom App Development N/A Use the API if you are building a custom app.
Confidential Data Analysis N/A Use the API if your project requires analyzing privileged information, together with public records.
Something New Many of our API users (most?) are doing things that no one has ever done before in the legal field. If you have a new idea that requires court data, the Docket Alarm API may be able to help.

Docket Alarm Enhance: a simpler tool for data professionals

Docket Alarm offers additional big-data tools that may be more suited for your challenge.

Docket Alarm Enhance is a spreadsheet processing system. Send a spreadsheet or csv with a list of cases or company names, and Enhance sends back an updated spreadsheet with more details embedded. Start an Enhance job with an online uploader or emailing the spreadsheet to a special generated email address (automation is possible via e-mail forwarding rules).

Docket Alarm Enhance was intended for folks that wanted to process a good deal of data, but do not want to jump fully into an API. It is perfect for jobs of less than 20,00 dockets/companies.

Learn more about Docket Alarm Enhance here.

Getting Started and Libraries

The following is the typical flow of API calls:

  • Log into the Docket Alarm API with login/.
  • Run a full-text-search for dockets or documents with search/.
  • (Optional) Search PACER directly for dockets with searchpacer/.
  • Update a docket with fresh court information with getdocket/.
  • Retrieve PDF documents associated with the docket.
  • Setup docket tracking with track/.
  • Receive API push notifications of docket updates.

Docket Alarm provides a python client library and a sample test program to help you get started. If you are developing in python, it is highly recommended that you look to that library first when developing your application.

The source code and corresponding documentation is available here:

Quickstart Sample Code

Below is a quick Python 2/3 code snippet that finds recent cases where Doordash or Uber were sued, and prints out the 3 most recent dockets.

# We'll use the json library to decode the responses.
import json
# Helpful for printing.
import pprint
# There are many python libraries for downloading API data (Requests,
# urllib3, etc.). Below, we import the built-in python `urllib` routines and
# use the six library for Python 2 and 3 compatibility.
from six.moves.urllib.request import Request, urlopen
# A python helper function used to turn dictionaries into url-encoded requests.
from six.moves.urllib.parse import urlencode
# All API calls start with this URL
base_api = ""

# Login: calls to login/ require a POST request, so "data= ... user/pass ..."
req = Request(base_api + "login/", data = urlencode({
    'username' : 'YOUR_EMAIL',
# Make the HTTP request.
response = urlopen(req).read()
# Convert the JSON response into python dictionary
json_response = json.loads(response)
# If there's a problem logging in, `success` is False and `error` has a
# description (e.g., bad password).
if not json_response['success']:
    raise Exception("Cant login to Docket Alarm API: " + json_response['error'])
login_token = json_response['login_token']

# Search: calls to search/ are a GET, so use query param encoding "?q=..."
req = Request(base_api + "search/" + "?" + urlencode({
    # The login token from the previous call
    'login_token' : login_token,

    # A research note or internal matter number, useful for tracking.
    'client_matter' : 'first-api-search-test',

    # The query below searches for dockets where Doordash or Uber were sued.
    # The query language is powerful, and can do a number of fielded searches.
    # Detailed documentation is below, you can also test queries on the website.
    'q' : 'party:(name:(door-dash OR uber) type:defendant) is:docket',

    # Newest first (also try -date_last_filing, random, or blank for relevance).
    # Note: The query language supports additional date filters for precise bucketing.
    'o' : '-date_filed',

    # Offset and limit allow for paging through results. You can get up to 50 at
    # a time, and offset up to 1000. After that, use date bucketing or scroll api.
    # The settings below get the first 3 results.
    'offset' : 0,
    'limit' : 3,
# Make the request. In production, wrap with a try/except to handle errors.
search_response = json.loads(urlopen(req).read())
# Print out the total count. This is the total number of results, which may be
# much higher than the limit of 3.
print("Search found " + str(search_response['count']) + " results")

# Loop over the results
count = 0
for result in search_response['search_results']:
    count += 1
    print("Getting Result " + str(count) + " for: " + result['title'] +
        ", " + result['docket'] + " " + result['court'])

    # The getdocket/ request uses GET, so again use "?"
    req = Request(base_api + "getdocket/" + "?" + urlencode({
        # Same login token as before
        'login_token' : login_token,

        # Another research/billing/client code of your choice.
        'client_matter' : 'first-api-getdocket-test',

        # The court name and docket number from the search result:
        'court' : result['court'],
        'docket' : result['docket'],

        # Important: You have a choice of pulling Docket Alarm's most recent
        # copy of the docket, or getting an update directly from the court.
        # If you set cached=True, you will get Docket Alarm's copy.
        # Setting cached=False (or leaving it blank), will contact the court to
        # retrieve an updated docket sheet. For Federal cases, PACER fees apply
        # for pulling updated docket sheets (no other courts charge for this).
        'cached' : True,
    docket_response = json.loads(urlopen(req).read())
    # Take a look at the docket.

Unexposed and Deprecated Features

Docket Alarm is capable of more features than those exposed in the API. Some unexposed features in the documentation are noted below. If you require unexposed functionality, or any other functionality, reach out to us and ask. We welcome all feedback on requested features.

Also, from time-to-time, we may deprecate certain functionality of the API for technical or business reasons. When an API endpoint is deprecated, it is accessible, but will be removed from a future release. Accordingly, users should not use deprecated API functionality. If you are using deprecated API functions that you need, let us know.

Please send questions and comments to

Recent API Changes

Unless otherwise noted, all changes are backwards compatible. Feel free to contact us about any specific changes.


Happy to publicly introduce the motion analysis API! Now, for cases filed in Federal court, the Docket Alarm API provides detailed motion tags, based on the docket entry text. Fields include the type of motion, the outcome of the order resulting from the motion, timing information, and links to SALI compliant codes.

The introduction of this data into the API mirrors related new features including pleading tags and recently added motion analytics in federal courts.

Jump down to the docs to view more details.


Add middle_name to the searchpacer/ endpoint.

Add more documentation to quick code snippet.

On Feb. 14, PACER changed their backend API. Their new API offered no significant new features, but is better organized and maintainable.

The searchpacer/ endpoint uses this PACER backend API. Both the PACER and by extension the Docket Alarm API now support separate first_name and last_name fields when searching for individuals.

January Add claims to the getdocket endpoint. This field is only available in select courts, but is useful for a high level overview of the case.
December Add an optional client_matter field to the search endpoint.
October Add the embed/create endpoint. You can now share pages on Docket Alarm with users that do not have a Docket Alarm account.
August Add the link_direct field to the docket entry dictionary.
July Add the link field to the related cases dictionary.
June Add the disposition field to the getdocket/ endpoint. This new field is only available in several state courts, and Federal district courts for an additional PACER fee.
Add the pacer_summary_page option to the getdocket/ endpoint. When this option is set, we will pull the PACER summary page as well as the docket report. This adds the disposition field, but costs an extra $0.10.
May Clarify documentation re 302 responses for documents.
Clarify documentation re push notifications. Add the test_track feature, useful for testing push notifications.
March Add the patents field to the getdocket/ endpoint. This endpoint is useful for anyone doing patent litigation analysis.
January Take _beta_use_last_filing_date out of beta. It still works, but use_last_filing_date is now preferred.
December Fairly major update: add the new searchdirect/ endpoint, that allows searching directly on a court's internal system. This provides up-to-date-search results across all state and agency courts covered by Docket Alarm.
Expose the fields lead and prose for attorneys.
Add quickstart python code..
June Add the normalize parameter to the getdocket/ endpoint to get normalized names of firms and parties.
April Add examples in java and python to the search/ endpoint documentation.
March Add datetime_cached to the getdocket/ and search/ endpoint.
January Add datetime_updated to the track/ endpoint.
Add related cases to docket report.
Clarify documentation regarding Content-Type header.
August Clarify docs on the filing number
Improve Single-Sign-On so it works with the API
Add link to track/ endpoint
Add the judges parameter to support multiple judges in a case. Deprecate the judge value.
July Document Single-Sign-On for group accounts.
June Send the client matter number when doing an API push.
March Add documentation on error handling and search sort order.
January Fix a bug pertaining to party names in Bankruptcy dockets.
October Return case "flags" in the getdocket/ endpoint.

API Conventions

API calls are either GET or POST made to the following base address:


All calls should be made with HTTPS, otherwise login credentials may be intercepted. Unless otherwise noted, all data sent via POST request must be in HTTP form data format with the Content-Type header set to application/x-www-form-urlencoded.

Return Values

Calls to most endpoints always return a HTTP 200 message and a JSON body. All JSON responses have the following parameters:

 success true or false.
 error If success is false, this describes the error.

When successfully retrieving a PDF document, a 200 Response is returned and the body is the binary PDF file. When unsuccessful, the response may be 403 and JSON will be returned as the body.

Also note that all dates that are returned are in the form mm/dd/yyyy (e.g., '02/08/2012') and all parameters which contain dates must be submitted in the same format.

API Versions

Whenever we increase an API point version number (e.g., 1.0 to 1.1), all changes are backwards compatible. That means that a Docket Alarm API client written for 1.0 will always work for version 1.1, 1.2, etc.

When we increase major version numbers (e.g., 1.0 to 2.0) we may break compatibility with prior API versions. However, when we do so, we will also change the endpoint URL and we may continue to support the older API versions.


Certain API calls may incur fees. To reduce costs while testing, we have provided a test-bed system that returns fake data. To use the test system, add the parameter test to each GET or POST request. You will not be charged when using this parameter.

Note: You only need to include the test parameter to put the API in test mode, i.e., you do not need to give it a value.

Testing Push Notifications

Push notifications are only sent when there is a new item that posts to the docket. You can test push notifications with fake data by making a POST call to track/ and adding test as a parameter.

How to Setup a Test Account

To access test data, you do not need a paid Docket Alarm account, you just need a login email and password. To create an account, go to, select "Signup", and enter a username and password. You will be presented with a payment form, but you can ignore that. The test API is already enabled on your account.

Retrying Failed Requests

In several API calls below, Docket Alarm contacts the court to request refreshed information. The connection to the court systems can fail due to regular maintenance, heavy court server load, or a CAPTCHA failure. We recommend that you implement a retry and backoff system when making requests to Docket Alarm's API, and limit your request rate to these endpoints.

For reference, the API endpoints that may contact the court are: searchdirect/, getdocket/ with cached set to false, and pulling documents.


All requests to the Docket Alarm API must be authenticated with a valid Docket Alarm username and password. If you do not have a Docket Alarm account, create one at You will need a credit card or your PACER credentials to download PACER documents.

There are two methods of authentication. You may choose either based on what is most convenient and secure for your needs:

Temporary Token

With this method, you send your username and password to the login/ endpoint and receive a temporary token that is used in later requests. This is documented directly below.

HTTP Basic Auth

Alternatively, you may submit your username and password on each request using HTTP Basic Authentication. Consult your system's documentation on how to submit HTTP Basic Auth.

Note: Even when using HTTP Basic Auth, some endpoints require a blank login_token.

To obtain a temporary token, send a username and password to the login/ endpoint and obtain a login_token. The login_token must then be used in all subsequent requests. The login_token is active for 90 minutes, after which a new call to login must be made.

POST Parameters

 username The username associated with the Docket Alarm account.
 password The password associated with the username.

Return Values

If the username or password is invalid, an error will be generated. Otherwise, it will return:

 login_token A token, in hexadecimal, valid for the next 90 minutes. This token must be supplied as a GET parameter for all future API calls.


A successful login request and response.




	'success': true

Types of Searching

There are two ways of searching court records on Docket Alarm: search Docket Alarm's database, or use Docket Alarm as an intermediary to search a court directly. One method may be preferred to the other in various circumstances.

Search Docket Alarm

Docket Alarm has been retrieving court records for many years, and has built one of the largest databases available, with over 675M dockets and documents (Aug. 2022). We index these records in a variety of ways, and allow you to use a unified search system to perform full text as well as complex fielded searches. Docket Alarm offers more powerful searching, with higher data limts, than any court system provides.

To search Docket Alarm, use the search/ endpoint.

The limitation of searching Docket Alarm's database is that it relies on Docket Alarm to have already pulled in the data. We pull down an enormous number of records, but sometimes you may need further customization on our own update schedule. In these cases, cases, you'll want to search courts directly.

Searching Courts Directly

Docket Alarm provides another means of searching: searching courts directly. In this case, Docket Alarm connects to the court, and makes a request on your behalf. It then returns the results in a standardized format.

The difficulty with searching courts directly is that each court has its own set of search options, update schedule, request rate limit, and in some cases cost. This API provides a unified interface to the otherwise haphazard system of searching state and agency courts.

The direct search APIs are divided into two:

  • searchpacer/: For searching PACER / Federal courts.
  • searchdirect/: For searching everything else.

The two endpoints deliver very similar data, but they are split into two because as of Dec. 2020, the searchpacer/ can incur additional court fees whereas searchdirect/ cannot.

Summary Chart

When integrating with the API, you must decide whether you want to search Docket Alarm or use Docket Alarm to search the court directly.

Search within Docket Alarm.
searchpacer/ and searchdirect/
Use Docket Alarm to search the court system directly.
Cost No additional cost. Can incur fees if the court imposes them for searching, we pass them to your account at cost. Currently, only searchpacer/ has a fee at $0.10 for each page of search results. These fees may or may not be passed on at cost depending on your arrangement.
Coverage Everything on Docket Alarm. Dockets and documents. Everything on Docket Alarm. Generally, dockets only.
Completeness Very comprehensive results, but not guaranteed complete. New cases are added daily, and old cases are updated on regular schedules. As comprehensive as the court's own filing system.
Search Options A variety of search and sorting options, full text, fielded, boolean, etc. Limited number of search options, only those provided by the court.
Speed Fast. Searches complete in 1 to 5 seconds. Slow. Searches can take 30-60 seconds.

Search Docket Alarm

As of March 2023, Docket Alarm has more than 732 million records in its database, making it one of the largest such databases available. Searching on Docket Alarm is fast and easy, and is the preferred search option unless you have specific requirements.

The search/ endpoint searches every docket and document on Docket Alarm.

GET Parameters

 login_token The authentication token.
 q The url encoded query you are searching for. The query can be as simple as a keyword, but supports many additional options and filters.

All major options are documented here.
 o Specifies the result order. Valid values are:
  • Blank: Search by relevance, which considers matching keywords, court level, and recentness.
  • date_filed: oldest first by docket/document filing date.
  • -date_filed: newest first by docket/document filing date.
  • date_last_filing: order dockets by the date of the most recent entry listed on the docket ascending.
  • -date_last_filing: order dockets by the date of the most recent entry listed on the docket descending.
  • random: random order (good for sampling);
 limit The number of results to be returned (50 max).
 offset The offset into the search results to be returned. Note that offset plus limit must be less than 1000.
 client_matter (Optional) An optional client matter number to be associated with the search. The field appears in your usage history, which can be helpful for administrative purposes.
(Optional) Advanced parameters for scrolling through thousands or millions of search results efficiently and in parallel. See below for details.

Return Values

 search_results A list of dictionaries where each dictionary is specified in the following section.
 count The number of search results.
 scroll See above for scroll documentation.


Each search result is a JSON dictionary object with the following key value pairs

 result_type Results may contain both dockets or documents. This value will be set to docket if the search result is a docket, or document if it is a document. In the future, Docket Alarm may serve other types of results (e.g., statutes, people, companies). Users should try to anticipate these changes.
 court The name of the court handling the case.
 docket The case docket.
 title The title of the case if the result is a docket, or the title of the document if it is a document.
 link A URL to the full docket or document on Docket Alarm.
 link_viewer If the result is a document, this link will be to Docket Alarm's web based document viewer.
 filename If the result is a document, this value will contain a nicely formatted filename for the document.
 date_filed The date the case / document was filed.
 date_cached (Advanced) The date the docket sheet was last pulled. Only set if result_type is docket.
 datetime_cached (Advanced) The date and time the docket sheet was last pulled in ISO 8601 format. Timezone is UTC. Only set if result_type is docket.
 cache_unofficial (Advanced) If the cached docket was pulled from an unofficial source (e.g., Govenment Printing Office, PACER RSS feeds). Only set if result_type is docket.

Note: even though search results do not return snippets, we provide a separate undocumented API for creating them. Contact support for more details.

Example Code Snippet

Below is a bit of code that will search for trademark dockets involving the company 3M.

Python Code

import urllib
import json

# Create all the GET arguments
get_args = {
    # Generate the login token using the login endpoint described above.
    'login_token': '',
    # This is the query that is used to run the search
    'q': 'is:docket party:(3M) type:trademark',
    # Limit to 20 results at a time
    'limit': 20,
    # Start with the first result.
    'offset': 0,
    # Newest cases first.
    'o' : '-date_filed',
# URL Encode all of the arguments together
get_args_encoded = urllib.urlencode(get_args)
# Append to search endpoint
full_url = '' +  get_args_encoded

# Execute the API command
fp = urllib.urlopen(full_url)
# Read its contents
contents =
# Decode the contents from JSON into a python dictionary.
json_contents = json.loads(contents)

# Print the output

Java Code

import java.util.HashMap;
import java.util.Map;

public class Main {
  public static void main(String[] args) throws MalformedURLException,
                                   UnsupportedEncodingException, IOException {
        // Create all the GET arguments
        Map<String, String> get_args = new HashMap<String,String>();
        get_args.put("login_token", "");
        // This is the query that is used to run the search
        get_args.put("q", "is:docket party:(3M) type:trademark");
        // Limit to 20 results at a time
        get_args.put("limit", "20");
        // Newest cases first.
        get_args.put("o", "-date_filed");

        // Start with the base url
        String base_url = "";
        // We will add parameters
        String encoded_params = "";
        // using for-each loop for iteration over Map.entrySet()
        for (Map.Entry<String, String> entry : get_args.entrySet()) {
            // URL Encode the value.
            String v = URLEncoder.encode(entry.getValue(), "UTF-8");
            encoded_params += "&" + entry.getKey() + "=" + v;
        // Combine the base url with the encoded values
        URL url = new URL(base_url + encoded_params);
        // Print out the generated URL
        System.out.println("Encoded API URL: " + url);
        // Create the HTTP Request
        HttpURLConnection con = (HttpURLConnection)url.openConnection();
        // Make the request and
        try(BufferedReader br = new BufferedReader(
          new InputStreamReader(con.getInputStream(), "utf-8"))) {
            StringBuilder response = new StringBuilder();
            String responseLine = null;
            while ((responseLine = br.readLine()) != null) {
        // Print out the generated URL
        System.out.println("API Response: " + response);
        // You will want to parse the JSON with a library like GSON

Scrolling Results

If your application requires scrolling through more than 1000 results, you must use the scroll API. This API can be somewhat complex, so if possible, you should divide your search results into chunks smaller than 1000 results and use the normal search API.

If you need to scroll through many thousands or millions of records efficiently, the scroll API can help. It also supports parallel searches allowing you to make multiple requests at once.

1. Scroll API - Setup

To use the API, you must first decide how many parallel requests you want to use to scan through results. This will be scroll_parallel. If don't want to do requests in parallel, set to 1.

Then, make scroll_parallel number of search requests. The requests take the same paramaters as a normal search, but you must also include two new parameters: scroll_parallel, set to the number of parallel requests. In addition, scroll_index, corresponding to the request number, ranging from 0 to scroll_parallel-1.

2. Scroll API - Scrolling

After each of the setup requests complete, the result will contain a list of results just like the normal search command, but will also include an additional field called scroll. This field's value contains state about the search.

For each of your parallel requests, take the previous result scroll and pass it into the next requests, along with the other parameters scroll_parallel and scroll_index. The scroll values may vary from request to request, always use the last one.

The following parameters should be added to your request to search/:

 scroll_parallel number of parallel threads, or bins, to divide the search results into for scanning (scroll_parallel = 1 means no parallelism). Choose scroll_parallel to be large enough that the resulting threads do not exceed 5000 search results. This is used in the first search using advanced parameters for scrolling.
  scroll_index individual thread, or bin, of the scroll_parallel threads (indexed from 0 to scroll_parallel-1); This is used in first search using advanced parameters for scrolling.
  scroll string produced for each thread when first setting scroll_index and scroll_parallel; outputted as another field with key “scroll.” Pass this value into all subsequent calls as the parameter scroll, without setting parameters scroll_index, scroll_parallel, or offset. With each refresh of this call, more cases will load. Note that each thread will have a different scroll value and the scroll value will change with each call of scroll_index and scroll_parallel.

Example of Scrolling with 3 Parallel Threads

This example uses three requests that can be run in parallel (i.e., you don't need to wait for one to complete to start the next). The first 3 requests set things up (and also return results):


If successful, the result will be (abbreviated):

  "count": 355,
  "search_results": [{ ... }, ...],
  "success": true,
  "scroll": "DnF1...="

  "count": 355,
  "search_results": [{ ... }, ...],
  "success": true,
  "scroll": "DnF2...="

  "count": 355,
  "search_results": [{ ... }, ...],
  "success": true,
  "scroll": "XS12...="

Subsequent requests will include the scroll parameter returned by the first. You do not need to include scroll_parallel or scroll_index on subsequent requests.


Search PACER

Search for PACER dockets using the searchpacer/ endpoint.

Blank GET Request

If no GET parameters (besides the required login_token and client_matter) are supplied, we return a dictionary with information that can be helpful to this search method:

 courts A list of PACER courts serviced by this endpoint.
 court_regions A list of valid court regions that you can use in a GET request below.
 nature_of_suits A list of nature of suit (NOS) codes that you can use in a GET request below.
 case_types A list of case type codes that you can use in a GET request below.

GET Parameters

 login_token The authentication token.
 client_matter The client or matter code used to bill the particular search. Max length is 50 characters.
 party_name (Optional) Company name to search, also searches individual's last names.
 first_name (Optional) Individual's first name (cannot use party_name).
 middle_name (Optional) Individual's middle name (cannot use party_name).
 last_name (Optional) Individual's last name (cannot use party_name).
 nature_of_suit (Optional) A list of strings, where each string is a nature of suit code specified below in Appendix B. The search results will be limited to the nature of suits specified.
 date_filed_start (Optional) Limits results to cases filed on or after the given date.
 date_filed_end (Optional) Limits results to cases filed on or before the given date.
 date_terminated_start (Optional) Limits results to cases terminated on or after the given date.
 date_terminated_end (Optional) Limits results to cases terminated on or before the given date.
 page (Optional) Page through results by specifying a page number. Before jumping to a page, the search must be run at least once.
 court_region (Optional) Limits results to cases filed in the given region. See Appendix A for valid values.
 docket_num (Optional) Limits results to cases filed with the given docket number. You should only use this field if you know the docket number, but do not know the court name.
 case_type (Optional) Limit search results to a particular case type. Acceptable values are: Appellate, Bankruptcy, Civil, Criminal, and Multi-District Litigation. Leaving no value will search all case types.
 mdl_id (Optional) Search for a particular Multi-District Litigation by MDL ID number. The case_type parameter must be set to Multi-District Litigation.
 ssn_tid (Optional) The nine digit social security number or Federal tax identification number of a party to the lawsuit. The case_type parameter must be set to Bankruptcy.
 ssn4 (Optional) The last four digits of the social security number of a party to the lawsuit. The case_type parameter must be set to Bankruptcy and party_name must be provided.

Return Values

 search_results A list of dictionaries where each dictionary is specified in the following section.
 page_max Only 50 search results are returned per search. If there are more items, then this variable will be set to the number of pages containing data.

Warning, known issue with page_max: If there are thousands of results, and you are requesting the first page, then page_max may be under-reported. As a workaround, only rely on page_max for pages 2 and above.


Each search result is a JSON dictionary object with the following key value pairs

 title The title of the case
 court The name of the court handling the case.
 docket The docket title of the case.
 date_filed The date the case was filed.
 link A URL to the full docket on Docket Alarm.
 nature_of_suit (Optional) The nature of the suit code, if one exists (Bankruptcy cases do not have natures of suit).
 date_terminated (Optional) If the case was terminated, this value returns the date.
 party_name (Optional) If party_name was provided in the searchpacer/ call, then this field will provide the full party's name. For example, if searchpacer/ was called with party_name=ebay, then this field may be "eBay, Inc.".
 party_role (Optional) If party_name was provided in the searchpacer/ call, then this field will provide the party's role in the lawsuit (e.g., Plaintiff, Defendant, etc.). See Appendix C for a list of valid values.


Search for cases where Sony is a party:


If successful, the result will be (abbreviated):

	'page_max': 4,
			'title': 'Broadcast Music Inc et al v. Camp Lounge L L C et al',
			'court': 'Louisiana Western District Court',
			'docket': '6:13-cv-01271',
			'party_role': 'Plaintiff',
			'party_name': 'Sony A T V Tree Publishing',
			'date_filed': '5/29/2013',
			'date_terminated': '',
			'link': '',
			'nature_of_suit': '820'
			'title': 'Adaptix, Inc. v. Sony Mobile Communications, Inc. et al',
			'court': 'Texas Eastern District Court',
			'docket': '6:13-cv-00442',
			'party_name': 'Sony Mobile Communications (USA), Inc.',
			'party_role': 'Defendant',
			'date_filed': '5/28/2013',
			'date_terminated': '',
			'link': '',
			'nature_of_suit': '830'
	'success': true

Search Direct

Search state and agency dockets directly with the searchdirect/ endpoint.

Because this endpoint contacts the court directly, it does not rely on Docket Alarm having a copy of the case. However, it is more challenging to use and has fewer search options than the search/ endpoint. This endpoint is analogous to searchpacer/, but for non-PACER courts.

Note: many courts do not have robust servers, and it is common for requests to fail due to high server load or maintenance. Accordingly, users of this endpoint should be prepared to handle errors and retry requests.

There are generally three steps that need to be performed when using this endpoint:

  • GET Request: Return a list of courts that support the searchdirect/ endpoint.
  • GET Request with a court Parameter: Get the required and optional search arguments for searching with the searchdirect/ endpoint.
  • POST Request: Run the search.

Blank GET Request

A blank GET request is used to get the list of courts supported by this endpoint (login_token and client_matter are still required).

Returns a dictionary with a courts parameter, listing every court that is covered by this endpoint.

        'courts': [
            "Supreme Court of the United States",
            "California State Supreme Court",
            "Connecticut State, Supreme Court",
            "Florida State, Supreme Court",
            "Minnesota State, Supreme Court",
            "Nevada State, Supreme Court",
            "Oregon State, Supreme Court",
            "Pennsylvania State, Supreme Court",
            "South Carolina State, Supreme Court",
        'success': true

GET Request

If the court parameter is added, then a structure is returned documenting the required and optional search parameters, and also, allowed values for those parameters.

 required A list of required search arguments.
 optional A list of optional search arguments.
 choices A dictionary specifying which allowed values for an optional or required search argument.

Below is an example call:


And the response:

		"success": True,
		"required": ["court"],
		"optional": ["docketnum", "party_name", "county",
					 "court_office", "date_filed_start", "date_filed_end",
		"choices": {
			"max_pages": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15,
						  16, 17, 18, 19, 20, 21, 22, 23, 24, 25],
			"county": [null, "Adams", "Allegheny", "Armstrong", "Beaver",
					"Bedford", "Berks", "Blair", "Bradford", "Bucks",
					"Butler", "Cambria", "Cameron", "Carbon", "Centre",
					"Chester", "Clarion", "Clearfield", "Clinton",
					"Columbia", "Crawford", "Cumberland", "Dauphin",
					"Delaware", "Elk", "Erie", "Fayette", "Forest",
					"Franklin", "Fulton", "Greene", "Huntingdon",
					"Indiana", "Jefferson", "Juniata", "Lackawanna",
					"Lancaster", "Lawrence", "Lebanon", "Lehigh",
					"Luzerne", "Lycoming", "McKean", "Mercer", "Mifflin",
					"Monroe", "Montgomery", "Montour", "Northampton",
					"Northumberland", "Perry", "Philadelphia", "Pike",
					"Potter", "Schuylkill", "Snyder", "Somerset",
					"Sullivan", "Susquehanna", "Tioga", "Union",
					"Venango", "Warren", "Washington", "Wayne",
					"Westmoreland", "Wyoming", "York"]},

POST Request

A POST request to this endpoint must specify all of the required search parameters to perform the search.

The result is returns a dictionary with an entry search_results, a list of dictionaries. Each dictionary in search_results has the following format:

 title The title of the case
 court The name of the court handling the case.
 docket The docket title of the case.
 date_filed The date the case was filed.
 link A URL to the full docket on Docket Alarm.

Retrieving a Docket

Download a case's docket information using the getdocket/ endpoint.

GET Parameters

 login_token The authentication token.
 client_matter The client or matter code used to bill the particular search. Max length is 50 characters.
 court The name of the court, obtained from search/, searchpacer/ or a push notification.
 docket The docket identifier, obtained from search/, searchpacer/ or a push notification.

(Optional, but important) The cached parameter.

Use the cached parameter to specify whether to retrieve the docket from the Docket Alarm cache or from the court system directly.

Docket Alarm has a copy of every case. If cached is set to true getdocket/ will retrieve Docket Alarm’s most recent copy of the docket sheet. The docket sheet contains the field datetime_cached, the time the docket was last pulled directly from the court.

When false, or when omitted, getdocket/ will retrieve the newest docket information directly from the court. Retrieving information directly from the court can take more time, and Federal Courts may impose PACER fees to pull a case, depending on its size.

 normalize (Optional) If true, normalize judges, party names, law firm names, and attorney names. If false, the normalized names are omitted. Current default setting is false, but that may change in the future. Note that although our normalization logic has been heavily tested, it is not perfect.
use_last_filing_date (Optional, Advanced) Only relevant to PACER-based dockets. Used to reduce PACER fees. We reduce PACER fees by relying on the most recent filing date on the docket, which we can get for free. Thus if there are no new filings, we can check the docket for free. However, if an existing docket entry is modified (rather than a new filing added), then the docket won't be updated. If there are new filings, then the docket will be pulled normally and a PACER fee will be incurred. This feature is useful if you only care about new filings and need to reduce PACER fees.
pacer_summary_page (Optional, Advanced) Only relevant to PACER-based dockets. For PACER dockets, for an extra $0.10 charge, we can pull the Summary page, which has the disposition field. This field will be added to the info in the result. Note that the fee may be up to $3.00 if the summary is very large.

Return Values

 info A dictionary containing information about the case. The values of this dictionary are described in the section below.
 docket_report A list of docket entries. Each entry is described in the section below.
 parties A list of parties to the case. Each is described in the section below.
 related A list of related cases, each a dictionary described below. Relationships depend on the jurisdiction and availability of underlying court data. To view cases with relationships, run a relationship search.
 claims A list of "claims" (also, charges, causes of action) in a case. Currently supported in several courts (e.g., NLRB, FL Palm Beach, FL Orange County, CA Sacramento, among others). To view cases with claims, run a claim search.


 title The title of the case.
 date_filed The date the case was filed.
 link A URL link to a web page that shows the entire docket report.
 judges (Optional) A list of one or more judges presiding over the case.
 judges_normalized (Optional) A list of one or more normalized judges presiding over the case. Returned if normalized is set.
 judge (Deprecated) The judge presiding over the case. Supported for backwards compatibility, but judges should be used instead.
 magistrate (Optional) The magistrate judge presiding over the case. Currently only available in Federal cases.
 nature_of_suit (Optional) The nature of the suit code. See Appendix B for valid values.
 type (Optional) The case type. This field is not available for federal cases. Case types vary from court to court and are not normalized.
 patents (Optional) A list of strings indicating patent numbers involved in this suit. Currently, this field works for PTAB cases, as well as Federal Court cases where Docket Alarm has already accessed the complaint (which generally contains all of the patents in suit).
 status (Optional) The case status. This field is not available for federal cases. Case statuses vary from court to court and are not normalized.
 division (Optional) Certain courts can have a sub-court field, which is specified here.
 date_terminated (Optional) If the case was terminated, this value returns the date that it was terminated.
 demand (Optional) The type of demand made by the plaintiff. Currently only available in Federal cases.
 cause (Optional) The cause of action. Currently only available in Federal cases.
 flags (Optional) A list of case flags, usually each flag is all capitals, but not necessary. Currently only available in Federal cases.
 disposition (Optional) Case disposition. This field is available in a number of state courts, and is also available for Federal District courts for an additional PACER fee (see pacer_summary_page above).
 date_debtor_discharged(Optional) Bankruptcy dates, deadlines, and dispositions. Only available in bankruptcies, and some, none, or all may be present depending on the state of the bankruptcy. The values is_asset and is_voluntary are boolean true/false.
 date_cached (Optional) (Advanced) If cached was set, this is the cache update date.
 datetime_cached (Optional) (Advanced) If cached was set, this is the cache update date and time in ISO 8601 format. Timezone is UTC.
 cache_unofficial (Optional) (Advanced) If cached was set, and we did not obtain this docket from an official source, then this will be true.


Each entry in a docket_report is a dictionary with the following key-value pairs:

 contents The html contents of the docket entry. The html is scrubbed for potentially dangerous tags and only innocuous style related tags are returned. For example:
Unopposed MOTION to Continue <i>Jury Trial</i> by Marcelino Ahumada Vargas (Tarver, Christophe) (Entered: 09/02/2010)
 date The filing date of the docket entry, e.g., 10/26/2010.
 entry_date The date the document was entered into PACER. This date is often the same day as the filing date, but can be later, occasionally much later, as well.
 number (Optional) If the docket entry has a document associated with it, then it may also be given a filing number. Filing numbers are returned as a string. In Federal Courts, these strings will represent an integer, but state courts may contain non-numeric values (e.g., "Motion-1").
 link (Optional) If the docket entry has a document associated with it, then this link will point to the location of the PDF file.
 link_viewer (Optional) If the docket entry has a document associated with it, then this link will point to the location of a file in Docket Alarm's web viewer.
 link_direct (Optional, Beta) If the docket entry has a document and the court supports directly linking to documents, this will return a link to the document on the court's system. Currently only supported in NY State dockets. As a beta feature, we reserve the right to remove this field in the future.
 exhibits (Optional) A list of exhibits that are associated with the docket entry, not including the main filing.

Each exhibit in the list is a dictionary with the keys:
 exhibit A string representing the exhibit number or name. This number will uniquely identify the exhibit from other exhibits associated with this filing.
 link A link to the exhibit PDF.
 link_viewer A link to the exhibit displayed in Docket Alarm's web viewer.
 link_direct (Optional, Beta) If the court supports directly linking to documents, this will return a link to the document on the court's system. Currently only supported in NY State dockets. As a beta feature, we reserve the right to remove this field in the future.
 analyze (Optional) An additional dictionary of analysis results. All fields/values in this dictionary are the result of analysis performed by Docket Alarm, not from the court directly.

Note: This field may not be included in every API license. Contact sales ( for more information.


A list of dictionaries, each with motions/orders identified by parsing the docket entry.

We do not claim to capture every single motion with full fidelity, but we err on the side of accuracy.

The keys/values of the dictionary are:

 type A high level procedural tag, one of the following (with corresponding icon):
  • motion
  • order
  • pleading
  • reply
  • response

A string representing a procedurally substantive identifier of the motion/order. Each identifier is tied to a data dictionary, that includes the full motion name, categories, a "priority" level, and a link to the equivalent SALI code.

The data dictionary in available in several formats:

Note: identifiers can be "children" of other identifiers (e.g., "disqualify" is parent of "disqualify_counsel").

Note: identifiers can be ambiguous, e.g. motion to limit claims. A tooltip is also provided in the data dictionary explaining ambiguity.

 outcomes A list of string outcomes. Each string one of: denied granted . In many cases, the outcome may be unknown.
When type is order, and where we can identify relationships between docket entries, timing fields are available.
  • Days sequence is the entire motion order sequence.
  • Days decision is the time from the last responsive brief to the order.
  • Days briefing is the time from the first opening brief, to the last responsive brief.
 related A list of dictionaries that contain references to other docket entries. The index being the list index into the docket_report and the number being the filing number.
 snippet Short text snippet highlighting relevant motion language.
 confidence Confidence value of very_low, low, medium, high, and very_high.


The following is an example of a single docket entry within a docket_report with analyze:

	"number": "335",
	"date": "6/18/2021",
	"entry_date": "6/18/2021",
	"contents": "ORDER granting in part and denying in part 240 Defendant's Motion for Summary Judgment",
	"exhibits": [],
	"link_viewer": "",
	"link": "",
	"analyze": {
		"parser_types": [{
			"type": "order"
			"identifier": "summaryjudgment",
			"confidence": "very_high",
			"outcome": [
			"related": [{
				"index": 350,
				"number": "240"
			"days_sequence": 141,
			"days_briefing": 35,
			"days_decision": 106,
			"snippet": "ORDER granting in part and denying in part 240 Defendant's Motion for Summary Judgment",

Excerpt of data dictionary corresponding to a summaryjudgment identifier:

	"success": true,
	"type": ["motion", "order", "pleading", "reply", "response"],
	"identifier": {
		"summaryjudgment": {
			"sali_identifier": "",
			"name": "Motion for Summary Judgment",
			"ambiguous": false,
			"sali_link": "<>)",
			"name_display": "Summary Judgment",
			"types": ["motion", "order", "response", "reply"],
			"can": {
				"analytics": true,
				"sequence": true,
				"search": true
			"parent": null,
			"priority": 10,
			"category": ["Dispositive", "Judgment"]

See /api/v1/parser/ or equivalent excel for complete data dictionary.


 name The name of the party to the case.
 name_normalized The normalized party name. Returned if normalized is set.
 type The type of party to the case, e.g., Plaintiff, Defendant, etc. See Appendix C for a list of valid values.
 counsel If attorney information is available for a party, then this field will contain a list of attorneys representing the party. Each attorney is represented with a counsel dictionary structure described below.


The counsel data structure contains information on the attorney representing the party. It includes the attorney’s name, law firm, role in the case, and contact information. The fields are as follows:

 name The lawyer’s name.
 firm The lawyer’s law firm.
 name_normalized The normalized lawyer’s name. Returned if normalized is set.
 firm_normalized The normalized lawyer’s law firm. Returned if normalized is set.
 email Their email address.
 phone Their phone number.
 address An array containing the attorney address, each array entry corresponding to a line in the address.
 lead True if the attorney is marked as the lead attorney in the case. Most courts do not distinguish between lead attorneys.
 prose True if the attorney is acting as pro-se counsel. Courts do not always use this field, but when set to true, it can be relied upon.


A list of cases related to this docket sheet. Each related case is a dictionary with the following fields:

 type (Optional) The type of relationship. Relationships include "Original Case", "Related Case", "Lead Case", "Orange Book", "2(d) Rejection", among others. Contact support to get an updated list of relationships.
 court (Optional) The court of the related case.
 docket (Optional) The docket of the related case.
 title (Optional) The title of the related case.
 link (Optional) The link to the docket on Docket Alarm.

Note: You can search and filter cases based on the relationship field as well. For example, searching
related:(type:(Original Case) court:(New York)) will find cases that are appealed from a New York court.


A list of claims made by the plaintiff/entity bringing the action. Each claim is a dictionary with the fields below.

Most courts do not support the claims field, to see a list of supported cases, run a search for claim:"".

 type The type of claim made. Currently, the only type supported is a charge, which indicates a criminal or administrative charge made against an entity. Future API releases may include other types (e.g., civil causes of action).
 description (Optional) A description of the claim.
 code (Optional) The statutory/regulatory code that correlates to this claim.
 disposition (Optional) If disposition data is available, then it will be in this field.
 date (Optional) If the claim date is available, then it will be in this field.
 id (Optional) The claim ID number, sometimes referred to as a charge count (e.g., count 1: theft; count 2 resisting arrest, etc.). Available in court systems that specify a claim ID. Is usually an integer, but is delievered as a string.


Here is a case in the Southern District of New York:


If successful, the result will be (abbreviated):

	"info": {
		"title": "Kickstarter, Inc. v. Fan Funded, LLC et al", 
		"date_filed": "09/30/2011", 
		"magistrate": null, 
		"nature_of_suit": "830 Patent", 
		"judge": "Judge Katherine Polk Failla"
	"parties" : [
			"type": "Defendant", 
			"name": "Fan Funded, LLC",
			"counsel": [
				  "firm": "Steptoe & Johnson, LLP (DC)", 
				  "name": "Michael Jarrett Allan", 
				  "phone": "202-555-3000", 
				  "email": ""
				  "firm": "Steptoe & Johnson, LLP (NYC)", 
				  "name": "Evan Glassman", 
				  "phone": "212-555-3900", 
				  "email": ""
			"type": "Plaintiff", 
			"name": "Kickstarter, Inc."
	"docket_report": [
			"link": "", 
			"entry_date": "9/11/2014", 
			"date": "9/11/2014", 
			"contents": "	DECLARATION of Matthew Ambros & William Seymour in ... ",
			"exhibits" : [
				"link": "",
				 "exhibit" : "1"
				"link": "",
				 "exhibit" : "2"
			"link": "", 
			"entry_date": "9/6/2013", 
			"date": "9/6/2013", 
			"exhibits" : []
			"link": null, 
			"entry_date": "9/6/2013", 
			"date": "9/6/2013", 
			"exhibits" : []
			"link": null, 
			"entry_date": "8/16/2013", 
			"date": "8/16/2013", 
			"contents": "Minute Entry for proceedings held before Judge Katherine Polk Failla: ...",
			"exhibits" : []
	"success": true

Retrieving a Document

Retrieving documents with a GET request. The URL for the request is the value link (see the getdocket/ section) in a docket entry. The URLs are relative to Docket Alarm’s hostname.

Rather than returning JSON, the call returns the binary PDF document.

Additional GET parameters include:

 login_token The authentication token, see the authentication section above.
 client_matter (Optional) The client or matter code used to bill the particular document. Max length is 50 characters.
 cached (Optional) Sometimes you may not want to contact the court to get a document, either because there is a fee for accessing the document, or because it takes longer to do such a download. By adding this parameter, you can choose to only download the document if it was previously downloaded and therefore guarunteed accessible.


If the link in the docket entry is as follows:


Then the document may be downloaded with the following call:


To download the document only if it was previously downloaded:


If there are no errors, the result should be a binary PDF document.

Errors and Sealed Documents

If there is an error downloading the document, then the API will return a status code other than 200 and a JSON response in the body. The JSON body will a dictionary with success set to false and error set to a corresponding error message.

Below is a table of HTTP response codes and their meaning. Check the error field for more information:

 200 Success. The body should be the PDF, not a JSON object.
 302 Redirect, the document moved. This occurs when we need to change link formats. The correct location for the document will be specified in the Location header field. Be sure to add the login_token when following the redirect.
 401 An issue with logging in. Check your login_token.
 403 The document is sealed or unavailable. Judges may seal documents even though they are listed on the docket sheet. In addition, sometimes documents are listed on the docket sheet and only available days later, because they need to be reviewed or redacted. In either case, if the court has not yet made the document available, we will raise a 403.
 404 We could not find this document within the docket, double check the document link.
 412 You specified the cached parameter but the document was not available in Docket Alarm's cache.
 500 Likely a bug with the API, contact support.
 502 Our servers are under heavy load and cannot respond to your request. Our system automatically spins up new servers when under heavy load, but sometimes it takes a few seconds for us to spin them up.

Tracking Cases

You may configure the API to send notifications of new case activity on a court docket. By default, these notifications are emailed, but you may also configure the API to send them to a server of your choosing (see Push Notifications below).

There are two types of requests you can make to the track/ endpoint, a GET request (to get the tracking status) or a POST request (to change tracking status).

GET Request

A GET request to the track/ endpoint returns the tracking status of one or more dockets. It takes the following parameters:

 login_token The authentication token.
 offset (Optional) The offset into the user's trackers (default 0).
 limit (Optional) The maximum number of trackers to return (default 25, max 50).

GET Request Result

If the request was successful, a dictionary will be returned. One dictionary entry will be dockets, which is a list of dictionaries in the form:

 court The court name.
 docket The docket id number.
 title The case title.
 link The relative url to the tracked docket sheet or search.
 enabled If tracking is enabled for this docket, returns true, otherwise false.
 frequency If tracking is enabled, frequency will be either 'twice_daily' or 'weekly'. If not enabled, this value is undefined.
 client_matter The client or matter code used to bill this docket tracker if enabled is true.
 datetime_updated The date and time, in ISO 8601 format, of when the docket was last updated, e.g., 2020-01-17T20:57:14.648000. Timezone is UTC.
 _api_push_debug_info If this case has ever attempted to make an API push, then this structure will be a dictionary as specified in "Debugging API Push" below.

Warning: This field should only used for debugging, and is not subject to our versioning policy above. Use this only as a manual debugging tool, but do not incorporate it into any automated system as it may be removed without notice.
 date_filed (Not exposed) The date when this case was first filed. We don't always have this information.

GET Example

An example of requesting tracking status:


If successful, the result will be:

	  "dockets": [{
		  "court": "California Northern District Court", 
		  "docket": "3:14-cv-03985"
		  "title": "Telesocial Inc. v. Orange S.A. et al", 
		  "enabled": false, 
		  "frequency": "twice_daily", 
		  "datetime_updated": null,
		  "court": "Patent Trial and Appeal Board", 
		  "docket": "IPR2016-00291", 
		  "title": "Inter Partes Review of U.S. Pat. 5,732,375", 
		  "enabled": false
		  "frequency": "weekly", 
		  "datetime_updated": "2020-01-17T20:57:14.648000",
	  "success": true

Debugging API Push

The _api_push_debug_info that is returned by the track/ endpoint can help you debug API push calls.

 response_code The response code of our last API push.
 request_url The API push URL of our last API push.
 request_payload The full payload of our API push.
 request_payload_truncated The truncated payload of our API push (currently the first 16kb).
 will_retry Set to true if we will be attempting another API push retry.
 error_message Additional information about the error that may be helpful.

POST Request

Use a POST request to the track/ endpoint to (1) create a new tracker, (2) modify an existing tracker, or (3) simulate a push notification for testing.

 login_token The authentication token.
 court Court name, obtained from search/, searchpacer/ or a push notification.
 docket Docket number, obtained from search/, searchpacer/ or a push notification.
 enable Set to true to enable docket tracking, set to false to disable it.
 q (Optional) Used to create search trackers. These are different from standard docket trackers because they do not contact the court, they just run the search/ endpoint internally and report new search results. If q is set, then the values of court and docket must be blank. See the corresponding section for push notifications.
 client_matter The client or matter code used to bill this docket tracker if enabled is true. Max length is 50 characters.
 frequency A tracking frequency, can be one of the following:
dailyOnce a day at 8AM ET.
twice_daily2x/day at 7AM and 4PM ET.
continuousA popular alert, 16x/day during and after business hours to capture late filers. Roughly at 1AM, 3AM, 9AM, 10AM, 11AM, 12PM, 1PM, 2PM, 3PM, 4PM, 5PM, 6PM, 7PM, 8PM, 9PM, 11PM.
weeklyOnce a week on Mondays.
monthlyOnce a month, first of the month. Currently no way to set the day of month via API.
40xOur "day trader" alert. Forty updates a day, roughly every 15 minutes, mostly during day trading hours, disabled on most accounts by default.
realtimeApplies to special ECF alerts that do not require polling. Not available in most cases.
 day_of_week (Unexposed) If frequency is set to weekly, this field may be used to set which day of the week the Docket Alarm checks the court docket.
 test (Optional) Test an API push with fake data. If set, all of the other parameters are ignored/unecessary. Useful for running quick tests to make sure your API endpoint is working properly.
 test_track (Optional) Synchronously test an API push for a specific case or search tracker. When this parameter is set to true, we'll push a notification to your endpoint for the tracker specified by the court/docket or q parameters. The track will not be updated/edited. The push notification will contain the most recent set of results.

POST Request Result

There are no special return values for this HTTP request. As with all calls to the Docket Alarm API, if the request was successful, the success parameter will be true. Otherwise, success will be false and error will return an error message.

POST Example


The result will be:

	'success': true,

Receiving Push Notifications

Docket Alarm can send push notifications when it detects a new court event. There are several types of events:

  • New Docket Item: Sent when a new case docket event is detected on an existing case. These alerts can be created via the API. See POST track.
  • New Search Result: Sent when a new search result is detected. Used to detect new lawsuits, or new documents across many cases. These alerts are customizable, and can be created via the API. See POST track.
  • New PACER Case: This is a specialized alert for PACER nature of suit codes. These alerts are setup via the UI, under "New Case Alerts --> Federal District". These alerts cannot be created via the API.

Whenever any of the events above is triggered, Docket Alarm sends a HTTP POST request to a URL endpoint. To setup a notification endpoint, email us and we'll set it up for you. Alternatively, you may use the subaccount/ endpoint to setup notification URLs via the API.

The JSON payload of the push notifications depends on the notification type, and is described in the sections below.

Retry Handling

When we send a push notification, we expect a 200 valid response. If there is a problem sending the push notification (we receive a non 200 status message), we retry up to 10 times with an exponentially longer delay: the minimum retry time being 10 minutes and the longest 4 hours.

Debugging / Testing Push Notifications

To simulate an API push, use the test_track or test parameters in part of a POST to the track/ endpoint. See track/ for further documentation.

To see the status of recent notifications, use the track/ endpoint, and read the value of _api_push_debug_info. You can test push notifications to make sure they are properly setup.

New Docket Item

 push_type Will always be set to docket.
 client_matter Will be the value specified when setting up the tracker.
 court The court name.
 docket Docket number.
 info A dictionary containing basic information about the case, not including the docket and parties. See info.
 docket_report A list of the new docket entries only. Older docket entries are not sent. The docket entry object is described in the docket_report section.
 parties A list of parties to the case. See parties.

New Search Result

These notifications are created using the track/ endpoint with the q parameter. When a new result is detected, we will send the following:

 push_type Will always be set to search_results.
 client_matter Will be the value specified when setting up the tracker.
 q The query that was run.
 link A relative link to the search results.
 title A human readable description of the search.
 search_results A list of new results. Each is a dictionary defined in the search_results section.

New PACER Case

 push_type Will always be set to new_case.
 client_matter Will be the value specified when setting up the tracker.
 party_name The name of the party searched, if one was specified.
 nature_of_suit A list of strings, where each string is a nature of suit specified in Appendix B. The search results will be limited to the nature of suits specified.
 search_results A list of new results. Each is a dictionary defined in the search_results section.


	'push_type': 'new_case',
	'client_matter': 'Best Client',
	'party_name': 'Sony',
	'search_results': [
			'docket': '1:13-cv-22843',
			'nature_of_suit': '840',
			'court': 'Florida Southern District Court',
			'date_filed': '8/8/2013',
			'title': 'Effs v. Sony Pictures Home Entertainment Inc. et al'
			'docket': '2:13-cv-05682',
			'nature_of_suit': '190',
			'court': 'California Central District Court',
			'date_filed': '8/6/2013',
			'title': 'Richard Arons v. Sony Music Entertainment Inc et al'

Sub Accounts

Docket Alarm supports creating sub accounts to your master account with the subaccount/ endpoint. This is helpful if you are developing an application and your users need isolated Docket Alarm accounts. Each sub account has their own email/password login, shows up separately on the monthly receipt, can maintain their own isolated set of case trackers, and can have separate push notification URLs.

Once a sub account is created and linked to a master account, you can log into it like any other Docket Alarm account. When making API calls with a sub account, you must first request the login/ endpoint to retrieve a login_token for that account. Sub accounts cannot have their own sub accounts.

For security reasons, by default, this endpoint is turned off. To have it turned on, email us and request access for your account.

Sub account features are made by GET and POST requests to the subaccount/ endpoint.

GET Request

A GET request to subaccount/ returns information about the currently active sub accounts. The only required parameter is the login_token. The return values are:

 subaccounts A list of dictionaries where each dictionary is specified in the following section.

Sub account Dictionary

Each dictionary in the subaccounts list above has the following fields:

 username The email address of the user.
 name (Not Exposed) The name of the user.
 organization (Not Exposed) The organization of the user.
 api_push_url (Not Exposed) The api_push_url of the user.

POST Request

A POST to subaccount/ can be used to create new accounts or modify existing accounts, and link and unlink them from the master account. The request parameters are:

 login_token The authentication token.
 username The username of the account that you want to create/modify. This username must be a functioning email address on the same domain as the master account. So for example, if the master account's username is, the sub accounts must also be on Sub accounts could not be created such as
 password When creating a new account, this must be the desired account password. When changing account settings, this must be the account password. You cannot change an existing password using the subaccount/ endpoint.
 password_repeat When creating a new account, this must be the desired account password. When changing account settings, this may be omitted.
 enable Set to true to enable this sub account and link it to the master account and false to disconnect the account from the master account. If set to false, any trackers that were previously enabled will be disabled the next time they are due to run.
 name The full name of the person whose account you are creating. This is required when creating a new account, but is otherwise optional. This will be shown to the user when they log into their account.
 organization (Optional) Organization name of the sub account you are creating.
 phone (Optional) Phone number of the sub account you are creating.
 address (Optional) Address of the sub account you are creating.
 city (Optional) City of the sub account you are creating.
 state (Optional) State of the sub account you are creating.
 zip (Optional) Zip of the sub account you are creating.
 api_push_url (Optional) The URL you would like push notifications to be sent to. You may encode HTTP basic authentication into this URL like, for example,

Sub-Account Login - SSO

Docket Alarm supports Single-Sign-On via its API via the subaccount/login endpoint. To login as a user, you must first create the user (using the API or the website), then generate an encrypted login link that you can use as a redirect for the user.

Follow the steps below:

  • Log in to the Docket Alarm API with your master account with the login/ endpoint.
  • Make sure the user you want to login as exists (either with the subaccount/ endpoint described above or using the website interface).
  • Make a GET to subaccount/login with the master account's login_token and the sub account's email address for the username (see below).
  • The subaccount/login endpoint returns a JSON object with a url field.
  • Redirect the user to the url.

Getting the User's Login URL

The subaccount/login endpoint can be made with the following parameters.

 login_token The authentication token of the master account.
 username The username of the sub account that you want to login as.
 redirect (Optional) The relative path where you want the user to login. If not specified, it will send the user to their dashboard.

If the user exists, the response of the call will contain a json object with the items:

 url The URL to send the user. This URL has a special encrypted encoding so that they will be logged in. Be careful sharing this URL, as it allows anyone to login as the user without a password.
 login_token A token that can be used to login as the user in the API. This should not be needed for Single Sign On, but it can be useful if you are doing complex API operations.


A successful sub account login request:


  "url": "",
  "login_token" : "ABCD123...",
  "success": true

The URL in the response can be passed to the user so they can login to their account.

Note: Expiring Login Tokens

The login_token and url are time-sensitive (they expire in 90 minutes). We recommend you use server-side redirection rather than provide the url for the user to click. This avoids the scenario where your site serves the url to the user but they wait several hours before clicking on it, and by this time the link has expired. Server-side redirection will ensure the url is always fresh.

Embedding and Auto-Authentication

You can embed pages in Docket Alarm, allowing users without a Docket Alarm account to view the page. To see examples, and use our embedding UI see our embed page. To create a new embedded link with the API, make a POST request to endpoint: embed/create

POST Parameters

 url The Docket Alarm URL you want to embed.
 title (Optional) Title of the embedded analytics link (appears in history).

Return Values

If the embedded link was submitted properly, you shuold recieve a dictionary with the following:

 link A link that can be shared and viewed by non Docket Alarm users.


To embed the following link:[...]&embed
Use the following curl command:

curl -XPOST \
  -d ""



Appendix A: Court Regions

Below following is a list of valid values to use for regions, which can also be accessed at the endpoint: /api/v1/searchpacer/?login_token=&client_matter=.

  • Alabama
  • Alabama Middle
  • Alabama Northern
  • Alabama Southern
  • Alaska
  • All Regions
  • Arizona
  • Arkansas
  • Arkansas Eastern
  • Arkansas Western
  • California
  • California Central
  • California Eastern
  • California Northern
  • California Southern
  • Colorado
  • Connecticut
  • Delaware
  • District of Columbia
  • Eighth Circuit
  • Eleventh Circuit
  • Federal Circuit
  • Fifth Circuit
  • First Circuit
  • Florida
  • Florida Middle
  • Florida Northern
  • Florida Southern
  • Fourth Circuit
  • Georgia
  • Georgia Middle
  • Georgia Northern
  • Georgia Southern
  • Guam
  • Hawaii
  • Idaho
  • Illinois
  • Illinois Central
  • Illinois Northern
  • Illinois Southern
  • Indiana
  • Indiana Northern
  • Indiana Southern
  • Iowa
  • Iowa Northern
  • Iowa Southern
  • Kansas
  • Kentucky
  • Kentucky Eastern
  • Kentucky Western
  • Louisiana
  • Louisiana Eastern
  • Louisiana Middle
  • Louisiana Western
  • Maine
  • Maryland
  • Massachusetts
  • Michigan
  • Michigan Eastern
  • Michigan Western
  • Minnesota
  • Mississippi
  • Mississippi Northern
  • Mississippi Southern
  • Missouri
  • Missouri Eastern
  • Missouri Western
  • Montana
  • Nebraska
  • Nevada
  • New Hampshire
  • New Jersey
  • New Mexico
  • New York
  • New York Eastern
  • New York Northern
  • New York Southern
  • New York Western
  • Ninth Circuit
  • North Carolina
  • North Carolina Eastern
  • North Carolina Middle
  • North Carolina Western
  • North Dakota
  • Northern Mariana Islands
  • Ohio
  • Ohio Northern
  • Ohio Southern
  • Oklahoma
  • Oklahoma Eastern
  • Oklahoma Northern
  • Oklahoma Western
  • Oregon
  • Pennsylvania
  • Pennsylvania Eastern
  • Pennsylvania Middle
  • Pennsylvania Western
  • Puerto Rico
  • Rhode Island
  • Second Circuit
  • Seventh Circuit
  • Sixth Circuit
  • South Carolina
  • South Dakota
  • Tennessee
  • Tennessee Eastern
  • Tennessee Middle
  • Tennessee Western
  • Tenth Circuit
  • Texas
  • Texas Eastern
  • Texas Northern
  • Texas Southern
  • Texas Western
  • Third Circuit
  • United States Court of International Trade
  • United States Federal Claims Court
  • Utah
  • Vermont
  • Virgin Islands
  • Virginia
  • Virginia Eastern
  • Virginia Western
  • Washington
  • Washington Eastern
  • Washington Western
  • West Virginia
  • West Virginia Northern
  • West Virginia Southern
  • Wisconsin
  • Wisconsin Eastern
  • Wisconsin Western
  • Wyoming

Appendix B: Nature of Suit

The meaning of each nature of suit code is listed below, which can also be accessed at the endpoint: /api/v1/searchpacer/?login_token=&client_matter=.

Code Nature of Suit
110 Insurance
120 Contract - Marine
125 Contract - Affordable Care Act
130 Miller Act
140 Negotiable Instrument
150 Recovery & Enforcement of Judgments
151 Recovery of Medicare
152 Recovery Student Loan
153 Recovery of Veteran Benefits
160 Stockholders Suits
190 Contract - Other
195 Contract - Product Liability
196 Franchise
210 Land Condemnation
212 Tax - Income, Individual
220 Foreclosure
230 Rent, Lease & Ejectment
240 Torts to Land
245 Tort Product Liability
290 Real Property - Other
310 Airplane Personal Injury
315 Airplane Product Liability
320 Assault, Libel & Slander
330 Federal Employer's Liability
340 Marine
345 Marine - Product Liability
348 Military Pay - Reinstatement
350 Motor Vehicle
355 Motor Vehicle Product Liability
360 Personal Injury - Other
362 Medical Malpractice
365 Product Liability
367 Healthcare/Pharmaceutical Personal Injury Product Liability
368 Asbestos
370 Fraud
371 Truth in Lending
375 False Claims Act
376 False Claims Act - Qui Tam 31 U.S.C. 3729(a)
380 Property Damage - Other
385 Property Damage - Product Liability
400 State Reapportionment
410 Anti-Trust
422 Bankruptcy Appeal
423 Bankruptcy Withdrawal
430 Banks and Banking
440 Civil Rights - Other
441 Civil Rights - Voting
442 Civil Rights - Jobs
443 Civil Rights - Accommodations
444 Civil Rights - Welfare
445 Civil Rights - Americans with Disabilities Act - Employment
446 Civil Rights - Americans with Disabilities Act - Other
448 Civil Rights - Americans with Disabilities Act - Education
450 Interstate Commerce
460 Immigration - Deportation
462 Immigration - Naturalization Application
463 Immigration - Habeas Corpus - Alien Detainee
465 Immigration - Other
470 Racketeer/Corrupt Organization
480 Consumer Credit
490 Cable/Satellite TV
492 Injury - Thimerosal
494 Injury - Influenza
509 Taking - Addicks & Barker Reservoirs
510 Prisoner - Vacate Sentence
514 Taking - Other
530 Habeas Corpus
535 Habeas Corpus - Death Penalty
540 Mandamus & Other
550 Prisoner - Civil Rights
555 Habeas Corpus - Prison Condition
560 Prison Condition
610 Agricultural
620 Food and Drug Acts
625 Drug Related Seizure of Property
630 Liquor Laws
640 Railroad and Trucks
650 Airline Regulations
660 Occupational Safety/Health
690 Forfeit/Penalty - Other
710 Labor - Fair Labor Standards Act
720 Labor - Labor Management Relations Act
730 Labor - Reporting & Disclosure
740 Railway Labor Act
751 Family and Medical Leave Act
790 Labor - Other
791 Employee Retirement (ERISA)
810 Selective Service
820 Copyright
830 Patent
835 Patent - Abbreviated New Drug Application (ANDA)
840 Trademark
850 Securities, Commodities, Exchange
861 Medicare
862 Social Security - Black Lung
863 Social Security - DIWC/DIWW
864 Social Security - SSID Tit. XVI
865 Social Security - RSI Tax Suits
870 Tax - General
871 Tax - IRS Third Party Suits
875 Tax - Customer Challenge
890 Statutory Actions - Other
891 Agricultural Acts
892 Economic Stabilization Act
893 Environmental Matters
894 Energy Allocation Act
895 Freedom of Information Act
896 Arbitration
899 Administrative Procedure Act
900 Appeal of Fee Determination
950 Constitutionality of State Statute
ZZZ Nature of Suit

Appendix C: Party Types

The following are types of parties that may appear in civil and criminal District Court cases.

  • Amicus
  • Appellant
  • Appellee
  • Arbitrator
  • Claimant
  • Co-Debtor
  • Conflict Party
  • Consol Claimant
  • Consol Counter Claimant
  • Consol Counter Defendant
  • Consol Cross Claimant
  • Consol Cross Defendant
  • Consol Defendant
  • Consol Plaintiff
  • Consol Third Party Defendant
  • Consol Third Party Plaintiff
  • Counter Claimant
  • Counter Defendant
  • Counter Plaintiff
  • Creditor
  • Cross Claimant
  • Cross Defendant
  • Custodian
  • Debtor-in-Possess
  • Defendant
  • Garnishee
  • In Re
  • Interested Party
  • Interested Party
  • Interpleader
  • Intervenor
  • Intervenor Defendant
  • Intervenor Plaintiff
  • Lead Plaintiff
  • Material Witness
  • Mediator
  • Movant
  • Notice Only
  • Notice of Appearance
  • Objector
  • Official Defendant
  • Petitioner
  • Plaintiff
  • Receiver
  • Respondent
  • Special Master
  • Special Request
  • Taxpayer
  • Third Party Custodian
  • ThirdParty Defendant
  • ThirdParty Plaintiff
  • Trustee

The following are the types of parties that may appear in a Bankruptcy case.

  • 3rd Party Plaintiff
  • 3rd Pty Defendant
  • Accountant
  • Appraiser
  • Assistant U.S. Trustee
  • Attorney
  • Auctioneer
  • Auditor
  • Broker
  • Consultant
  • Consumer Privacy Ombudsman
  • Counter-Claimant
  • Counter-Defendant
  • Creditor
  • Creditor Committee
  • Creditor Committee Chair
  • Cross Defendant
  • Cross-Claimant
  • Debtor
  • Debtor In Possession
  • Defendant
  • Examiner
  • Executor plaintiff
  • Financial Advisor
  • Foreign Representative
  • Health Care Ombudsman
  • Interested Party
  • Interim Trustee
  • Interpleader
  • Intervenor
  • Intervenor-Defendant
  • Intervenor-Plaintiff
  • Joint Debtor
  • Judge
  • Liquidator
  • Mediator
  • Non-Filing Spouse
  • Other Professional
  • Partner
  • Petitioning Creditor
  • Plaintiff
  • Realtor
  • Respondent
  • Special Counsel
  • Stockholder
  • Successor Trustee
  • Surveyor
  • Trustee
  • U.S. Trustee
  • Witness