POST
/party/screenLitigation check
Full case store, deterministic resolution plus optional LLM adjudication
One name in, one scored answer out. query echoes what you sent, summary gives the headline verdict, and matches carries the full detail per case. verdict: "no_matches_found" is only ever returned when coverage.exhaustive is true; otherwise the endpoint answers "inconclusive" rather than overstating a partial search as a clean result. A since filter, or a restricted record withheld with nothing else left to report, also forces "inconclusive" even on an otherwise exhaustive run. Unlike the search endpoints, this endpoint's request body is strict: an unrecognised top-level field is rejected with HTTP 400 rather than being silently dropped.
Body parameters
| Field | Type | Required | Notes |
|---|---|---|---|
| name | string | Yes | 2 to 200 characters. The party name to screen. |
| entityType | "person" | "company" | Yes | Selects the name normalisation and disambiguation rules applied to the search. |
| purpose | string | Yes | One of kyc, bgv, due_diligence, litigation, research, compliance. Mandatory under our DPDP handling; the request is rejected without it. |
| aliases | string[] | No | Up to 7 alternate spellings or names for the same party. |
| identifiers | object | No | Optional pan, gstin, cin, llpin. The strongest disambiguator you can supply; never written to logs. |
| address | object | No | Optional city, state, stateCode. Used as a disambiguation signal, not a filter. |
| knownPersons | string[] | No | Names of people known to be associated with the party, used as a disambiguator. |
| court | string | string[] | No | Restrict the screen to one named court. A single-element array is accepted; an array with more than one entry is rejected with 400 (one court per request for now). |
| since | string | No | YYYY-MM-DD lower bound on case activity. Must be a real calendar date; an invalid or malformed date is rejected with 400. |
| limit | number | No | 1 to 100, default 40. Candidates evaluated before scoring. |
| adjudicate | boolean | No | Default false. Runs an LLM pass on ambiguous matches; adds the adjudication surcharge. |
| displayThreshold | number | No | 0 to 1. Hides matches scored below this threshold from the response; does not change what was evaluated. |
Bash
curl -X POST https://research.courtmesh.ai/api/v1/prod/party/screen \
-H "X-API-Key: cm-YOUR_KEY_HERE" \
-H "Content-Type: application/json" \
-d '{
"name": "Ramesh Kumar Sharma",
"entityType": "person",
"purpose": "bgv",
"identifiers": { "pan": "ABCDE1234F" },
"address": { "city": "Delhi", "state": "Delhi" },
"limit": 40
}'JSON
{
"success": true,
"data": {
"query": {
"name": "Ramesh Kumar Sharma",
"entityType": "person",
"purpose": "bgv"
},
"summary": {
"matchCount": 2,
"byBand": { "confirmed": 1, "probable": 1, "possible": 0, "unlikely": 4 },
"highestBand": "confirmed",
"verdict": "matches_found"
},
"matches": [
{
"caseId": "664b19f2c8d4e5f6a7b80042",
"title": "Ramesh Kumar Sharma vs State (NCT of Delhi)",
"court": "Delhi High Court",
"caseNumber": "CRL.A/842/2021",
"cnr": "DLHC010084212021",
"caseType": "CRL.A",
"filingDate": "2021-03-11",
"decisionDate": "2022-07-19",
"disposalNature": "Dismissed",
"petitioners": ["Ramesh Kumar Sharma"],
"respondents": ["State (NCT of Delhi)"],
"partyRole": "petitioner",
"confidence": { "band": "confirmed", "score": 0.94, "calibrated": 0.94, "engine": "rules" },
"evidence": {
"entityMatch": true,
"matchedFields": ["name", "pan"],
"strategies": ["exact_name", "identifier_match"],
"signals": [
{ "name": "pan_match", "status": "matched", "weight": 0.9, "evidence": "PAN supplied in the request matches the PAN recorded against this party" }
],
"nameSimilarity": 1.0,
"disambiguatorPresent": true
},
"rationale": "The PAN supplied in the request matches the PAN recorded against this party.",
"casePageUrl": "https://courtmesh.ai/judgment/664b19f2c8d4e5f6a7b80042"
}
],
"relatedButUnverified": [],
"coverage": {
"exhaustive": true,
"exhaustiveWithinFilters": true,
"planClamped": false,
"anyStrategyErrored": false,
"strategiesRun": ["exact_name", "fuzzy_name", "identifier_match"],
"someRecordsWithheld": false
},
"adjudicationsRun": 0,
"notice": "A party can ask for a case to be withheld from search under CourtMesh's case removal policy (https://courtmesh.ai/case-removal-policy). A screen that reports no matches reflects what is currently searchable, not an exhaustive record of all litigation history."
},
"meta": {
"creditsCharged": 100,
"adjudicated": false,
"corpusAsOf": "2026-09-17"
}
}Errors
- 400 validation failed: name missing or out of the 2 to 200 character range, aliases over 7 entries, purpose missing or not one of the allowed values, court given as more than one entry (one court per request for now), since not a real calendar date, or an unrecognised top-level field in the request body
- 401 unauthorised: no key supplied, malformed key, or a deactivated key
- 402 insufficient credits: body carries required, balance, shortfall and topUpUrl, and the call is not executed
- 403 forbidden: trial accounts, a tier without litigation check access, or adjudicate set to true on the Free tier (API_TIER_NOT_ALLOWED)
- 403 limit reached: the Free tier's monthly litigation check cap already used (PARTY_SCREEN_LIMIT_REACHED)
- 429 too many requests: per minute or per day distinct name cap exceeded for your tier (DISTINCT_NAMES_LIMIT_REACHED), body carries Retry-After
- 502 search degraded: the underlying case search errored and returned no usable results, so no charge is made (PARTY_SCREEN_SEARCH_DEGRADED); the response carries a Retry-After header
- 503 unavailable: account standing could not be verified with the identity service, the endpoint fails closed rather than serving an unauthorised result