Table of Contents

PACER API Specification for U.S. Courts

Version 1.6.3
Released: August 2013
Last Edit: October 2018 5+ years!

Introduction

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

Background

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 judgement. 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 420, and a summary. The docket entry also contains one attachment and a notice of when the document was entered.

Docket Alarm obtains its information from a number of court docketing systems, including PACER. PACER is a system docketing for US Federal Courts, Appellate Courts, and Bankruptcy. Docket Alarm provides a REST API for the PACER system. Docket Alarm also provides access to numerous state courts, see a full listing of available jurisdictions here.

Get Started

The following is the typical flow of API calls:

  • Log into the Docket Alarm API with login/.
  • Search PACER for dockets with searchpacer/.
  • (Optional) Run a full-text-search for dockets or documents with search/.
  • 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.

Client Library and Sample Code

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:
     https://github.com/speedplane/docketalarm-api

Unexposed and Deprecated Features

Docket Alarm is capable of more features than those exposed in the API. When a feature is unexposed in the documentation, we note it as such. If you require unexposed functionality, we ask that you 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 support@docketalarm.com.

API Conventions

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

https://www.docketalarm/api/v1/

All calls should be made with HTTPS, otherwise login credentials may be intercepted.

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.

Testing

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.

Authentication

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 www.docketalarm.com. 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.

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 30 minutes. This token must be supplied as a GET parameter for all future API calls.

Example

A successful login request and response.

Request:

	POST https://www.docketalarm.com/api/v1/login/
		username=foo%40example.com&
		password=aaa

Response:

200
{
	'login_token':'839dbcf5fa7768ea912341011ba754c354bc75792494804fb6f56538',
	'success': true
}

Search PACER

Search for PACER dockets using the searchpacer/ 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.
 party_name (Optional) The name of the party you wish to search.
 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.

search_results

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.

Example

Search for cases where Sony is a party:

	
	GET https://www.docketalarm.com/api/v1/searchpacer/?login_token=...&party_name=Sony&client_matter=&page=2
	

If successful, the result will be (abbreviated):

200
{
	'page_max': 4,
	'search_results':
	[
		{
			'date_terminated': '', 
			'court': 'Louisiana Western District Court', 
			'party_role': 'Plaintiff', 
			'title': 'Broadcast Music Inc et al v. Camp Lounge L L C et al', 
			'date_filed': '5/29/2013', 
			'link': 'https://www.docketalarm.com/cases/Louisiana_Western_District_Court/6--13-cv-01271/Broadcast_Music_Inc_et_al_v._Camp_Lounge_L_L_C_et_al/', 
			'nature_of_suit': '820', 
			'party_name': 'Sony A T V Tree Publishing', 
			'docket': '6:13-cv-01271'
		}, 
		...
		{
			'date_terminated': '', 
			'court': 'Texas Eastern District Court', 
			'party_role': 'Defendant', 
			'title': 'Adaptix, Inc. v. Sony Mobile Communications, Inc. et al', 
			'date_filed': '5/28/2013', 
			'link': 'https://www.docketalarm.com/cases/Texas_Eastern_District_Court/6--13-cv-00442/Adaptix_Inc._v._Sony_Mobile_Communications_Inc._et_al/', 
			'nature_of_suit': '830', 
			'party_name': 'Sony Mobile Communications (USA), Inc.', 
			'docket': '6:13-cv-00442'
		}, 
	],
	'success': true
}

Search Docket Alarm

Docket Alarm records a copy of every docket that we retrieve from the court. As of November, 2017, Docket Alarm has over 210 million records in its database, making it one of the largest such databases available.

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

Should I use search or searchpacer?

When integrating with the API, you must decide whether you want to use the search/ endpoint, the searchpacer/ endpoint, or a combination of the two. There are advantages to each:

search/searchpacer/
Cost No additional cost. Incurs $0.10 PACER fees for each page of search results. Docket Alarm may add additional charges to these fees.
Coverage Everything on Docket Alarm. Dockets and documents. Federal District Courts, Circuit Courts, and Bankruptcies. Only dockets.
Completeness No guarantee of comprehensive results. If a case was filed recently, it may not appear in results. Guaranteed comprehensive results, covering all dockets in PACER.
Search Options Use search filters and search within PDF filings. All options are documented here. Search with only the parameters listed here.

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 options are documented here.
 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.
