How to Wire LegalCheck into a BGV or KYB Flow

Wire LegalCheck after offer acceptance or vendor creation, poll until completed, then attach risk.band plus match CNRs to the same PDF or ATS report your team already ships. Keep identity, UAN, and address verification on your existing BGV or KYC stack. LegalCheck is only the court layer: an async scored screen over public Indian court records (model eCI-1.2, report schema legal-check.v1). This is a reference architecture for risk engineers, not legal advice, and not an automated hire/fire or credit decision.

Key takeaways

• Do not replace Aadhaar, PAN, UAN, or address checks with LegalCheck. Compose them.
• Trigger on a stable business event (offer accepted, vendor created, loan stage gate), not on every form keystroke.
• Put a practical purpose string in config.purpose, reuse Idempotency-Key for ATS retries, poll status, honour Retry-After.
• Persist code, client_ref_no, risk.band, and match CNRs. Do not dump full subject PII into your analytics warehouse.
• min_score starting points below are labelled STARTING POINTS NOT POLICY. Tune with your counsel and ops team.
• Show the candidate a calm summary. Keep full match lists and low-confidence noise internal until a human reviews.

Where LegalCheck sits in the stack

Court-record screening is one module inside employment BGV, lending KYC, or vendor KYB. Your identity and employment stack stays authoritative for “who is this person” and “where did they work”. LegalCheck answers a narrower question: given the name and corroborators you already collected, which public court matters look like plausible matches, and what risk band does model eCI-1.2 assign?

Product UI for manual checks: legalcheck.ecourtsindia.com. Partner REST docs: ecourtsindia.com/api/docs. Pricing (confirm live figures before modelling volume): ecourtsindia.com/api/pricing. Hub and deep guides: LegalCheck product hub, API cookbook, how to read a report, LegalCheck vs case search.

Consent and config.purpose (practical, not a legal opinion)

Your privacy notice and candidate consent text belong to your counsel and your DPDP programme. What LegalCheck needs from you on the wire is a short purpose label in config.purpose, plus optional client_ref_no and ticket_size for your own reconciliation. Treat purpose as operational metadata that matches the consent string you already showed the person or vendor, not as a substitute for that consent.

Practical patterns partners use (examples only):

Flow	Example config.purpose	Example client_ref_no
Employment BGV after offer	employment_bgv_court_check	ATS-OFFER-88421
Gig / marketplace onboarding	gig_worker_court_screen	GIG-USER-10992
NBFC / BFSI underwriting gate	loan_underwriting_court_check	LOS-APP-55102
Vendor KYB (company)	vendor_kyb_court_check	VENDOR-1042
Director screen under a vendor	vendor_director_court_check	VENDOR-1042-DIR-3

Pin config.model to eCI-1.2 (or whatever GET /api/partner/legal-check/models returns). Do not invent model ids. Keep purpose strings stable so your ops team can filter list results and audit who ran what.

Sequence: offer / vendor created to submit to poll to attach

1. Gate. Wait until identity fields you will send are frozen (name as on ID, father/relative name if collected, DOB, city/state addresses). Do not fire LegalCheck on every draft edit.
2. Submit. POST /api/partner/legal-check with Bearer token, JSON body, and Idempotency-Key derived from your ATS/LOS id (see idempotency section).
3. Persist. Save data.code (for example LC-A1B2C3D), status_url, report_url, client_ref_no, and meta.request_id on the application row.
4. Poll. GET /api/partner/legal-check/{code} while status is queued or running. Honour Retry-After (live checks on 3 September 2026 returned 5 seconds). Do not hammer report.
5. Report. Only after completed, call GET .../report with your chosen verbosity and min_score. Early report calls return 409 NOT_READY.
6. Compose. Write risk.band, risk.identity_confidence, match count, and a table of CNR / court / role / match_band into your PDF or internal report object. Link each CNR to the eCourtsIndia case URL from the match payload.
7. Route. Auto-attach LOW clean reports to the dossier. Send MEDIUM/HIGH or noisy common-name piles to a human queue before adverse action.

Billing reminder: a newly accepted submit is charged once. Status, report, list, and models reads are free. Confirm the rupee figure on the pricing page. Cap: at most three jobs queued or running per partner (429 LEGAL_CHECK_QUEUE_FULL). Typical completion is on the order of 1-3 minutes; estimated_seconds on submit is advisory, not an SLA.

Minimal submit sketch (individual hire)

curl -X POST "https://webapi.ecourtsindia.com/api/partner/legal-check" \
  -H "Authorization: Bearer eci_live_YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ats-offer-88421-court-v1" \
  -d '{
  "subject_type": "individual",
  "subject": {
    "name": "Candidate Name As On ID",
    "father_name": "Relative Name If Collected",
    "date_of_birth": "1990-06-15",
    "addresses": ["Bengaluru, Karnataka"],
    "aliases": ["Optional Prior Name"]
  },
  "config": {
    "model": "eCI-1.2",
    "purpose": "employment_bgv_court_check",
    "client_ref_no": "ATS-OFFER-88421"
  }
}'

Full cURL / Python / Node flows, status states, and error table: LegalCheck API cookbook. Field-level reading of bands and match confidence: How to read a LegalCheck report.

Individual hire vs company vendor (directors)

Individual (employment BGV / gig / borrower)

• subject_type: individual
• Required: subject.name
• Strong corroborators: father_name, date_of_birth, city/state addresses, aliases
• One LegalCheck job per person per screening event
• Reuse the same identity payload your BGV stack already normalised after ID verification

Company (vendor KYB / counterparty)

• subject_type: company
• Required: subject.company_name
• Optional context you already hold from registry KYB: cin, gst, pan, registered_addresses, directors, company_type
• Those identifiers are partner-supplied context. Their presence does not mean LegalCheck independently verified an MCA filing.

