Party profile (background check)

What one call returns

• Identities. Everything POST /party/screen finds is grouped by the evidence the cases share: a known person you gave recorded as a relation or as a middle name, and the same statutory identifier. A case naming a different relation is kept apart, and cases matched on name alone form one unconfirmed group that is never merged into a confirmed identity. Each identity carries a confidence band and a why list of plain sentences.
• The primary identity. The strongest identity at or above minConfidence that the evidence ties to the subject is returned in full under identities, with its cases and a code built profile (counts by court type and role, pending and disposed, categories, flags and a plain paragraph). For a company, a name only group may be the primary only when its name is exactly the one you gave (or an alias); a generic company name such as "Sharma Traders" is never the primary on name alone. When no identity qualifies, identities is empty and verdict is no_confirmed_identity.
• Possible other people. Every other identity is listed under possibleOtherPeople with its case ids, the reasons, and the basic facts of each case (court, case type, title, parties, role, filing and decision dates) at no extra cost, so you can judge them yourself. GET /cases/:id gives a case in full.
• Each case carries its court (and bench for tribunals), case type, title, party role, status, next hearing date, decision date, a confidence band, matchReasons in plain words, acts and FIR as the court record states them, and the documents held for it with links to the text and the PDF.
• Notes. notes is always present: plain sentences on anything left out, empty when nothing was. Restricted and masked records are dropped before anything is built, and a note that some records are withheld is the only disclosure.

Takes every field of POST /party/screen, with the same validation and caps, plus the fields below. In quick mode the answer is the profile itself (HTTP 200). In full mode the answer is HTTP 202 with a requestId, and the profile is read later.

curl -X POST https://research.courtmesh.ai/api/v1/prod/party/profile \
  -H "X-API-Key: cm-YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sample Person Name",
    "entityType": "person",
    "knownPersons": ["Sample Father Name"],
    "address": { "state": "Karnataka", "city": "Bengaluru" },
    "purpose": "bgv",
    "mode": "quick"
  }'

Full mode

With mode: "full" the call puts correctness ahead of speed. It answers 202 at once and the work runs behind it in this order:

1. The same search and grouping as quick mode, with the case records and documents listings read.
2. Every case of the primary identity (identities[0]) that has a CNR is read again from its court, so status, hearings and orders are current. The request waits up to 25 minutes for these refreshes, then carries on with what arrived. When a court refuses or a refresh fails, the case is asked again after a wait (about 1, 2, 4 and 5 minutes, up to 4 retries). Each case is charged one refresh at most; a retry is never charged. Each case reports courtRefresh.status, and courtRefresh.attempts when more than one try was made.
3. Every case of that identity is analysed from the documents this API may show for it, pending cases first, then newest first. A current analysis is reused; one older than 180 days or older than the newest document is written again. A case with no open document gets analysis.status: "not_done" with a plain reason and is not charged. When maxCredits cannot cover a full analysis of every case, the cases at the front get a full analysis and the rest get a short one (analysis.status: "short": summary, outcome and issues, about 5 credits each), so every case is covered. Once every case has an analysis, short ones are redone in full, front of the order first, while what is left of maxCredits covers a full analysis; a case keeps its short analysis unless the full one comes back. A short analysis is written for this request only.
4. One analysis of the person or company over all of those cases (partyAnalysis): an overview, the litigation pattern, key risks, notable cases and open matters, each tied to case ids from this profile. Being a party to a case is not a finding against anyone.

• Only the primary identity is refreshed and analysed. Identities under possibleOtherPeople are listed as in quick mode.
• The set of cases is fixed when the search stage ends. If the court refresh changes which cases match, the cases already found are still the ones analysed and notes says so.
• If the API key that made the request is revoked or expires while it runs, the request stops and no further stage is charged.
• Read the outcome from GET /party/profile/:requestId, or pass webhook to be told when it ends. A finished result can be read for 30 days.
• An account may have at most 3 full profiles queued or running at once.
• Where full mode is not available, mode: "full" is a 503 with code PARTY_PROFILE_FULL_UNAVAILABLE and nothing is charged; send mode: "quick".

curl -X POST https://research.courtmesh.ai/api/v1/prod/party/profile \
  -H "X-API-Key: cm-YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: acme-check-2026-11-11" \
  -d '{
    "name": "Acme Infrastructure Private Limited",
    "entityType": "company",
    "identifiers": { "cin": "U45200DL2010PTC123456" },
    "purpose": "due_diligence",
    "mode": "full",
    "maxCredits": 1000,
    "webhook": {
      "url": "https://hooks.example.com/courtmesh",
      "headers": { "Authorization": "Bearer your-own-token" }
    }
  }'

Where a full mode request stands: status (queued, running, completed, failed), the stage while running, progress counts, and credits charged so far with a breakdown. Once status is completed, result holds the profile: the same shape as quick mode, with courtRefresh and analysis on every case of the primary identity, the partyAnalysis, and notes. A failed request carries failure with a code and a plain message; what it was charged before failing stays in credits.

