How do I get the parties for a docket using the API?

[mlissner]

When I try to get the parties for a docket, it's really hard, and I don't wind up getting what I expect. What's the best way to get the attorneys and parties for a docket?

[mlissner]

This is a very tricky part of the API and indeed it's a tricky part of the whole system — even when we have direct access to the database, it's sometimes very challenging to make the correct queries and to make those queries efficient.

Some things that make performance difficult:

• Some attorneys have represented thousands of parties through things like class action cases
• Some parties — like "USA," for example — have been represented by thousands of attorneys
• Some cases have thousands of parties and attorneys

Taken together, this is why parties and attorneys are not simply folded into the docket objects. It would be a disaster to have thousands of parties and attorneys in a docket — this much information demands pagination, unfortunately.

Structurally, the attorney/case/party relationship is also very complicated. The best source of truth for the way these objects are modeled is the API documentation, which provides a nice diagram. In English terms though:

• parties are parts of cases (via the historically-named PartyType table);
• criminal parties have criminal counts and complaints levied against them
• attorneys have roles for parties in cases (via the Roles table); and
• attorneys are parts of organizations for particular cases (via the AttorneyOrganizationAssociation table)
• parties, attorneys, roles, and party types, all have additional metadata

So that's kind of a lot. Really, the picture in the docs makes this make more sense.

---

Enough background. How do we do what we want with the API?

Well, if you know what party you want, you can request it like this:

https://www.courtlistener.com/api/rest/v3/parties/11870/

But be careful. That link will load tens of thousands of attorneys because party 11870 is USA. But it'll also get you the criminal counts and complaints for the party as well as extra metadata for that party. Plus, because the attorney information for the party lists the docket, you can filter down that information:

{
  "role": 1,
  "docket": "https://www.courtlistener.com/api/rest/v3/dockets/6289678/",
  "attorney":"https://www.courtlistener.com/api/rest/v3/attorneys/773929/",
  "date_action":null
}

So that'll get you information about a party if you know it's ID. If, instead, you're starting with a docket ID, you can get a list of all the parties (and their attorneys) via something like:

https://www.courtlistener.com/api/rest/v3/parties/?docket=4214664

The last direction you can use to approach this issue is via the attorneys endpoint. Again, you can filter to a specific attorney:

https://www.courtlistener.com/api/rest/v3/attorneys/6315443/

Or by filtering to a particular docket:

https://www.courtlistener.com/api/rest/v3/attorneys/?docket=4214664

Either way, you'll get the nested roles and raw contact information for the attorney.

For the moment, the parsed attorney organization information is not available in the API.