---
title: "Lookup Bills"
method: POST
path: "/api/v1/bills/lookup"
tags: ["bills"]
---

# Lookup Bills

`POST /api/v1/bills/lookup`

## Request

- Base URL: `https://api.billcommons.org`
- URL: `https://api.billcommons.org/api/v1/bills/lookup`
- Auth: none declared

Batch lookup with a structured JSON body. Same response shape as
`GET /bills/batch`, which it supersedes for anything non-trivial.

The GET form encodes each lookup as `JUR:NUMBER:SESSION` in the query
string, which breaks in two ways that are not hypothetical: 100
session-qualified keys is 4-8KB of URL, past the default request-line limit
on common proxies (they return 414 before our own error can fire), and the
colon delimiter collides with session identifiers and OCD jurisdiction ids
that contain colons themselves.

Keys are echoed back on each result so callers can correlate without
re-implementing bill-number normalization.

## Request body

- BillLookupRequest
  - `keys` BillLookupKey[], required
    - `id` string, uuid, nullable
    - `jurisdiction` string, nullable
    - `identifier` string, nullable
    - `session` string, nullable

## Response `200`

Successful Response

- BillBatchEnvelope: Response for the batch lookup. `not_found` is the point of the shape. A batch endpoint that just returns the rows it managed to resolve makes a typo, a renumbered bill and a jurisdiction we do not cover all look identical to a caller diffing counts -- and this project has already shipped two bugs where a short result was read as a complete one. Every requested key is accounted for in exactly one of the three fields. `ambiguous` is kept separate from `not_found` because they call for opposite actions. Not-found means the bill is not here; ambiguous means it is here more than once (the same number in several sessions) and the request needs a session to pick one. It maps the key to the session identifiers that matched, so the caller can re-ask without a second query. Folding these together would tell a consumer to drop a bill we hold.
  - `data` BillSummary[], required
    - `id` string, uuid, required
    - `jurisdiction_id` string, uuid, required
    - `session_id` string, uuid, required
    - `jurisdiction_abbreviation` string, nullable
    - `session_identifier` string, nullable
    - `chamber` string, nullable
    - `identifier` string, required
    - `identifier_norm` string, required
    - `title` string, required
    - `short_title` string, nullable
    - `bill_type` string, nullable
    - `status` string, nullable
    - `status_date` string, date, nullable
    - `introduced_date` string, date, nullable
    - `latest_action_text` string, nullable
    - `latest_action_date` string, date, nullable
    - `source_url` string, nullable
    - `updated_at` string, date-time, nullable
  - `not_found` string[], required
  - `ambiguous` object
  - `meta` object, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/billcommons/apis/bill-commons-api.md) · [All operations](https://skmtc.dev/billcommons/apis/bill-commons-api/llms.txt) · [OpenAPI document](https://skmtc.dev/billcommons/apis/bill-commons-api/revisions/bfb8cd50a317?raw)