Directors: separate individual jobs

For vendor KYB, most risk teams want both the company as a party and the people who control it. Recommended pattern today:

• Job A: company subject with client_ref_no like VENDOR-1042
• Jobs B to N: one individual submit per director (name + father/DOB/address if you have them), client_ref_no like VENDOR-1042-DIR-1
• Respect the three in-flight cap: queue director jobs behind the company job, or stagger with a small worker pool
• Compose one vendor dossier: company band + director bands + all CNRs

There is no batch-submit endpoint yet. Do not rotate idempotency keys to bypass the in-flight cap.

min_score starting points (STARTING POINTS NOT POLICY)

Report query parameter min_score is 0-100 (API default 40). Raising it hides lower-confidence matches from the returned list. It does not change the underlying job. These are engineering starting points for first pilots. They are not eCourtsIndia policy, not legal advice, and not a substitute for your risk matrix.

Use case	Suggested start min_score	Suggested verbosity	Notes (still STARTING POINTS NOT POLICY)
IT / corporate hire (office roles)	50	standard, then compact for candidate PDF	Common names still need human review. Prefer father + city before lowering the floor.
Gig / marketplace worker	45	compact for ops queue	Speed matters. Auto-clear only on empty/LOW with strong identity anchors.
BFSI / NBFC underwriting	40 (default), review MEDIUM+	standard or full for credit ops	Keep a human gate. Pair with your existing bureau/fraud stack. Never auto-reject on name alone.
Vendor KYB (company)	40	standard	Company + director jobs. Watch NCLT/IBC-style matters carefully in your review queue.

If the band feels wrong, do not silently raise min_score forever. Open the CNR, read the order if needed via the case/order APIs, and use the report literacy guide. Feedback loop for us is at the end of this post.

Idempotency for ATS and LOS retries

Offer workflows double-fire. Webhooks retry. Recruiters click “Run BGV” twice. Treat LegalCheck submit like a payment intent.

• Send Idempotency-Key (1-255 characters) on every submit.
• Derive it from a stable business key, for example ats-offer-88421-court-v1 or los-app-55102-court-v1.
• Reuse the same key with the same JSON body after timeouts. Live behaviour: replay returns the original data.code without a second charge.
• Same key with a different body returns 409 IDEMPOTENCY_CONFLICT. Bump a version suffix (-v2) only when the subject payload deliberately changed (name correction after ID fix).
• Store the mapping client_ref_no to code in your DB so a late retry can short-circuit to status/report without a new POST.

What to show the candidate vs keep internal

Adverse-action hygiene is your policy. The split below is an engineering default that keeps noise and over-claiming out of candidate inboxes.

Surface	Show	Keep internal
Candidate / vendor self-serve	That a court-record screen was run; date; overall status (in progress / completed / needs review); if you disclose matches, only confirmed CNRs a human already verified, with a clear “public court record, not a finding of guilt” line	Raw possible piles; internal scores; excluded candidates; engine notes; full address lists you sent; other applicants’ data
Recruiter / credit ops PDF	risk.band, identity confidence, match table (CNR, court, case type, role/side, match_band, dates), coverage/limitations/disclaimer from the report, deep links to case pages	API tokens; idempotency keys; full request JSON with excess PII in logs
Automated decisioning	Nothing that auto-rejects solely on a name hit	Any rule that treats match_band=possible as proven identity

A match is a candidate to investigate, not proof of wrongdoing. Common names produce many rows. Verify identity and the underlying order before any adverse step. That principle is also spelled out in the report reading guide.

What not to ask LegalCheck to do

• Not FIR / police verification
• Not Aadhaar, PAN, or UAN verification
• Not a 99% “clear” certificate you can rubber-stamp into HRIS
• Not a replacement for exploratory party research (use case search vs LegalCheck for that routing)
• Not an MCP tool yet (partner REST only under /api/partner/legal-check)

Production checklist

• Separate staging and production API tokens; name them in the dashboard
• Queue worker with concurrency at most 3 LegalCheck jobs in flight
• Honour Retry-After; treat 409 NOT_READY as keep polling
• On failed, keep code + meta.request_id for support; terminal processing failures are refunded once
• Persist band + CNRs on the application; re-fetch report later with different min_score without recharging
• Human review queue for HIGH, for MEDIUM when identity confidence is weak, and for very common names

Feedback we want from design partners

Send a redacted payload that failed matching. Strip phone numbers and full street lines if you must, but keep the name shape, father/relative name (if any), DOB year, city/state, and what you expected to find (a known CNR is ideal). We will tell you which anchor would have helped (father name, alias, city, DOB, director expansion, and so on). Prefer job code + meta.request_id over raw tokens.

FAQ

---

Soft CTA: partner sandbox

If you are wiring LegalCheck into an employment screen, NBFC underwriting gate, or vendor KYB dossier, start with a sandbox token, one individual job, and one company-plus-director set. Product: legalcheck.ecourtsindia.com. API home: ecourtsindia.com/api. Docs: ecourtsindia.com/api/docs. Pricing: ecourtsindia.com/api/pricing. Keys: dashboard settings.

Read next: LegalCheck product hub | Submit, poll, report cookbook | How to read a report | When to score vs when to search | Full partner API guide

Sources

Live partner LegalCheck surface under https://webapi.ecourtsindia.com/api/partner/legal-check, verified 3 September 2026 (model eCI-1.2, schema legal-check.v1). Product UI legalcheck.ecourtsindia.com. API docs ecourtsindia.com/api/docs. Pricing ecourtsindia.com/api/pricing. Case index described as a 28 crore+ floor across Supreme Court, High Courts, district courts, and 18 tribunal families.