scroll
scroll_parallel
scroll_index
(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.

search_results

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.

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

Scrolling Results

Scrolling through thousands of search results efficiently and in parallel can be accomplished with the scroll parameters.

First decide how many parallel threads you want to use to scan through results (can be 1 for no parallelism). Then, do the first search setting scroll_parallel to the number of threads and scroll_index, which is the thread number (indexed 0 to scroll_parallel-1).

After the first search of each thread, the result will contain an additional field called scroll. This field's value contains state about the search. Pass this value into all subsequent calls as the parameter scroll, along with the other parameters scroll_parallel and scroll_index. Note that each thread may have a different scroll value.

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

GET https://www.docketalarm.com/api/v1/search/?q=...&scroll_parallel=0&scroll_index=0
GET https://www.docketalarm.com/api/v1/search/?q=...&scroll_parallel=0&scroll_index=1
GET https://www.docketalarm.com/api/v1/search/?q=...&scroll_parallel=0&scroll_index=2

If successful, the result will be (abbreviated):

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

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

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

Subsequent requests will include the scroll parameter returned by the first.

GET https://www.docketalarm.com/api/v1/search/?q=...&scroll=Dnf1...=
GET https://www.docketalarm.com/api/v1/search/?q=...&scroll=Dnf2...=
GET https://www.docketalarm.com/api/v1/search/?q=...&scroll=XS12...=

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.
 cached (Optional) If set to true getdocket/ will not get the newest docket information from the court. Instead, it will return whatever is already cached in Docket Alarm's database, which may not be up to date. When false, or when omitted, it will get the newest docket information directly from the court. When set to true, this call may be less expensive, depending on the court and your billing plan.

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.

info

 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.
 judge (Optional) The judge presiding over the case. This value may not be present if a judge has not yet been assigned.
 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.
 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.
 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_joint_debtor_discharged
 date_341_meeting
 date_plan_confirmed
 date_deadline_object_discharge
 date_deadline_financial_mgmt_course
 date_discharged
 date_converted
 disposition_debtor
 disposition_joint_debtor
 chapter
 chapter_previous
 is_asset
 is_voluntary
 date_cached (Optional) (Advanced) If cached was set, this is the cache update date. Currently, this is only the date, but future API versions may return the full date and time.
 cache_unofficial (Optional) (Advanced) If cached was set, and we did not obtain this docket from an official source, then this will be true.

docket_report

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 has 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 will also be given a filing number. Filing numbers are integers.
 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.
 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 two keys:
 exhibit 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.

parties

 name The name of the party to the case.
 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.

counsel

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.
 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.

Example

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

	GET https://www.docketalarm.com/api/v1/getdocket/?docket=1%3A11-cv-06909&login_token=...&court=New+York+Southern+District+Court&client_matter=

If successful, the result will be (abbreviated):

200
{
	"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": "mallan@foo.com"
				}, 
				{
				  "firm": "Steptoe & Johnson, LLP (NYC)", 
				  "name": "Evan Glassman", 
				  "phone": "212-555-3900", 
				  "email": "eglassman@bar.com"
				}
			]
		},
		{
			"type": "Plaintiff", 
			"name": "Kickstarter, Inc."
		},
		...
	],
	
	"docket_report": [
		{
			"link": "https://www.docketalarm.com/cases/New_York_Southern_District_Court/1--11-cv-06909/Kickstarter_Inc._v._Fan_Funded_LLC_et_al/docs/107.pdf", 
			"entry_date": "9/11/2014", 
			"date": "9/11/2014", 
			"contents": "	DECLARATION of Matthew Ambros & William Seymour in ... ",
			"exhibits" : [
				{
				"link": "https://www.docketalarm.com/cases/New_York_Southern_District_Court/1--11-cv-06909/Kickstarter_Inc._v._Fan_Funded_LLC_et_al/docs/107/1.pdf",
				 "exhibit" : "1"
				},
				{
				"link": "https://www.docketalarm.com/cases/New_York_Southern_District_Court/1--11-cv-06909/Kickstarter_Inc._v._Fan_Funded_LLC_et_al/docs/107/2.pdf",
				 "exhibit" : "2"
				}
			]
		},
		...
		{
			"link": "https://www.docketalarm.com/cases/New_York_Southern_District_Court/1--11-cv-06909/Kickstarter_Inc._v._Fan_Funded_LLC_et_al/docs/78.pdf", 
			"entry_date": "9/6/2013", 
			"date": "9/6/2013", 
			"contents": "JOINT STIPULATION AND MODIFIED ... ",
			"exhibits" : []
		}, 
		{
			"link": null, 
			"entry_date": "9/6/2013", 
			"date": "9/6/2013", 
			"contents": "***NOTE TO ATTORNEY TO RE-FILE DOCUMENT - NON-ECF DOCUMENT ERROR. Note to ... ",
			"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 is done 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.

Example

If the link in the docket entry is as follows:

	cases/Arkansas_Eastern_District_Court/4--2010-cr-00188/USA_v_Vargas_et_al/docs/425.pdf

Then the document may be downloaded with the following call:

	GET https://www.docketalarm.com/cases/Arkansas_Eastern_District_Court/4--2010-cr-00188/USA_v_Vargas_et_al/docs/425.pdf?login_token=...

To download the document only if it was previously downloaded:

	GET https://www.docketalarm.com/cases/Arkansas_Eastern_District_Court/4--2010-cr-00188/USA_v_Vargas_et_al/docs/425.pdf?cached&login_token=...

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.
 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.

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.
 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.
 _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:

		GET https://www.docketalarm.com/api/v1/track/?login_token=...
	

If successful, the result will be:

	200
	{
	  "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", 
		  "last_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", 
		  "last_updated": "06/01/2017", 
	  }], 
	  "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 128kb).
 will_retry Set to true if we will be attempting another API push retry.

GET One Case Tracker Request

The following GET endpoint has been deprecated. It is kept here for backwards compatibility, but you should not use it.

A GET request to the track/ endpoint returns the tracking status of a docket. The required parameters are:

 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.

GET Request Result

If the request was successful, the following result will be returned:

 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 (Not exposed) The client or matter code used to bill this docket tracker if enabled is true.

GET Example

This is an example of requesting the tracking status for a criminal docket in Arkansas Eastern District Court:

		GET https://www.docketalarm.com/api/v1/track/?docket=4%3A2010-cr-00188&login_token=...&court=Arkansas+Eastern+District+Court
	

If successful, the result will be:

	200
	{
		'enabled': 	true,
		'frequency':'twice_daily',
		'success':	true,
	}
	

POST Request

A POST request to the track/ endpoint modifies tracking options.

 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 If set to 'twice_daily', Docket Alarm will check the court docket two times a day. If set to 'weekly', Docket Alarm will check the court docket every week morning.
 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.

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

	POST https://www.docketalarm.com/api/v1/track/
		docket=4%3A2010-cr-00188&
		login_token=...&
		court=Arkansas+Eastern+District+Court&
		client_matter=&
		frequency=twice_daily

The result will be:

200
{
	'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 Case: Sent when a new case is filed matching criteria setup using the Federal Court Alert tool.
  • New Docket Item: Sent when a new case docket event is detected.
  • New Search Result: Sent when a new search result is detected on a search result tracker.

New case notifications must be setup on the Docket Alarm website and cannot currently be created with the API. The other notifications may be setup using the website and the API (see track/).

For all notifications, Docket Alarm sends a HTTP POST request to a URL endpoint. 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.

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.

Testing Push Notifications

You can test push notifications to make sure they are properly setup. See Testing for more details.

New Case Notifications

 push_type Will always be set to new_case.
 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.

Example

{
	'push_type': 'new_case', 
	'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'
		}, 
}

Docket Notifications

 push_type Will always be set to docket.
 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.

Search Result Notifications

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.
 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.

Sub Accounts

Docket Alarm supports creating sub accounts to your main 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 master@example.com, the sub accounts must also be on example.com. Sub accounts could not be created such as subact@gmail.com.
 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, https://gooduser:secretpassword@www.example.com/webcallback?foo=bar

Appendices

Appendix A: Court Regions

The following is a list of valid values to use for regions.

  • 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.

Code Nature of Suit
110 Insurance
120 Contract - Marine
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
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
  • 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
  • Creditor
  • Cross Claimant
  • Cross Defendant
  • Custodian
  • Debtor-in-Possess
  • Defendant
  • Garnishee
  • In Re
  • Interested Party
  • Interpleader
  • Intervenor
  • Intervenor Defendant
  • Intervenor Plaintiff
  • Lead Plaintiff
  • Material Witness
  • Mediator
  • Movant
  • Notice of Appearance
  • Objector
  • Petitioner
  • Plaintiff
  • Receiver
  • Respondent
  • Special Master
  • Taxpayer
  • 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