> For the complete documentation index, see [llms.txt](https://api.clearinghouse.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api.clearinghouse.net/api-reference-v2p1/endpoints/documents.md).

# Documents

### Get documents.

<mark style="color:blue;">`GET`</mark> `https://clearinghouse.net/api/v2p1/documents/`

Returns a paginated list of documents. All parameters are optional and can be combined.

**Headers**

| Name                                            | Type   | Description                                                                                                                    |
| ----------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------ |
| Authorization<mark style="color:red;">\*</mark> | String | <p>Authorization</p><p><code>Token XXXXXXXXXXX</code></p><p>where</p><p><code>XXXXXXXXXXX</code></p><p>is the token string</p> |

**Query Parameters**

| Parameter             | Type    | Description                                                                                                |
| --------------------- | ------- | ---------------------------------------------------------------------------------------------------------- |
| case\_id              | Integer | Filter by case ID.                                                                                         |
| docket\_id            | Integer | Filter by docket ID.                                                                                       |
| title                 | String  | Case-insensitive partial match on document title.                                                          |
| is\_core\_document    | Boolean | Filter by core document status. Accepts `true` or `false`.                                                 |
| document\_type        | Integer | Filter by document type ID. See supported values below.                                                    |
| document\_status      | Integer | Filter by document status ID. See supported values below.                                                  |
| born\_digital\_status | Integer | Filter by born digital status ID. See supported values below.                                              |
| text                  | String  | Full-text search across document text, document title, case name, and case summary. See Text Search below. |

{% tabs %}
{% tab title="200 Documents successfully retrieved" %}

{% endtab %}

{% tab title="400: Bad Request No results, key not found, or invalid parameter" %}

```
\\ No results
\\ Example query endpoint: /api/v2p1/documents/?title=zzznomatch
["No results for {'title': 'zzznomatch'}"]

\\ Key not found
\\ Example query endpoint: /api/v2p1/documents?test_key=1
["API Error: Key: test_key, Value: 1 not found."]

\\ Invalid parameter
\\ Example query endpoint: /api/v2p1/documents/?case_id=xyz
["API Error: xyz is not an integer."]
```

{% endtab %}

{% tab title="401 Permission denied" %}

```javascript
{
    "detail":"Authentication credentials were not provided."
}
```

{% endtab %}
{% endtabs %}

**Example**

{% tabs %}
{% tab title="URL" %}

```
https://clearinghouse.net/api/v2p1/documents/?case_id=18003&document_type=5893
```

{% endtab %}

{% tab title="python" %}

```python
import requests

url = "https://clearinghouse.net/api/v2p1/documents/?case_id=18003&document_type=5893"
headers = { 'Authorization': 'Token XXXXXXXXXX',
'User-Agent': 'Chrome v22.2 Linux Ubuntu'
}
response = requests.request("GET", url, headers=headers, data={})

print(response.text)
```

{% endtab %}
{% endtabs %}

***

#### Supported Filter Values

**document\_type**

| id    | value                                         |
| ----- | --------------------------------------------- |
| 5894  | Declaration/Affidavit                         |
| 5908  | Discovery Material/FOIA Release               |
| 5909  | Docket                                        |
| 5905  | Complaint                                     |
| 5906  | Correspondence                                |
| 38543 | Executive Order                               |
| 5899  | FOIA Request                                  |
| 5910  | Findings Letter/Report                        |
| 5897  | Internal memorandum                           |
| 5895  | Justification Memo                            |
| 5896  | Legislative Report                            |
| 5891  | Magistrate Report/Recommendation              |
| 5911  | Monitor/Expert/Receiver Report                |
| 5913  | Notice of Investigation or Suit/Demand Letter |
| 5893  | Order/Opinion                                 |
| 5914  | Other                                         |
| 5915  | Pleading / Motion / Brief                     |
| 5898  | Press Release                                 |
| 5900  | Settlement Agreement                          |
| 5892  | Statute/Ordinance/Regulation                  |
| 38762 | Statement of Interest (DOJ)                   |
| 5904  | Transcript                                    |

**document\_status**

| id   | value                                       |
| ---- | ------------------------------------------- |
| 5923 | Approved                                    |
| 5927 | Coding Complete                             |
| 5928 | Coding Complete, but not for Public Display |
| 5925 | Deleted                                     |
| 5926 | Empty/Missing Document                      |
| 5920 | In Process                                  |

**born\_digital\_status**

| id    | value        |
| ----- | ------------ |
| 39148 | Born digital |
| 39150 | Mixed        |
| 39149 | Scanned      |

***

#### Text Search

The `text` parameter uses PostgreSQL full-text search. It runs across the following fields, in descending order of relevance weight:

| Field          | Weight      |
| -------------- | ----------- |
| Case name      | A (highest) |
| Document title | B           |
| Case summary   | C           |
| Document text  | D (lowest)  |

Queries support natural language stemming (e.g. "running" matches "run"). Multi-word queries require all terms to match (AND logic).

**Example**

{% tabs %}
{% tab title="URL" %}

```
https://clearinghouse.net/api/v2p1/documents/?text=solitary+confinement
```

{% endtab %}

{% tab title="python" %}

```python
import requests

url = "https://clearinghouse.net/api/v2p1/documents/?text=solitary+confinement"
headers = { 'Authorization': 'Token XXXXXXXXXX',
'User-Agent': 'Chrome v22.2 Linux Ubuntu'
}
response = requests.request("GET", url, headers=headers, data={})

print(response.text)
```

{% endtab %}
{% endtabs %}

***

### Get a single document by Document ID (integer).

<mark style="color:blue;">`GET`</mark> `https://clearinghouse.net/api/v2p1/documents/ID/`

Returns the full document record for the given ID, including document text.

**Headers**

| Name                                            | Type   | Description                                                                                                                    |
| ----------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------ |
| Authorization<mark style="color:red;">\*</mark> | String | <p>Authorization</p><p><code>Token XXXXXXXXXXX</code></p><p>where</p><p><code>XXXXXXXXXXX</code></p><p>is the token string</p> |

{% tabs %}
{% tab title="200 Document successfully retrieved" %}

{% endtab %}

{% tab title="400: Bad Request No results or invalid parameter" %}

```
\\ No results
\\ Example query endpoint: /api/v2p1/documents/1/
["No results for {'id': '1'}"]

\\ Invalid parameter
\\ Example query endpoint: /api/v2p1/documents/xyz/
["API Error: xyz is not an integer."]
```

{% endtab %}

{% tab title="401 Permission denied" %}

```javascript
{
    "detail":"Authentication credentials were not provided."
}
```

{% endtab %}
{% endtabs %}

**Example**

{% tabs %}
{% tab title="URL" %}

```
https://clearinghouse.net/api/v2p1/documents/136285/
```

{% endtab %}

{% tab title="python" %}

```python
import requests

url = "https://clearinghouse.net/api/v2p1/documents/136285/"
headers = { 'Authorization': 'Token XXXXXXXXXX',
'User-Agent': 'Chrome v22.2 Linux Ubuntu'
}
response = requests.request("GET", url, headers=headers, data={})

print(response.text)
```

{% endtab %}
{% endtabs %}