• Poll every few seconds to a minute. Most requests finish within minutes; waiting for court refreshes, with their retries, can take up to 25 minutes.
• A request can be read only by the account that made it; any other id is the same 404 NOT_FOUND.
• The result can be read for 30 days after the request ends; after that resultExpired is true and only the status, progress and credits remain.
• A case withheld since the request ran is left out, and the party analysis with it. Send the request again for a current profile.

curl https://research.courtmesh.ai/api/v1/prod/party/profile/ppr_3f9c2a7d1b8e4c6fa0d5e2b7c9a1f4d8 \
  -H "X-API-Key: cm-YOUR_KEY_HERE"

Completion webhook

When a full mode request ends, completed or failed, one POST is sent to webhook.url with a small JSON notice: event (party.profile.completed or party.profile.failed), requestId, status, creditsCharged, resultUrl, finishedAt and, on failure, failure. The profile itself is never in the notice: read it from resultUrl with your API key.

• The 202 answer carries webhook.signingSecret once. Store it.
• Every delivery is signed: CourtMesh-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">. Reject a delivery when the difference between now and t is over 300 seconds.
• Dedupe on the CourtMesh-Event-Id header (the requestId): delivery is at least once.
• A delivery that does not get a 2xx is retried with growing gaps for about two days. The url must be a public https address; redirects are not followed.

POST https://hooks.example.com/courtmesh
Content-Type: application/json
CourtMesh-Event-Id: ppr_3f9c2a7d1b8e4c6fa0d5e2b7c9a1f4d8
CourtMesh-Signature: t=1794390097,v1=5d41402abc4b2a76b9719d911017c592...
Authorization: Bearer your-own-token

{
  "event": "party.profile.completed",
  "requestId": "ppr_3f9c2a7d1b8e4c6fa0d5e2b7c9a1f4d8",
  "status": "completed",
  "creditsCharged": 150,
  "resultUrl": "/api/v1/prod/party/profile/ppr_3f9c2a7d1b8e4c6fa0d5e2b7c9a1f4d8",
  "finishedAt": "2026-11-11T09:41:37.000Z"
}

import crypto from "node:crypto";

// rawBody: the request body exactly as received, before JSON parsing.
function verifyCourtMeshSignature(rawBody, header, signingSecret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = crypto
    .createHmac("sha256", signingSecret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(parts.v1 ?? "", "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// Then dedupe on the CourtMesh-Event-Id header: delivery is at least once.

Document and PDF links

Each case lists the documents held for it (the case document and its orders), each with documentId, kind, date and links. links.text is the path of the order text endpoint, relative to the API base and billed as that endpoint is, or null when the text is not offered. documentsNote is a plain sentence when the text and order PDFs of the case are not offered, and documentsMore: true means the case holds more documents than one listing carries.

• Where a PDF is held and may be shown, links.pdf is a ready download URL, valid for one hour (links.pdfExpiresAt). It needs no API key, so it can be opened in a browser.
• Receiving a link is free. The first time a link is opened it is charged as one PDF call to the key that read the profile, and counts toward your tier's monthly PDF limit. Opening the same link again is free.
• An expired link answers 403 DOWNLOAD_LINK_INVALID: read the profile again for fresh links (a stored full mode result mints new ones on every read).
• Other answers when opening a link: 402 INSUFFICIENT_CREDITS (top up and open it again), 403 CASE_RESTRICTED or API_KEY_INACTIVE, 404 PDF_NOT_STORED, 409 DOWNLOAD_IN_PROGRESS (the same link is being opened already), 429 PDF_LIMIT_REACHED.

Pricing

• Every profile costs at least 100 credits, even when no case is found. Above that it is priced by what the call actually used, at the existing rates.
• Quick mode: 1 credit per search call (name, alias, known person and identifier queries, at most 24), 1 per case record read and 1 per documents listing that offers a document (at most 100 cases are enriched), plus the optional AI review by its tokens, held at 80 credits. One quick call never costs more than 304 credits; a run that would exceed it stops enriching and notes says the answer may be incomplete. meta.creditsBreakdown itemises searches, caseRecords, documentLists, aiReview when charged, and minimumCharge when the call used less than the minimum.
• Full mode: charged stage by stage as each finishes: the search stage at the quick mode rates, 1 credit per court refresh started (retries are free), each new, rewritten or short case analysis by the tokens it used, each reused analysis at the price of reading a stored analysis, and the party analysis by its tokens. An analysis that fails or is cut off is not charged. Accepting the request and reading its status cost nothing.
• A full mode request never spends more than maxCredits (100 to 5000, default 1000, or your balance if that is lower). The balance must cover it (or the 100 credit minimum when you send none) when the request is accepted, else 402 and nothing runs. When the ceiling or the balance is reached the work stops, and notes says what was not done.
• Up to 60 credits of maxCredits (never more than 30 percent of it) are kept back from the case analyses so the party analysis can still be written.
• A refused or failed call charges nothing. If a charge cannot be confirmed, no further paid work is done: on the first charge the request fails with SETTLEMENT_UNCONFIRMED and returns no profile; later on it finishes with what it has and notes says so.
• Not available on the Free tier.

Errors