Overview
Each step below outlines the various endpoints you need to use to download a complaint file for a case.
Remember that all API calls are secured using tokens. For more information about tokens, and how to generate them, see our article on How to Generate an API key and Authentication Tokens.
All the examples in this article are demonstrated using direct CURL calls to the API, which can be performed through a terminal. While they can be used exactly as outlined (with your token information injected), they are not identical to how various programming languages or frameworks execute external requests to APIs.
For the purpose of this article we are focusing on the Civil Litigation library. The Opinion and Bankruptcy libraries work nearly identically but in some cases have different properties or attributes. Consult the API documentation for specific details of other libraries.
Performing a Search & Seeing if a Case has a Complaint
A search is executed by a POST to the /api/1/search/civil-litigation endpoint.
The endpoint, as with most collection endpoints, requires a page and pageSize query parameter.
NOTE: All API endpoints are restricted to a maximum page size of 100. API requests are also throttled per minute, the limit depending on your account tier. Be sure to include logic your code that accounts for a throttling response (429) and appropriately waits 60 seconds before trying again.
It can also be optionally sorted using sortBy, and in the order of your choosing using sortOrder.
The parameters of the search are included in the POST body. A few details about the body parameters:
- "engine" refers to the search engine used, and currently only ElasticSearch is supported, specified using "ES"
- "requestData" contains the full details of what the search parameters are
- "query" contains the primary query (same as what you would enter in the CasePortal interface)
- "startDate" is a restriction of the filed on date of the case
- "endDate" is a restriction of the filed on date of the case
- "options" are for aggregate counts (filters as shown in CasePortal) and should generally not be used in interacting with the API directly
Generally speaking it's not a good practice to restrict the search to a small window using the startDate and endDate parameters. This is because a case may be added with a filing date in the past - for example when a court makes a case available a few days after the case has actually been filed. Therefore, using this restriction to find cases that were added on a certain day would mean that some cases are missed. A better approach would be to use the createdAtUTC attribute of a case, which can be restricted in the query itself.
For example, to get a list of cases created on October 25th, 2023 that had "google" in any field, you would post the body:
{
"engine": "ES",
"requestData": {
"query": "google AND createdAtUTC:[2023-10-25T07:00:00 TO 2023-10-26T07:00:00]",
"startDate": "1900-01-01T00:00:00",
"endDate": "2023-10-30T23:59:59"
}
}The full request to the API would be:
curl -X 'POST' \
'https://api.cnscaseportal.com/api/1/search/civil-litigation?Page=1&PageSize=20&SortBy=FiledAt&SortOrder=desc' \
-H 'accept: text/plain' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json-patch+json' \
-d '{
"engine": "ES",
"requestData": {
"query": "google AND createdAtUTC:[2023-10-25T07:00:00 TO 2023-10-26T07:00:00]",
"startDate": "1900-01-01T00:00:00",
"endDate": "2023-10-30T23:59:59"
}
}'Note that the createdAtUTC attribute is in UTC time. In the query above a shift of 7 hours is applied to make the range based on the PST time zone.
Once you receive the response, it's easy to see which of the cases has a complaint file. Each case has a hasComplaintFile property, and if there is a file, this is set to true.
Here's the third case in this search result set, which does have a complaint file:
{
"_score": 14.7003765,
"id": "3_1_1100_2d4990b0-7ae3-49a9-8c18-a6e2b963eb73",
"litigationName": "Misael Ambriz, individually and on behalf of all others similarly situated v. <mark>Google</mark> LLC",
"filedAt": "2023-10-23T00:00:00",
"publishedAtUTC": null,
"createdAtUTC": "2023-10-26T00:34:53.6911446Z",
"updatedAtUTC": "2023-10-26T01:17:12.8602139Z",
"legacyCreatedAtUTC": "2023-10-26T00:34:00Z",
"legacyDocketUpdatedAtUTC": null,
"dependantItemUpdatedAtUTC": "2023-10-26T00:35:01.926161Z",
"legacyUpdatedAtUTC": null,
"legacyComplaintId": 31113963,
"indexedAtUtc": "2023-10-29T10:55:13.7226596Z",
"caseBlockId": 1100,
"caseNumber": "4:23cv5437",
"courtName": "USDC Northern District of California",
"plaintiffs": [
"Misael Ambriz, individually and on behalf of all others similarly situated"
],
"defendants": [
"<mark>Google</mark> LLC"
],
"judge": [
"Gilliam"
],
"summary": "Class action for consumer privacy. Defendant records conversations between plaintiffs and customer service representatives without their permission.",
"plaintiffLawyers": [
"Neal Deckant"
],
"defendantLawyers": [],
"plaintiffLawyerFirms": [
"Bursor Fisher"
],
"defendantLawyerFirms": [],
"services": [
"San Francisco Fed"
],
"filtered": false,
"createdById": 3,
"createdByName": null,
"natureOfSuit": "Torts - Personal Injury - Other Personal Injury",
"natureOfSuitId": 360,
"isTrackable": true,
"hasComplaintFile": true,
"courtCity": "San Francisco",
"courtState": "California",
"courthouseId": 721,
"civilLawsuitType": "Civil Litigation"
}
Getting the Complaint File Information
Once you have the case information, and know that the case has a file, you can get the file information by executing a GET to /api/1/civil-litigation/{caseId}/complaint-file.
Proceeding from the example above, we make the following API call to get the file information:
curl -X 'GET' \
'https://api.cnscaseportal.com/api/1/civil-litigation/3_1_1100_2d4990b0-7ae3-49a9-8c18-a6e2b963eb73/complaint-file' \
-H 'accept: text/plain' \
-H 'Authorization: Bearer YOUR_TOKEN'This will return the following response:
{
"caseId": "3_1_1100_2d4990b0-7ae3-49a9-8c18-a6e2b963eb73",
"docketId": "11111111-2222-3333-4444-555555555555",
"docketDescription": "",
"files": [
{
"fileId": "9d31bcf1-800a-4996-a58b-da7814b50b13",
"description": "",
"fileName": "COMPLAINT.pdf",
"fee": {
"originalFee": 5,
"finalFee": 5,
"isDownloaded": false
}
}
]
}A few things to note here:
- the "originalFee" for the file is how much the document costs
- "finalFee" is how much it will cost this user right now - if the document was paid for and downloaded previously, then the final fee would be $0
- the "fileId" is what we need to be able to download the file
Note: If you want to compose a download link to the complaint file for your users, the format is: https://search.cnscaseportal.com/civil-litigation/case/{caseId}/docket/file/{fileId}. From the above example the download link would be: https://search.cnscaseportal.com/civil-litigation/case/3_1_1100_2d4990b0-7ae3-49a9-8c18-a6e2b963eb73/docket/file/9d31bcf1-800a-4996-a58b-da7814b50b13
Getting Charge Fields (Billing References)
Before you can download the document using the API, you need to know the charge fields configuration for your firm. Charge fields determine which fields are required to be provided to be able to download the file (or make any other requests where charges apply).
These fields are configured and custom for each firm. It's possible that in your configuration no fields are configured, or that no fields are required. In such a case, you can skip past this section as the download endpoint will not require any of the fields.
To get your firms charge fields configuration you need to execute a GET to the /api/1/billing/fields endpoint. For example, here's a call to retrieve all fields, with 20 results per page:
curl -X 'GET' \
'https://api.cnscaseportal.com/api/1/billing/fields?Page=1&PageSize=20' \
-H 'accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN'Here's an example response:
{
"result": [
{
"id": 2418,
"isDeleted": true,
"orderId": 0,
"firmId": 56864,
"name": "Some Other Reference",
"type": "Text",
"isRequired": true
},
{
"id": 9753,
"isDeleted": false,
"orderId": 0,
"firmId": 56864,
"name": "Billing Reference",
"type": "Text",
"isRequired": true
},
{
"id": 14332,
"isDeleted": false,
"orderId": 2,
"firmId": 56864,
"name": "Client Id",
"type": "Text",
"isRequired": false
}
],
"totalCount": 3
}A few things to note here:
- you can ignore any fields that have "isDeleted" set to true, as they are deleted fields
- fields marked with "isRequired" false are optional, and you do not need to supply these fields for downloads
- fields marked with "isRequired" true must be provided when making a download call
- from this example, we can see that field with ID 9753 is a required field, and will need to be provided for downloads
- all these settings are firm specific, your firm will have different IDs, and you must use the appropriate IDs in your calls
Downloading a Document
With the file information in hand, along with the charge field configurations, we can now go ahead and download the document by executing a POST to the /api/1/civil-litigation/{caseId}/docket-entries/files endpoint.
Based on our example here is the post body to download the document from our search results. Note that the particular chargeFields attributes are specific to your firm, and you must set the values for the IDs in accordance with the ones you've found to be required from the previous step.
{
"filesIds": [
"9d31bcf1-800a-4996-a58b-da7814b50b13"
],
"chargeFields": [
{
"settingId": 9753,
"value": "Some value for the Billing Reference field for this download."
}
]
}Here's the full API call:
curl -X 'POST' \
'https://api.cnscaseportal.com/api/1/civil-litigation/3_1_1100_2d4990b0-7ae3-49a9-8c18-a6e2b963eb73/docket-entries/files' \
-H 'accept: */*' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json-patch+json' \
-d '{
"filesIds": [
"9d31bcf1-800a-4996-a58b-da7814b50b13"
],
"chargeFields": [
{
"settingId": 9753,
"value": "Some value for the Billing Reference field for this download."
}
]
}'The response will be the PDF file of the complaint.
Can't find what you're looking for?