Parties Watchlist API
API To Watch The Companies And People You Deal With For Litigation Across India
The Parties Watchlist API lets you add a party, a company or a person you deal with, say what they are to you, and have CasePrimus.ai look for court cases against them across India. Built for vendor onboarding, lending, due diligence and counterparty monitoring, it watches the signals that belong to that relationship instead of every signal for everyone.
A party can be assessed once, or watched continuously as the courts publish. Cases that are found wait in a review queue: accept the ones that really are about your party and they are monitored from then on. Each party carries its findings, a risk level, and what changed since you last looked.
Built on certified infrastructure
CasePrimus.ai is operated by Pegadroid IQ Solutions Private Limited, the legal entity behind Attestr's products, which holds ISO/IEC 27001:2022 certification. Data is hosted in India (AWS Mumbai, ap-south-1) and every connection is encrypted in transit. See Trust & Compliance.
Key capabilities
Companies and people
Add a BUSINESS or a PERSON. Registration numbers, addresses and name variations sharpen the match.
Say what they are to you
entityCategories records the relationship, such as a supplier or a borrower, and a party can be more than one thing. It decides which signals are watched.
Signals that fit the relationship
Leave signals out to use the defaults for the party's categories, or choose your own. GET /parties/catalog lists every category and signal.
Once, or continuously
ONE_OFF assesses the party once. MONITOR assesses it, then keeps watching as the courts publish. A party can move between the two without being added again.
A review queue for what is found
Cases found for your parties wait for you. Accept one and it is monitored. Decline it and it stays on the party's record as declined.
Every case, with its risk level
A party's findings list each case with its risk level, the signals it answers and where it stands for that party.
What changed since you last looked
List new cases, new orders, risk moves, hearings and status changes for a party in one call.
Webhooks for every change
Push new cases, review-queue arrivals, hearing changes and risk moves to your own endpoint, signed and retried automatically.
How it works
- 1
Add a party
Send a company or a person, and what they are to you, to
POST /parties. You do this once. - 2
We search India's courts
CasePrimus.ai looks for cases against the party across courts and tribunals, and keeps looking if you chose
MONITOR. - 3
Review what is found
Found cases wait in the review queue. Accept the ones that are about your party, and decline the rest.
- 4
Read the findings, and get alerted
Each party carries its cases, their risk levels and what changed. Alerts appear in your dashboard and are pushed to your endpoint by webhook.
API definition
Read the signal catalogue
Lists every party family, entity category, signal family and signal CasePrimus knows about, with the signals that are always on. It is the same for every customer. What differs per customer is which signals a given party has switched on.
Read it rather than hard-coding a signal list. availability is court coverage, not importance: a signal marked NOT_AVAILABLE is still listed and still selectable, because knowing that a kind of record is not published is part of the answer. One category, other.custom ("Custom / Other"), is for a party none of the others describes. It preselects nothing but the always-on signals, and every other signal is your own choice.
Request URL
https://api.caseprimus.ai/api/caseprimus/v1/parties/catalogRequest headers
| Type | Name | Value / description | Optional |
|---|---|---|---|
| String | X-CasePrimus-Api-Key | Your API key: {apiKey} | Required |
No API key yet? See Authentication.
Sample request
BASE="https://api.caseprimus.ai/api/caseprimus/v1" curl "$BASE/parties/catalog" \ -H "X-CasePrimus-Api-Key: $CASEPRIMUS_API_KEY"
const BASE = "https://api.caseprimus.ai/api/caseprimus/v1"; const res = await fetch(BASE + "/parties/catalog", { method: "GET", headers: { "X-CasePrimus-Api-Key": process.env.CASEPRIMUS_API_KEY, }, }); const data = await res.json();
import os import requests BASE = "https://api.caseprimus.ai/api/caseprimus/v1" res = requests.request( "GET", BASE + "/parties/catalog", headers={"X-CasePrimus-Api-Key": os.environ["CASEPRIMUS_API_KEY"]}, ) data = res.json()
Responses
| 200 | The whole catalogue. |
| 403 | The caller lacks watchlist.read. |
Response fields (HTTP 200)
| Field | Description |
|---|---|
partyFamiliesarray of object | |
entityCategoriesarray of object | |
signalFamiliesarray of object | |
signalsarray of object | |
idstring | |
familystring | |
namestring | |
aboutstring | |
availabilityenum | Court coverage, not importance. `NOT_AVAILABLE` means no court or registry publishes the data - labour court dockets, pollution board orders, SEBI penalties. Such a signal is still listed and still selectable, because knowing nobody publishes it is the point: it stops an empty finding from reading as good news. LIVEPARTIALNOT_AVAILABLE |
kindenum | `CLASSIFICATION` is what kind of case this is, and a single case can be assigned to it - 121 of the 133. `DERIVED` is computed across the party's whole case set, never from one case: filing velocity, respondent-side concentration, the adversary map. CLASSIFICATIONDERIVED |
alwaysOnarray of enum | insolvency.petitioninsolvency.admittedinsolvency.liquidationinsolvency.resolvedinsolvency.s95.personalinsolvency.nclat.appealinsolvency.avoidance.preferentialsecured.drt.recoverysecured.drat.appealsecured.sarfaesi.enforcementsecured.recovery.certificatesecured.enforcement.samecheque.s138cheque.velocitycheque.s148.appellatecheque.other.instrumentscivil.summary.suitcivil.commercial.courtcivil.original.sidecivil.specific.performancecivil.executionarbitration.s9.interimarbitration.s11.arbitratorarbitration.s34.challengearbitration.s36.enforcementarbitration.s37.appealtax.income.itattax.indirect.cestattax.gst.appellatetax.recovery.attachmenttax.writtax.prosecution.statutorycorporate.oppression.mismanagementcorporate.company.compromisecorporate.director.disqualificationcorporate.class.actioncorporate.serious.fraudsecurities.sat.appealsecurities.sebi.penaltiessecurities.rbi.enforcementsecurities.wilful.defaulterconsumer.complaintconsumer.volume.patternconsumer.unfair.tradeproperty.title.partitionproperty.land.acquisitionproperty.tenancy.evictionproperty.mortgage.chargelabour.industrial.disputelabour.epf.s7alabour.epfo.defaulterlabour.esilabour.writ.employmentlabour.wage.gratuitylabour.factory.safetyenvironment.ngtenvironment.pcbenvironment.writenvironment.aptelenvironment.tdsatenvironment.competition.appealscriminal.economiccriminal.directorscriminal.quashingcriminal.bail.anticipatorycriminal.fir.registrationip.infringementip.passing.offip.injunctionappeal.supreme.courtappeal.high.courtappeal.adverse.orderappeal.costs.imposedappeal.adverse.judicialbehaviour.filing.velocitybehaviour.respondent.sidebehaviour.creditor.diversitybehaviour.escalation.ratebehaviour.adjournment.delaybehaviour.abandonmentbehaviour.forum.spreadbehaviour.counsel.churnbehaviour.dormancy.breaknetwork.adversary.mapnetwork.coparty.mapnetwork.shared.counselnetwork.common.addressnetwork.group.companyregistry.mca.statusregistry.registered.securedregistry.directorship.signatoryregistry.related.companyregistry.gstin.statusregistry.udyam.msmeregistry.filed.financialsregistry.credit.bureauextended.guarantee.enforcementextended.franchise.distributionextended.agency.commissionextended.carriage.cargoextended.admiralty.shipextended.demurrage.detentionextended.customs.valuationextended.debarment.blacklistingextended.insurance.coverageextended.motor.mactextended.medical.negligenceextended.insurance.fraudextended.repeat.claimantextended.non.competeextended.professional.disciplinaryextended.encumbrance.competingprovider.deempanelmentprovider.clinical.establishmentprovider.fire.safetyprovider.biomedical.hazardousprovider.drug.pharmacyprovider.regulated.practiceprovider.counterfeit.spuriousprovider.workshop.licensingsector.product.liabilitysector.fssaisector.metrologysector.nppa.pricesector.patent.linkagesector.clinical.trialsector.public.liabilitysector.miningsector.forest.clearancesector.essential.commoditiessector.bissector.epr.wastesector.data.protection |
partySidesarray of string |
{
"partyFamilies": [
{
"id": "credit.finance",
"number": 1,
"name": "Credit and finance",
"launch": true,
"description": "Companies you have lent money to, or who owe you money."
}
],
"entityCategories": [
{
"id": "vendor",
"name": "Vendor / Supplier",
"familyNumber": 2,
"description": "They make or supply what you sell, or a part or material you depend on.",
"launch": true,
"defaultSignalCount": 14,
"suggestedSignalCount": 19
},
{
"id": "other.custom",
"name": "Custom / Other",
"familyNumber": 0,
"description": "None of the relationships above describes this one. We run only the checks that always run, and you choose the rest yourself.",
"launch": true,
"defaultSignalCount": 0,
"suggestedSignalCount": 0
}
],
"signalFamilies": [
{
"id": "insolvency",
"number": 1,
"name": "Insolvency and bankruptcy"
}
],
"signals": [
{
"id": "cheque.s138",
"family": "cheque",
"availability": "LIVE",
"kind": "CLASSIFICATION",
"name": "Section 138 NI Act complaint (cheque dishonour)",
"about": "Criminal complaint for a bounced cheque. Individually small, collectively the earliest reliable liquidity signal in Indian litigation data, and frequently the first thing visible months before a formal default."
}
],
"alwaysOn": [
"insolvency.petition",
"insolvency.admitted",
"insolvency.liquidation"
],
"partySides": [
"PETITIONER",
"RESPONDENT",
"BOTH"
]
}Add a party
Adds a party, a company or a person you deal with, and starts watching for court cases against it. entityCategories says what the party is to you, such as a supplier or a borrower, and it can be more than one thing. It decides which signals are watched. There is no default, because only you know the relationship. mode is MONITOR to keep watching as the courts publish, or ONE_OFF to assess the party once. A party can move between the two later without being added again.
Send no signals and the selection is seeded from the category's defaults, which is the normal path. Send signals to choose your own, and declined to record the ones you switched off. A declined signal stays off even if the category's defaults change later. The always-on signals are added whatever you send and cannot be declined.
This call starts work and can be charged against your plan. Both modes run a litigation report on the party, and a monitored party is also kept under watch afterwards. If your plan does not allow it, the call is refused and nothing is stored.
Request URL
https://api.caseprimus.ai/api/caseprimus/v1/partiesRequest headers
| Type | Name | Value / description | Optional |
|---|---|---|---|
| String | Content-Type | application/json | Required |
| String | X-CasePrimus-Api-Key | Your API key: {apiKey} | Required |
No API key yet? See Authentication.
Input parameters
| Field | Description |
|---|---|
namestring Required | 2 to 255 characters |
entityTypeenum Required | PERSONBUSINESS |
entityCategoriesarray of enum Required | What this party is to you - and it can be more than one thing. A company can be your vendor AND your borrower, watched for different things; the seeded selection is then the UNION, because you carry both exposures and the narrower answer would be the wrong one. at least 1 item borrower.equipmentborrower.receivablesborrower.securedborrower.unsecuredcolendercollateral.providerguarantortrade.counterpartyagentchannel.partnerlogisticsservice.providervendoracquisition.targetgroup.companyjoint.venturekey.hireprofessionalpromoterclaimantinsuredinsured.assetprovider.empanelmentprovider.leakagereinsurancesubrogationlandlordtenantgovernmentopposing.partyown.entityother.customlenderdebt.assigneeplatform.fintechprincipal.brandacquirer.parentinvestor.funddivesting.sellerinsurerbroker.intermediary |
modeenum Required | `ONE_OFF` is a one-time report and nothing else. `MONITOR` is that same report plus ongoing monitoring - a superset, not a different product. `scope.tier` applies to both: it decides how the party's EXISTING cases are assessed. It does not describe a watched case - monitoring reads every order as it publishes, which is deeper than either tier. ONE_OFFMONITOR |
skipReportboolean Optional | Add the party and run NO report. The party starts empty and watches from here on: no litigation report, no historical back-catalogue fetch, and nothing billed at add time, because nothing was produced. Cases arrive as the courts publish them and as you add them yourself. `MONITOR` only - a one-off party IS its report, so this is refused on one (61494). |
nameVariationsarray of string or null Optional | Other spellings of the same company. Courts record whatever was typed on the cause list, so one name finds a fraction of them. |
autoNameVariationsboolean Optional | Ask us to derive further spellings in addition to the ones you send. |
identifiersany or null Optional | How to recognise them - the litigation report's own shape, so one body serves both. Either a typed list or one comma-separated string. A bare string is stored with a null `type`: we never guess the type from the pattern, because a wrong type is worse than none when matching trusts it. |
addressesarray of object or null Optional | Up to three - a registered office and the one or two places they actually operate from. The litigation report takes five; a watched party does not need them. |
labelstring or null Optional | up to 60 characters |
linestring or null Optional | up to 400 characters |
citystring or null Optional | up to 100 characters |
districtstring or null Optional | up to 100 characters |
statestring or null Optional | up to 100 characters |
pincodestring or null Optional | |
registrationNumberstring or null Optional | The watchlist entity's older free-text spelling of `identifiers`. Derived from them when you send those up to 100 characters |
locationstring or null Optional | The older free-text spelling of `addresses` up to 4192 characters |
tagstring or null Optional | up to 100 characters |
fatherNamestring or null Optional | up to 256 characters |
birthDatestring or null Optional | |
labelsarray of string or null Optional | |
signalsarray of enum Optional | Omit to seed from the categories' defaults - the union of them - which is the normal path. insolvency.petitioninsolvency.admittedinsolvency.liquidationinsolvency.resolvedinsolvency.s95.personalinsolvency.nclat.appealinsolvency.avoidance.preferentialsecured.drt.recoverysecured.drat.appealsecured.sarfaesi.enforcementsecured.recovery.certificatesecured.enforcement.samecheque.s138cheque.velocitycheque.s148.appellatecheque.other.instrumentscivil.summary.suitcivil.commercial.courtcivil.original.sidecivil.specific.performancecivil.executionarbitration.s9.interimarbitration.s11.arbitratorarbitration.s34.challengearbitration.s36.enforcementarbitration.s37.appealtax.income.itattax.indirect.cestattax.gst.appellatetax.recovery.attachmenttax.writtax.prosecution.statutorycorporate.oppression.mismanagementcorporate.company.compromisecorporate.director.disqualificationcorporate.class.actioncorporate.serious.fraudsecurities.sat.appealsecurities.sebi.penaltiessecurities.rbi.enforcementsecurities.wilful.defaulterconsumer.complaintconsumer.volume.patternconsumer.unfair.tradeproperty.title.partitionproperty.land.acquisitionproperty.tenancy.evictionproperty.mortgage.chargelabour.industrial.disputelabour.epf.s7alabour.epfo.defaulterlabour.esilabour.writ.employmentlabour.wage.gratuitylabour.factory.safetyenvironment.ngtenvironment.pcbenvironment.writenvironment.aptelenvironment.tdsatenvironment.competition.appealscriminal.economiccriminal.directorscriminal.quashingcriminal.bail.anticipatorycriminal.fir.registrationip.infringementip.passing.offip.injunctionappeal.supreme.courtappeal.high.courtappeal.adverse.orderappeal.costs.imposedappeal.adverse.judicialbehaviour.filing.velocitybehaviour.respondent.sidebehaviour.creditor.diversitybehaviour.escalation.ratebehaviour.adjournment.delaybehaviour.abandonmentbehaviour.forum.spreadbehaviour.counsel.churnbehaviour.dormancy.breaknetwork.adversary.mapnetwork.coparty.mapnetwork.shared.counselnetwork.common.addressnetwork.group.companyregistry.mca.statusregistry.registered.securedregistry.directorship.signatoryregistry.related.companyregistry.gstin.statusregistry.udyam.msmeregistry.filed.financialsregistry.credit.bureauextended.guarantee.enforcementextended.franchise.distributionextended.agency.commissionextended.carriage.cargoextended.admiralty.shipextended.demurrage.detentionextended.customs.valuationextended.debarment.blacklistingextended.insurance.coverageextended.motor.mactextended.medical.negligenceextended.insurance.fraudextended.repeat.claimantextended.non.competeextended.professional.disciplinaryextended.encumbrance.competingprovider.deempanelmentprovider.clinical.establishmentprovider.fire.safetyprovider.biomedical.hazardousprovider.drug.pharmacyprovider.regulated.practiceprovider.counterfeit.spuriousprovider.workshop.licensingsector.product.liabilitysector.fssaisector.metrologysector.nppa.pricesector.patent.linkagesector.clinical.trialsector.public.liabilitysector.miningsector.forest.clearancesector.essential.commoditiessector.bissector.epr.wastesector.data.protection |
declinedarray of enum Optional | insolvency.petitioninsolvency.admittedinsolvency.liquidationinsolvency.resolvedinsolvency.s95.personalinsolvency.nclat.appealinsolvency.avoidance.preferentialsecured.drt.recoverysecured.drat.appealsecured.sarfaesi.enforcementsecured.recovery.certificatesecured.enforcement.samecheque.s138cheque.velocitycheque.s148.appellatecheque.other.instrumentscivil.summary.suitcivil.commercial.courtcivil.original.sidecivil.specific.performancecivil.executionarbitration.s9.interimarbitration.s11.arbitratorarbitration.s34.challengearbitration.s36.enforcementarbitration.s37.appealtax.income.itattax.indirect.cestattax.gst.appellatetax.recovery.attachmenttax.writtax.prosecution.statutorycorporate.oppression.mismanagementcorporate.company.compromisecorporate.director.disqualificationcorporate.class.actioncorporate.serious.fraudsecurities.sat.appealsecurities.sebi.penaltiessecurities.rbi.enforcementsecurities.wilful.defaulterconsumer.complaintconsumer.volume.patternconsumer.unfair.tradeproperty.title.partitionproperty.land.acquisitionproperty.tenancy.evictionproperty.mortgage.chargelabour.industrial.disputelabour.epf.s7alabour.epfo.defaulterlabour.esilabour.writ.employmentlabour.wage.gratuitylabour.factory.safetyenvironment.ngtenvironment.pcbenvironment.writenvironment.aptelenvironment.tdsatenvironment.competition.appealscriminal.economiccriminal.directorscriminal.quashingcriminal.bail.anticipatorycriminal.fir.registrationip.infringementip.passing.offip.injunctionappeal.supreme.courtappeal.high.courtappeal.adverse.orderappeal.costs.imposedappeal.adverse.judicialbehaviour.filing.velocitybehaviour.respondent.sidebehaviour.creditor.diversitybehaviour.escalation.ratebehaviour.adjournment.delaybehaviour.abandonmentbehaviour.forum.spreadbehaviour.counsel.churnbehaviour.dormancy.breaknetwork.adversary.mapnetwork.coparty.mapnetwork.shared.counselnetwork.common.addressnetwork.group.companyregistry.mca.statusregistry.registered.securedregistry.directorship.signatoryregistry.related.companyregistry.gstin.statusregistry.udyam.msmeregistry.filed.financialsregistry.credit.bureauextended.guarantee.enforcementextended.franchise.distributionextended.agency.commissionextended.carriage.cargoextended.admiralty.shipextended.demurrage.detentionextended.customs.valuationextended.debarment.blacklistingextended.insurance.coverageextended.motor.mactextended.medical.negligenceextended.insurance.fraudextended.repeat.claimantextended.non.competeextended.professional.disciplinaryextended.encumbrance.competingprovider.deempanelmentprovider.clinical.establishmentprovider.fire.safetyprovider.biomedical.hazardousprovider.drug.pharmacyprovider.regulated.practiceprovider.counterfeit.spuriousprovider.workshop.licensingsector.product.liabilitysector.fssaisector.metrologysector.nppa.pricesector.patent.linkagesector.clinical.trialsector.public.liabilitysector.miningsector.forest.clearancesector.essential.commoditiessector.bissector.epr.wastesector.data.protection |
scopeobject Optional | WHERE TO LOOK. The same inputs a litigation report takes, asked once for the whole party. Which side of a case to look on is here rather than on each signal: it is the same question asked once instead of 133 times, and it is the control a customer already recognises. |
partyTypeenum Optional | Which side of a case to look for this party on. Defaults to BOTH - narrowing to one side silently hides half the cases. PETITIONERRESPONDENTBOTH |
tierenum Optional | BASIC reads the court record. ADVANCED also reads the order documents, which is what lets a signal be classified from what a judge wrote rather than only from the index entry. Defaults to BASIC, so nobody is moved onto the paid tier by omission. BASICADVANCED |
caseStatusenum Optional | ALLPENDINGDISPOSED |
fromYearinteger or null Optional | |
toYearinteger or null Optional | |
courtTypesarray of enum Optional | Which courts to go looking in. Empty means every court. OTHER covers tribunals, consumer commissions and anything unplaceable. SCHCDCOTHER |
maxCasesinteger Optional | How many cases the one-off HISTORICAL search covers, newest first. Raised to 10,000 on. This is not a limit on how many cases a party may hold: cases added to monitoring directly are not bounded by it. Your plan's own `maxCasesPerReport` can still clamp a report below this number. 25 to 10000 |
sortenum Optional | The default ordering for this party's findings. A findings view can still sort differently; this is what it opens on. score_descfiling_descfiling_ascorder_adverseorder_favourable |
Sample request
BASE="https://api.caseprimus.ai/api/caseprimus/v1" curl -X POST "$BASE/parties" \ -H "X-CasePrimus-Api-Key: $CASEPRIMUS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Acme Logistics Private Limited", "entityType": "BUSINESS", "entityCategories": [ "vendor", "borrower.unsecured" ], "mode": "MONITOR", "identifiers": [ { "type": "CIN", "value": "U63090MH2015PTC123456" }, { "type": "GSTIN", "value": "27AABCA1234D1ZV" } ], "addresses": [ { "label": "Registered office", "line": "14 Marine Lines", "city": "Mumbai", "state": "Maharashtra", "pincode": "400020" } ], "nameVariations": [ "Acme Logistics Pvt Ltd" ], "autoNameVariations": true, "tag": "VEND-001", "labels": [ "tier-1" ] }'
const BASE = "https://api.caseprimus.ai/api/caseprimus/v1"; const res = await fetch(BASE + "/parties", { method: "POST", headers: { "Content-Type": "application/json", "X-CasePrimus-Api-Key": process.env.CASEPRIMUS_API_KEY, }, body: JSON.stringify({ "name": "Acme Logistics Private Limited", "entityType": "BUSINESS", "entityCategories": [ "vendor", "borrower.unsecured" ], "mode": "MONITOR", "identifiers": [ { "type": "CIN", "value": "U63090MH2015PTC123456" }, { "type": "GSTIN", "value": "27AABCA1234D1ZV" } ], "addresses": [ { "label": "Registered office", "line": "14 Marine Lines", "city": "Mumbai", "state": "Maharashtra", "pincode": "400020" } ], "nameVariations": [ "Acme Logistics Pvt Ltd" ], "autoNameVariations": true, "tag": "VEND-001", "labels": [ "tier-1" ] }), }); const data = await res.json();
import os import requests BASE = "https://api.caseprimus.ai/api/caseprimus/v1" res = requests.request( "POST", BASE + "/parties", headers={"X-CasePrimus-Api-Key": os.environ["CASEPRIMUS_API_KEY"]}, json={ "name": "Acme Logistics Private Limited", "entityType": "BUSINESS", "entityCategories": ["vendor", "borrower.unsecured"], "mode": "MONITOR", "identifiers": [ { "type": "CIN", "value": "U63090MH2015PTC123456", }, { "type": "GSTIN", "value": "27AABCA1234D1ZV", }, ], "addresses": [ { "label": "Registered office", "line": "14 Marine Lines", "city": "Mumbai", "state": "Maharashtra", "pincode": "400020", }, ], "nameVariations": ["Acme Logistics Pvt Ltd"], "autoNameVariations": True, "tag": "VEND-001", "labels": ["tier-1"], }, ) data = res.json()
Responses
| 200 | The party as it now stands. |
| 400 | Malformed input (60001), an unknown entity category (61484) or signal (61486), an always-on signal declined (61487), other.custom combined with another category (61489), or a reference already in use (61483). |
Response fields (HTTP 200)
| Field | Description |
|---|---|
_idstring | |
numberstring or null | |
namestring | |
entityTypeenum | PERSONBUSINESS |
riskobject or null | The company's reputation score and litigation level, from the report that answered this party - a party has no score of its own. Sent on the LIST so a page of parties can be ranked and read without fetching a report per row; null while the report is still running, and on one that found no cases. |
scoreinteger or null | 0-1000, higher is better. |
scaleinteger | |
levelenum or null | VERY_HIGHHIGHMODERATELOWMINIMAL |
pendingReviewinteger | How many findings on this party are waiting for your decision - the same set `GET /parties/{partyId}/findings?tab=pending` returns, counted here so a page of parties can show where the work is without a request per row. Sent on the LIST. Zero means nothing is waiting, and a `ONE_OFF` party is always zero: it assesses once and discovers nothing after. |
monitoredCasesinteger | How many cases are being followed for this party - the same set `GET /parties/{partyId}/findings?tab=monitored` returns. Sent on the LIST. A case we are still checking the identifiers of counts here: it is being followed either way. |
casesFoundinteger or null | How many cases the opening report found. Sent on the LIST, read off the report's stored summary. Null - not zero - while that report is still running, because "we found none" and "we have not finished looking" are opposite answers. |
entityCategoriesarray of enum | What this party is to you, and it can be more than one thing. Decides which signals apply, so there is no default - read GET /parties/catalog for the list. borrower.equipmentborrower.receivablesborrower.securedborrower.unsecuredcolendercollateral.providerguarantortrade.counterpartyagentchannel.partnerlogisticsservice.providervendoracquisition.targetgroup.companyjoint.venturekey.hireprofessionalpromoterclaimantinsuredinsured.assetprovider.empanelmentprovider.leakagereinsurancesubrogationlandlordtenantgovernmentopposing.partyown.entityother.customlenderdebt.assigneeplatform.fintechprincipal.brandacquirer.parentinvestor.funddivesting.sellerinsurerbroker.intermediary |
categoriesarray of object | The same list with the names and families a screen renders, so a reader need not carry the catalogue. `retired` marks an id the catalogue no longer knows - reported rather than dropped. |
idstring | |
namestring or null | |
partyFamilystring or null | |
partyFamilyNamestring or null | |
retiredboolean | |
modeenum | `MONITOR` keeps looking as the courts publish, which is what the watchlist did. `ONE_OFF` assesses once, which is what a litigation report did. A party moves between them without being re-added - a one-off assessment that comes back badly is exactly the party you then want watched. ONE_OFFMONITOR |
statusenum | ACTIVEARCHIVED |
nameVariationsarray of string | Other spellings of the same company |
autoNameVariationsboolean | Whether you asked us to derive further spellings as well. |
identifiersarray of object | Always the typed shape here, whichever of the two accepted shapes you sent. `type` is null for an identifier sent as a bare string - we never guess it. |
typeenum or null | CINPANGSTINUDYAMOTHERnull |
valuestring | |
addressesarray of object | Up to three. An address with every field empty is dropped rather than stored, so a count of these means what it says. |
labelstring or null | |
linestring or null | |
citystring or null | |
districtstring or null | |
statestring or null | |
pincodestring or null | |
registrationNumberstring or null | The watchlist entity's older free-text spelling of `identifiers` up to 100 characters |
locationstring or null | The older free-text spelling of `addresses` |
tagstring or null | Your own reference for this party. Unique among your active parties; archiving frees it. |
fatherNamestring or null | PERSON only. Identifying metadata |
birthDatestring or null | |
labelsarray of string | |
signalsarray of object | |
signalstring | |
namestring or null | |
familystring or null | |
availabilityenum or null | LIVEPARTIALNOT_AVAILABLE |
kindenum or null | CLASSIFICATIONDERIVED |
retiredboolean | A signal stored on this party that the catalogue no longer knows. Reported rather than dropped, so the party never looks narrower than it is. |
declinedSignalsarray of string | What you switched off. Remembered rather than merely absent, so a later change to the category's defaults can never switch one back on - a signal declined on purpose is a decision. |
scopeobject | WHERE TO LOOK. The same inputs a litigation report takes, asked once for the whole party. Which side of a case to look on is here rather than on each signal: it is the same question asked once instead of 133 times, and it is the control a customer already recognises. |
partyTypeenum | Which side of a case to look for this party on. Defaults to BOTH - narrowing to one side silently hides half the cases. PETITIONERRESPONDENTBOTH |
tierenum | BASIC reads the court record. ADVANCED also reads the order documents, which is what lets a signal be classified from what a judge wrote rather than only from the index entry. Defaults to BASIC, so nobody is moved onto the paid tier by omission. BASICADVANCED |
caseStatusenum | ALLPENDINGDISPOSED |
fromYearinteger or null | |
toYearinteger or null | |
courtTypesarray of enum | Which courts to go looking in. Empty means every court. OTHER covers tribunals, consumer commissions and anything unplaceable. SCHCDCOTHER |
maxCasesinteger | How many cases the one-off HISTORICAL search covers, newest first. Raised to 10,000 on. This is not a limit on how many cases a party may hold: cases added to monitoring directly are not bounded by it. Your plan's own `maxCasesPerReport` can still clamp a report below this number. 25 to 10000 |
sortenum | The default ordering for this party's findings. A findings view can still sort differently; this is what it opens on. score_descfiling_descfiling_ascorder_adverseorder_favourable |
selectionSourceenum or null | Whether the selection is still the category's defaults or you have changed it. Published because it answers "did I change this, or did you?". CATEGORY_DEFAULTSCUSTOMER |
sourceobject or null | What answers this party. A party has no case pipeline of its own. BOTH modes begin with a litigation report, so `reportId` is always set; `entityId` is the watchlist entity that keeps looking afterwards and is null for a one-off. Both are provisioned at add time under their own product's quota and billing, and the ids are those products' own, so you can follow either into its records. |
reportIdstring | The litigation report that assesses them. Always set - both modes begin with one. |
entityIdstring or null | The watchlist entity that keeps looking. Null unless `mode` is MONITOR. |
rerunobject or null | A re-run collecting a replacement set of findings, started after the party was edited. Present only while one is in flight. `reportId` above still points at the report the findings on screen came from, and is swapped for this one the moment the re-run completes - so an edit never empties the page it was made on. |
previousReportIdsarray of string | Reports this party has had before, oldest first, at most ten. Each is kept after it is replaced because its usage event points at it and an invoice line has to resolve; its case rows expire on their own 30-day schedule. |
decisionobject | One decision about a party, stamped with who took it, when, and the score it was taken against. The score is stored on the decision rather than read back later on purpose: a party cleared at 437 stays a party cleared at 437 after it falls to 180, which is what makes "this was cleared when it looked better" a fact on the record instead of an argument. |
verdictenum | `CLEAR` - proceed, nothing here stops it. `CONDITIONS` - proceed, but something has to hold, and `note` carries what. `ESCALATE` - not yours to clear. Three, because these are the only three that change what happens next; "needs more information" is a condition and "rejected" is an escalation that ended. CLEARCONDITIONSESCALATE |
notestring or null | The reason up to 1000 characters |
bystring or null | The user who decided. Null for a decision taken with an API key rather than by a signed-in user. |
atinteger (int64) | When it was taken. |
atScoreinteger or null | The reputation score at the time 0 to 1000 |
atLevelenum or null | The litigation level at the time VERY_HIGHHIGHMODERATELOWMINIMALUNCLASSIFIED |
decisionHistoryarray of object | Every decision that was ever current on this party, oldest first, capped at the last 20. A decision that was reversed is exactly what someone comes looking for later, so changing one adds to this rather than replacing it. |
verdictenum | `CLEAR` - proceed, nothing here stops it. `CONDITIONS` - proceed, but something has to hold, and `note` carries what. `ESCALATE` - not yours to clear. Three, because these are the only three that change what happens next; "needs more information" is a condition and "rejected" is an escalation that ended. CLEARCONDITIONSESCALATE |
notestring or null | The reason up to 1000 characters |
bystring or null | The user who decided. Null for a decision taken with an API key rather than by a signed-in user. |
atinteger (int64) | When it was taken. |
atScoreinteger or null | The reputation score at the time 0 to 1000 |
atLevelenum or null | The litigation level at the time VERY_HIGHHIGHMODERATELOWMINIMALUNCLASSIFIED |
rerunobject | Whether this party is still answering the question it was asked, and what bringing it up to date would cost. Present on `GET /parties/{id}` and on the responses of the edit endpoints; absent from the party a create returns, which by definition is up to date. The findings were produced from the inputs that were given at the time. Edit the name, the identifiers, the addresses, the courts, the years, how many cases or the tier and they were produced from something else - so this compares the party as it stands against the report's own stored inputs and says what moved. **Editing a party never bills.** This is the quote for bringing it up to date. |
pendingboolean | Something the findings were produced from has changed and nothing is running to catch up. False while a re-run is in flight - read `running` for that. |
changedarray of string | Which party fields no longer agree with the report that produced the findings - any of `name`, `nameVariations`, `autoNameVariations`, `identifiers`, `addresses`, `partyType`, `caseStatus`, `fromYear`, `toYear`, `courtTypes`, `maxCases`, `tier`. Two changes are deliberately NOT listed, because they cannot cost you anything: dropping a name variation the report already searched (the findings are then a superset of what you asked for - nothing is missing) and lowering the tier (it asks for less than what is already on screen). Changing a party's categories or its signal selection is not here either: those decide which of a case's signals are the ones you asked about, and are applied on the next read for free. |
noReportboolean | No report is answering this party at all. A re-run is how it gets one. |
needsDiscoveryboolean | A search input moved |
needsIdentityRematchboolean | An identifier, an address or the name moved. These are not search inputs - no court search takes an address - but they are what decides whether a case found by name is actually this company, matched against what its order document says. Every carried case is re-matched against the order evidence already stored on it, which costs nothing and needs no document. |
tierRaisedboolean | BASIC to ADVANCED. The carried cases have no order read to carry |
runningobject or null | The re-run in flight, if there is one. Null otherwise. |
lastFailureobject or null | The last re-run failed - its discovery could not be collected. The change is pending again; start another. |
estimateobject | What a re-run would be charged, in your account's own pricing shape. A re-run IS a litigation report - a discovery search across every court, a court record per case, an order read per case on Advanced, a classification per case - so it is billed as one, under the mode your pack sets, with no separate unit type and no second billing path. Billed once, at completion: a re-run that never finishes is never charged. |
answeringReportIdstring or null | The report the findings on screen actually came from. |
answeredAtinteger (int64) or null | When that report finished. |
createdinteger (int64) | |
createdBystring or null | |
updatedinteger (int64) or null | |
updatedBystring or null |
{
"_id": "CPP0exampledemo0001",
"number": "4821-305917-2604",
"name": "Acme Logistics Private Limited",
"entityType": "BUSINESS",
"entityCategories": [
"vendor",
"borrower.unsecured"
],
"categories": [
{
"id": "vendor",
"name": "Vendor / Supplier",
"partyFamily": "supply.delivery",
"partyFamilyName": "Supply and delivery",
"retired": false
},
{
"id": "borrower.unsecured",
"name": "Institutional Borrower · Unsecured / Cash-Flow",
"partyFamily": "credit.finance",
"partyFamilyName": "Credit and finance",
"retired": false
}
],
"mode": "MONITOR",
"status": "ACTIVE",
"nameVariations": [
"Acme Logistics Pvt Ltd"
],
"autoNameVariations": true,
"identifiers": [
{
"type": "CIN",
"value": "U63090MH2015PTC123456"
},
{
"type": "GSTIN",
"value": "27AABCA1234D1ZV"
}
],
"addresses": [
{
"label": "Registered office",
"line": "14 Marine Lines",
"city": "Mumbai",
"district": null,
"state": "Maharashtra",
"pincode": "400020"
}
],
"registrationNumber": "U63090MH2015PTC123456, 27AABCA1234D1ZV",
"location": "14 Marine Lines, Mumbai, Maharashtra, 400020",
"tag": "VEND-001",
"fatherName": null,
"birthDate": null,
"labels": [
"tier-1"
],
"signals": [
{
"signal": "cheque.s138",
"name": "Section 138 NI Act complaint (cheque dishonour)",
"family": "cheque",
"availability": "LIVE",
"kind": "CLASSIFICATION",
"retired": false
}
],
"declinedSignals": [],
"scope": {
"partyType": "BOTH",
"tier": "BASIC",
"caseStatus": "ALL",
"fromYear": null,
"toYear": null,
"courtTypes": [],
"maxCases": 1000,
"sort": "score_desc"
},
"selectionSource": "CATEGORY_DEFAULTS",
"source": {
"reportId": "CPLR0exampledemo01",
"entityId": "CPE0exampledemo001"
},
"created": 1757000000000,
"createdBy": "CPU0exampledemo0001",
"updated": null,
"updatedBy": null
}List parties
Lists your parties, newest first. $like matches the name, your own reference and the registration number, the three things you would type to find a party you added earlier.
Request URL
https://api.caseprimus.ai/api/caseprimus/v1/parties/searchRequest headers
| Type | Name | Value / description | Optional |
|---|---|---|---|
| String | Content-Type | application/json | Required |
| String | X-CasePrimus-Api-Key | Your API key: {apiKey} | Required |
No API key yet? See Authentication.
Input parameters
| Field | Description |
|---|---|
$limitinteger Optional | 1 to 200 |
$skipinteger Optional | minimum 0 |
$sortenum Optional | createdcreated_descnamename_descupdatedupdated_desc |
$likestring Optional | Matches the name |
statusenum Optional | ACTIVEARCHIVED |
modeenum Optional | `ONE_OFF` is a one-time report and nothing else. `MONITOR` is that same report plus ongoing monitoring - a superset, not a different product. `scope.tier` applies to both: it decides how the party's EXISTING cases are assessed. It does not describe a watched case - monitoring reads every order as it publishes, which is deeper than either tier. ONE_OFFMONITOR |
entityCategoryenum Optional | What a party is to you. Decides which signals apply, so there is no default. `other.custom` is the exception and the escape hatch: it describes no relationship, preselects nothing beyond the always-on eight, and leaves every other signal for you to choose. The last nine describe the OTHER seat - the lender you borrow from, the acquirer buying you, the fund investing in you, the insurer you buy cover from - where the rest describe a party you are exposed to as the receiving side. A party can carry several of these at once and the selection is their union. borrower.equipmentborrower.receivablesborrower.securedborrower.unsecuredcolendercollateral.providerguarantortrade.counterpartyagentchannel.partnerlogisticsservice.providervendoracquisition.targetgroup.companyjoint.venturekey.hireprofessionalpromoterclaimantinsuredinsured.assetprovider.empanelmentprovider.leakagereinsurancesubrogationlandlordtenantgovernmentopposing.partyown.entityother.customlenderdebt.assigneeplatform.fintechprincipal.brandacquirer.parentinvestor.funddivesting.sellerinsurerbroker.intermediary |
entityCategoriesarray of enum Optional | Several categories at once - a party carrying ANY of them, not all. "My vendors and my borrowers" is one list, not the intersection of two, and a company can be both at the same time. Takes precedence over the singular `entityCategory` when both are sent. borrower.equipmentborrower.receivablesborrower.securedborrower.unsecuredcolendercollateral.providerguarantortrade.counterpartyagentchannel.partnerlogisticsservice.providervendoracquisition.targetgroup.companyjoint.venturekey.hireprofessionalpromoterclaimantinsuredinsured.assetprovider.empanelmentprovider.leakagereinsurancesubrogationlandlordtenantgovernmentopposing.partyown.entityother.customlenderdebt.assigneeplatform.fintechprincipal.brandacquirer.parentinvestor.funddivesting.sellerinsurerbroker.intermediary |
entityTypeenum Optional | PERSONBUSINESS |
labelsarray of string Optional | |
addedFrominteger (int64) Optional | Added on or after this time. Epoch milliseconds, because that is how `created` is stored; either end may be sent on its own. |
addedTointeger (int64) Optional | Added on or before this time. |
levelenum Optional | The COMPANY's litigation level, as its opening report assessed it - the same figure `risk.level` carries on every row. A party whose report is still running, or that found no cases, has no level and is not returned by this filter: "we have not finished looking" is not a level. VERY_HIGHHIGHMODERATELOWMINIMAL |
scoreMininteger Optional | The company's reputation score, 0-1000 where HIGHER IS BETTER - `risk.score` on the row. Banded by the litigation level above, so the two filters can narrow one list without contradicting each other. A party with no score yet is outside any range rather than at the bottom of it. 0 to 1000 |
scoreMaxinteger Optional | 0 to 1000 |
Sample request
BASE="https://api.caseprimus.ai/api/caseprimus/v1" curl -X POST "$BASE/parties/search" \ -H "X-CasePrimus-Api-Key: $CASEPRIMUS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "$limit": 25, "status": "ACTIVE", "mode": "MONITOR" }'
const BASE = "https://api.caseprimus.ai/api/caseprimus/v1"; const res = await fetch(BASE + "/parties/search", { method: "POST", headers: { "Content-Type": "application/json", "X-CasePrimus-Api-Key": process.env.CASEPRIMUS_API_KEY, }, body: JSON.stringify({ "$limit": 25, "status": "ACTIVE", "mode": "MONITOR" }), }); const data = await res.json();
import os import requests BASE = "https://api.caseprimus.ai/api/caseprimus/v1" res = requests.request( "POST", BASE + "/parties/search", headers={"X-CasePrimus-Api-Key": os.environ["CASEPRIMUS_API_KEY"]}, json={ "$limit": 25, "status": "ACTIVE", "mode": "MONITOR", }, ) data = res.json()
Responses
| 200 | A page of parties. |
Response fields (HTTP 200)
| Field | Description |
|---|---|
recordsarray of object | |
_idstring | |
numberstring or null | |
namestring | |
entityTypeenum | PERSONBUSINESS |
riskobject or null | The company's reputation score and litigation level, from the report that answered this party - a party has no score of its own. Sent on the LIST so a page of parties can be ranked and read without fetching a report per row; null while the report is still running, and on one that found no cases. |
pendingReviewinteger | How many findings on this party are waiting for your decision - the same set `GET /parties/{partyId}/findings?tab=pending` returns, counted here so a page of parties can show where the work is without a request per row. Sent on the LIST. Zero means nothing is waiting, and a `ONE_OFF` party is always zero: it assesses once and discovers nothing after. |
monitoredCasesinteger | How many cases are being followed for this party - the same set `GET /parties/{partyId}/findings?tab=monitored` returns. Sent on the LIST. A case we are still checking the identifiers of counts here: it is being followed either way. |
casesFoundinteger or null | How many cases the opening report found. Sent on the LIST, read off the report's stored summary. Null - not zero - while that report is still running, because "we found none" and "we have not finished looking" are opposite answers. |
entityCategoriesarray of enum | What this party is to you, and it can be more than one thing. Decides which signals apply, so there is no default - read GET /parties/catalog for the list. borrower.equipmentborrower.receivablesborrower.securedborrower.unsecuredcolendercollateral.providerguarantortrade.counterpartyagentchannel.partnerlogisticsservice.providervendoracquisition.targetgroup.companyjoint.venturekey.hireprofessionalpromoterclaimantinsuredinsured.assetprovider.empanelmentprovider.leakagereinsurancesubrogationlandlordtenantgovernmentopposing.partyown.entityother.customlenderdebt.assigneeplatform.fintechprincipal.brandacquirer.parentinvestor.funddivesting.sellerinsurerbroker.intermediary |
categoriesarray of object | The same list with the names and families a screen renders, so a reader need not carry the catalogue. `retired` marks an id the catalogue no longer knows - reported rather than dropped. |
modeenum | `MONITOR` keeps looking as the courts publish, which is what the watchlist did. `ONE_OFF` assesses once, which is what a litigation report did. A party moves between them without being re-added - a one-off assessment that comes back badly is exactly the party you then want watched. ONE_OFFMONITOR |
statusenum | ACTIVEARCHIVED |
nameVariationsarray of string | Other spellings of the same company |
autoNameVariationsboolean | Whether you asked us to derive further spellings as well. |
identifiersarray of object | Always the typed shape here, whichever of the two accepted shapes you sent. `type` is null for an identifier sent as a bare string - we never guess it. |
addressesarray of object | Up to three. An address with every field empty is dropped rather than stored, so a count of these means what it says. |
registrationNumberstring or null | The watchlist entity's older free-text spelling of `identifiers` up to 100 characters |
locationstring or null | The older free-text spelling of `addresses` |
tagstring or null | Your own reference for this party. Unique among your active parties; archiving frees it. |
fatherNamestring or null | PERSON only. Identifying metadata |
birthDatestring or null | |
labelsarray of string | |
signalsarray of object | |
declinedSignalsarray of string | What you switched off. Remembered rather than merely absent, so a later change to the category's defaults can never switch one back on - a signal declined on purpose is a decision. |
scopeobject | WHERE TO LOOK. The same inputs a litigation report takes, asked once for the whole party. Which side of a case to look on is here rather than on each signal: it is the same question asked once instead of 133 times, and it is the control a customer already recognises. |
selectionSourceenum or null | Whether the selection is still the category's defaults or you have changed it. Published because it answers "did I change this, or did you?". CATEGORY_DEFAULTSCUSTOMER |
sourceobject or null | What answers this party. A party has no case pipeline of its own. BOTH modes begin with a litigation report, so `reportId` is always set; `entityId` is the watchlist entity that keeps looking afterwards and is null for a one-off. Both are provisioned at add time under their own product's quota and billing, and the ids are those products' own, so you can follow either into its records. |
decisionobject | One decision about a party, stamped with who took it, when, and the score it was taken against. The score is stored on the decision rather than read back later on purpose: a party cleared at 437 stays a party cleared at 437 after it falls to 180, which is what makes "this was cleared when it looked better" a fact on the record instead of an argument. |
decisionHistoryarray of object | Every decision that was ever current on this party, oldest first, capped at the last 20. A decision that was reversed is exactly what someone comes looking for later, so changing one adds to this rather than replacing it. |
rerunobject | Whether this party is still answering the question it was asked, and what bringing it up to date would cost. Present on `GET /parties/{id}` and on the responses of the edit endpoints; absent from the party a create returns, which by definition is up to date. The findings were produced from the inputs that were given at the time. Edit the name, the identifiers, the addresses, the courts, the years, how many cases or the tier and they were produced from something else - so this compares the party as it stands against the report's own stored inputs and says what moved. **Editing a party never bills.** This is the quote for bringing it up to date. |
createdinteger (int64) | |
createdBystring or null | |
updatedinteger (int64) or null | |
updatedBystring or null | |
totalinteger | |
limitinteger | |
skipinteger |
{
"records": [
{
"_id": "CPP0exampledemo0001",
"name": "Acme Logistics Private Limited",
"entityType": "BUSINESS",
"entityCategories": [
"vendor"
],
"mode": "MONITOR",
"status": "ACTIVE",
"labels": [
"tier-1"
],
"declinedSignals": [],
"selectionSource": "CATEGORY_DEFAULTS",
"risk": {
"score": 437,
"scale": 1000,
"level": "MODERATE"
},
"casesFound": 1000,
"monitoredCases": 4,
"pendingReview": 1,
"created": 1757000000000
}
],
"total": 1,
"limit": 25,
"skip": 0
}{
"records": [
{
"_id": "CPP0exampledemo0001",
"name": "Acme Logistics Private Limited",
"entityType": "BUSINESS",
"entityCategories": [
"vendor"
],
"mode": "MONITOR",
"status": "ACTIVE",
"labels": [
"tier-1"
],
"declinedSignals": [],
"selectionSource": "CATEGORY_DEFAULTS",
"risk": {
"score": 437,
"scale": 1000,
"level": "MODERATE"
},
"casesFound": 1000,
"monitoredCases": 4,
"pendingReview": 1,
"created": 1757000000000
}
],
"total": 1,
"limit": 25,
"skip": 0
}Read a party
Returns one party with its full signal selection, including what it is to you and whether it is watched once or continuously.
rerun says whether the party's findings are still up to date. rerun.pending is true when something they were produced from has been edited since, rerun.changed names what, and rerun.estimate is what bringing them up to date would cost. Editing a party never charges you.
Request URL
https://api.caseprimus.ai/api/caseprimus/v1/parties/{id}Request headers
| Type | Name | Value / description | Optional |
|---|---|---|---|
| String | X-CasePrimus-Api-Key | Your API key: {apiKey} | Required |
No API key yet? See Authentication.
Path parameters
| Name | In | Required | Description |
|---|---|---|---|
id | path | Required | The id returned when the resource was created. |
Sample request
BASE="https://api.caseprimus.ai/api/caseprimus/v1" curl "$BASE/parties/PARTY_ID" \ -H "X-CasePrimus-Api-Key: $CASEPRIMUS_API_KEY"
const BASE = "https://api.caseprimus.ai/api/caseprimus/v1"; const res = await fetch(BASE + "/parties/PARTY_ID", { method: "GET", headers: { "X-CasePrimus-Api-Key": process.env.CASEPRIMUS_API_KEY, }, }); const data = await res.json();
import os import requests BASE = "https://api.caseprimus.ai/api/caseprimus/v1" res = requests.request( "GET", BASE + "/parties/PARTY_ID", headers={"X-CasePrimus-Api-Key": os.environ["CASEPRIMUS_API_KEY"]}, ) data = res.json()
Responses
| 200 | The party. |
| 400 | No such party (61482), or the id is malformed (60001). |
Response fields (HTTP 200)
| Field | Description |
|---|---|
_idstring | |
numberstring or null | |
namestring | |
entityTypeenum | PERSONBUSINESS |
riskobject or null | The company's reputation score and litigation level, from the report that answered this party - a party has no score of its own. Sent on the LIST so a page of parties can be ranked and read without fetching a report per row; null while the report is still running, and on one that found no cases. |
scoreinteger or null | 0-1000, higher is better. |
scaleinteger | |
levelenum or null | VERY_HIGHHIGHMODERATELOWMINIMAL |
pendingReviewinteger | How many findings on this party are waiting for your decision - the same set `GET /parties/{partyId}/findings?tab=pending` returns, counted here so a page of parties can show where the work is without a request per row. Sent on the LIST. Zero means nothing is waiting, and a `ONE_OFF` party is always zero: it assesses once and discovers nothing after. |
monitoredCasesinteger | How many cases are being followed for this party - the same set `GET /parties/{partyId}/findings?tab=monitored` returns. Sent on the LIST. A case we are still checking the identifiers of counts here: it is being followed either way. |
casesFoundinteger or null | How many cases the opening report found. Sent on the LIST, read off the report's stored summary. Null - not zero - while that report is still running, because "we found none" and "we have not finished looking" are opposite answers. |
entityCategoriesarray of enum | What this party is to you, and it can be more than one thing. Decides which signals apply, so there is no default - read GET /parties/catalog for the list. borrower.equipmentborrower.receivablesborrower.securedborrower.unsecuredcolendercollateral.providerguarantortrade.counterpartyagentchannel.partnerlogisticsservice.providervendoracquisition.targetgroup.companyjoint.venturekey.hireprofessionalpromoterclaimantinsuredinsured.assetprovider.empanelmentprovider.leakagereinsurancesubrogationlandlordtenantgovernmentopposing.partyown.entityother.customlenderdebt.assigneeplatform.fintechprincipal.brandacquirer.parentinvestor.funddivesting.sellerinsurerbroker.intermediary |
categoriesarray of object | The same list with the names and families a screen renders, so a reader need not carry the catalogue. `retired` marks an id the catalogue no longer knows - reported rather than dropped. |
idstring | |
namestring or null | |
partyFamilystring or null | |
partyFamilyNamestring or null | |
retiredboolean | |
modeenum | `MONITOR` keeps looking as the courts publish, which is what the watchlist did. `ONE_OFF` assesses once, which is what a litigation report did. A party moves between them without being re-added - a one-off assessment that comes back badly is exactly the party you then want watched. ONE_OFFMONITOR |
statusenum | ACTIVEARCHIVED |
nameVariationsarray of string | Other spellings of the same company |
autoNameVariationsboolean | Whether you asked us to derive further spellings as well. |
identifiersarray of object | Always the typed shape here, whichever of the two accepted shapes you sent. `type` is null for an identifier sent as a bare string - we never guess it. |
typeenum or null | CINPANGSTINUDYAMOTHERnull |
valuestring | |
addressesarray of object | Up to three. An address with every field empty is dropped rather than stored, so a count of these means what it says. |
labelstring or null | |
linestring or null | |
citystring or null | |
districtstring or null | |
statestring or null | |
pincodestring or null | |
registrationNumberstring or null | The watchlist entity's older free-text spelling of `identifiers` up to 100 characters |
locationstring or null | The older free-text spelling of `addresses` |
tagstring or null | Your own reference for this party. Unique among your active parties; archiving frees it. |
fatherNamestring or null | PERSON only. Identifying metadata |
birthDatestring or null | |
labelsarray of string | |
signalsarray of object | |
signalstring | |
namestring or null | |
familystring or null | |
availabilityenum or null | LIVEPARTIALNOT_AVAILABLE |
kindenum or null | CLASSIFICATIONDERIVED |
retiredboolean | A signal stored on this party that the catalogue no longer knows. Reported rather than dropped, so the party never looks narrower than it is. |
declinedSignalsarray of string | What you switched off. Remembered rather than merely absent, so a later change to the category's defaults can never switch one back on - a signal declined on purpose is a decision. |
scopeobject | WHERE TO LOOK. The same inputs a litigation report takes, asked once for the whole party. Which side of a case to look on is here rather than on each signal: it is the same question asked once instead of 133 times, and it is the control a customer already recognises. |
partyTypeenum | Which side of a case to look for this party on. Defaults to BOTH - narrowing to one side silently hides half the cases. PETITIONERRESPONDENTBOTH |
tierenum | BASIC reads the court record. ADVANCED also reads the order documents, which is what lets a signal be classified from what a judge wrote rather than only from the index entry. Defaults to BASIC, so nobody is moved onto the paid tier by omission. BASICADVANCED |
caseStatusenum | ALLPENDINGDISPOSED |
fromYearinteger or null | |
toYearinteger or null | |
courtTypesarray of enum | Which courts to go looking in. Empty means every court. OTHER covers tribunals, consumer commissions and anything unplaceable. SCHCDCOTHER |
maxCasesinteger | How many cases the one-off HISTORICAL search covers, newest first. Raised to 10,000 on. This is not a limit on how many cases a party may hold: cases added to monitoring directly are not bounded by it. Your plan's own `maxCasesPerReport` can still clamp a report below this number. 25 to 10000 |
sortenum | The default ordering for this party's findings. A findings view can still sort differently; this is what it opens on. score_descfiling_descfiling_ascorder_adverseorder_favourable |
selectionSourceenum or null | Whether the selection is still the category's defaults or you have changed it. Published because it answers "did I change this, or did you?". CATEGORY_DEFAULTSCUSTOMER |
sourceobject or null | What answers this party. A party has no case pipeline of its own. BOTH modes begin with a litigation report, so `reportId` is always set; `entityId` is the watchlist entity that keeps looking afterwards and is null for a one-off. Both are provisioned at add time under their own product's quota and billing, and the ids are those products' own, so you can follow either into its records. |
reportIdstring | The litigation report that assesses them. Always set - both modes begin with one. |
entityIdstring or null | The watchlist entity that keeps looking. Null unless `mode` is MONITOR. |
rerunobject or null | A re-run collecting a replacement set of findings, started after the party was edited. Present only while one is in flight. `reportId` above still points at the report the findings on screen came from, and is swapped for this one the moment the re-run completes - so an edit never empties the page it was made on. |
previousReportIdsarray of string | Reports this party has had before, oldest first, at most ten. Each is kept after it is replaced because its usage event points at it and an invoice line has to resolve; its case rows expire on their own 30-day schedule. |
decisionobject | One decision about a party, stamped with who took it, when, and the score it was taken against. The score is stored on the decision rather than read back later on purpose: a party cleared at 437 stays a party cleared at 437 after it falls to 180, which is what makes "this was cleared when it looked better" a fact on the record instead of an argument. |
verdictenum | `CLEAR` - proceed, nothing here stops it. `CONDITIONS` - proceed, but something has to hold, and `note` carries what. `ESCALATE` - not yours to clear. Three, because these are the only three that change what happens next; "needs more information" is a condition and "rejected" is an escalation that ended. CLEARCONDITIONSESCALATE |
notestring or null | The reason up to 1000 characters |
bystring or null | The user who decided. Null for a decision taken with an API key rather than by a signed-in user. |
atinteger (int64) | When it was taken. |
atScoreinteger or null | The reputation score at the time 0 to 1000 |
atLevelenum or null | The litigation level at the time VERY_HIGHHIGHMODERATELOWMINIMALUNCLASSIFIED |
decisionHistoryarray of object | Every decision that was ever current on this party, oldest first, capped at the last 20. A decision that was reversed is exactly what someone comes looking for later, so changing one adds to this rather than replacing it. |
verdictenum | `CLEAR` - proceed, nothing here stops it. `CONDITIONS` - proceed, but something has to hold, and `note` carries what. `ESCALATE` - not yours to clear. Three, because these are the only three that change what happens next; "needs more information" is a condition and "rejected" is an escalation that ended. CLEARCONDITIONSESCALATE |
notestring or null | The reason up to 1000 characters |
bystring or null | The user who decided. Null for a decision taken with an API key rather than by a signed-in user. |
atinteger (int64) | When it was taken. |
atScoreinteger or null | The reputation score at the time 0 to 1000 |
atLevelenum or null | The litigation level at the time VERY_HIGHHIGHMODERATELOWMINIMALUNCLASSIFIED |
rerunobject | Whether this party is still answering the question it was asked, and what bringing it up to date would cost. Present on `GET /parties/{id}` and on the responses of the edit endpoints; absent from the party a create returns, which by definition is up to date. The findings were produced from the inputs that were given at the time. Edit the name, the identifiers, the addresses, the courts, the years, how many cases or the tier and they were produced from something else - so this compares the party as it stands against the report's own stored inputs and says what moved. **Editing a party never bills.** This is the quote for bringing it up to date. |
pendingboolean | Something the findings were produced from has changed and nothing is running to catch up. False while a re-run is in flight - read `running` for that. |
changedarray of string | Which party fields no longer agree with the report that produced the findings - any of `name`, `nameVariations`, `autoNameVariations`, `identifiers`, `addresses`, `partyType`, `caseStatus`, `fromYear`, `toYear`, `courtTypes`, `maxCases`, `tier`. Two changes are deliberately NOT listed, because they cannot cost you anything: dropping a name variation the report already searched (the findings are then a superset of what you asked for - nothing is missing) and lowering the tier (it asks for less than what is already on screen). Changing a party's categories or its signal selection is not here either: those decide which of a case's signals are the ones you asked about, and are applied on the next read for free. |
noReportboolean | No report is answering this party at all. A re-run is how it gets one. |
needsDiscoveryboolean | A search input moved |
needsIdentityRematchboolean | An identifier, an address or the name moved. These are not search inputs - no court search takes an address - but they are what decides whether a case found by name is actually this company, matched against what its order document says. Every carried case is re-matched against the order evidence already stored on it, which costs nothing and needs no document. |
tierRaisedboolean | BASIC to ADVANCED. The carried cases have no order read to carry |
runningobject or null | The re-run in flight, if there is one. Null otherwise. |
lastFailureobject or null | The last re-run failed - its discovery could not be collected. The change is pending again; start another. |
estimateobject | What a re-run would be charged, in your account's own pricing shape. A re-run IS a litigation report - a discovery search across every court, a court record per case, an order read per case on Advanced, a classification per case - so it is billed as one, under the mode your pack sets, with no separate unit type and no second billing path. Billed once, at completion: a re-run that never finishes is never charged. |
answeringReportIdstring or null | The report the findings on screen actually came from. |
answeredAtinteger (int64) or null | When that report finished. |
createdinteger (int64) | |
createdBystring or null | |
updatedinteger (int64) or null | |
updatedBystring or null |
{
"_id": "CPP0exampledemo0001",
"name": "Acme Logistics Private Limited",
"entityType": "BUSINESS",
"entityCategories": [
"vendor"
],
"mode": "MONITOR",
"status": "ACTIVE",
"labels": [
"tier-1"
],
"declinedSignals": [],
"selectionSource": "CATEGORY_DEFAULTS",
"rerun": {
"pending": false,
"changed": [],
"noReport": false,
"needsDiscovery": false,
"needsIdentityRematch": false,
"tierRaised": false,
"running": null,
"lastFailure": null,
"estimate": {
"pricingMode": "PER_PAGE",
"unitType": "LITIGATION_REPORT_BASIC_PAGE",
"tier": "BASIC",
"caseCap": 1000,
"minUnits": 1,
"maxUnits": 10,
"casesPerUnit": 100
},
"answeringReportId": "CPLR0exampledemo0001",
"answeredAt": 1757005000000
},
"created": 1757000000000
}Get the review queue
Lists every case waiting for your decision, across every party you watch. Accept one with POST /parties/{id}/findings/{candidateId}/promote and it starts being monitored. Decline it with .../decline and it stays on the party's record as declined. Both need the partyId and candidateId that each row carries.
A case reaches the queue once CasePrimus has checked it against the court's own record, or when it came from a one-time historical search, which is yours to decide on. The queue is ordered worst first, then longest waiting, so you can read it from the top. A case that is already monitored never appears here.
Request URL
https://api.caseprimus.ai/api/caseprimus/v1/parties/review-queueRequest headers
| Type | Name | Value / description | Optional |
|---|---|---|---|
| String | X-CasePrimus-Api-Key | Your API key: {apiKey} | Required |
No API key yet? See Authentication.
Path and query parameters
| Name | In | Required | Description |
|---|---|---|---|
$limit | query | Optional | |
$skip | query | Optional | |
partyId | query | Optional | One party's share of the queue. byParty on the response says which parties have anything waiting. |
level | query | Optional |
Sample request
BASE="https://api.caseprimus.ai/api/caseprimus/v1" curl "$BASE/parties/review-queue" \ -H "X-CasePrimus-Api-Key: $CASEPRIMUS_API_KEY"
const BASE = "https://api.caseprimus.ai/api/caseprimus/v1"; const res = await fetch(BASE + "/parties/review-queue", { method: "GET", headers: { "X-CasePrimus-Api-Key": process.env.CASEPRIMUS_API_KEY, }, }); const data = await res.json();
import os import requests BASE = "https://api.caseprimus.ai/api/caseprimus/v1" res = requests.request( "GET", BASE + "/parties/review-queue", headers={"X-CasePrimus-Api-Key": os.environ["CASEPRIMUS_API_KEY"]}, ) data = res.json()
Responses
| 200 | The cases waiting for a decision. |
| 401 | Not signed in. |
Response fields (HTTP 200)
| Field | Description |
|---|---|
recordsarray of object | |
totalinteger | |
byPartyarray of object | How much is waiting per party, biggest first - enough to build a filter that only ever offers a party with something in it. |
partyIdstring | |
namestring or null | |
countinteger | |
oldestAtinteger or null | When the longest-waiting of them was queued. A count on its own cannot be ranked against anything - four cases queued this morning and four queued a fortnight ago are not the same item. |
limitinteger | |
skipinteger |
{
"records": [
{
"key": "DC:MHCC010054082020",
"candidateId": "CPWLCC0-71ab49",
"partyId": "CPP0exampledemo0001",
"partyName": "Acme Logistics Private Limited",
"queuedAt": 1794300000000,
"discoveryMode": "ONGOING",
"cnr": "MHCC010054082020",
"caseNumber": "CC/2241/2024",
"courtType": "DC",
"court": "District Court, Mumbai City",
"caseType": "Cheque Dishonour",
"caseStatus": "Pending",
"filingDate": "2024-03-14",
"risk": {
"level": "HIGH",
"score": 70,
"caseScore": {
"value": 260,
"scale": 1000,
"higherIsBetter": true,
"band": "HIGH"
},
"outcome": null,
"category": "CHEQUE_DISHONOUR",
"reasons": []
}
}
],
"total": 1,
"byParty": [
{
"partyId": "CPP0exampledemo0001",
"name": "Acme Logistics Private Limited",
"count": 1,
"oldestAt": 1794300000000
}
],
"limit": 50,
"skip": 0
}List the cases found for a party
Lists every case found for a party, with each case's risk level, the signals it answers and where it stands for this party.
findingState is REPORT_ONLY, NOT_REVIEWED (waiting for you to accept or decline it), WATCHED or DECLINED. depth says how much was read for the case: RECORD (the court record, including its acts and sections), ORDER_LATEST (also the most recent order) or ORDER_ALL (every order, for a monitored case).
counts tallies the whole set rather than the page, so you can show how many cases a filter would leave before anyone applies it.
Request URL
https://api.caseprimus.ai/api/caseprimus/v1/parties/{id}/findingsRequest headers
| Type | Name | Value / description | Optional |
|---|---|---|---|
| String | X-CasePrimus-Api-Key | Your API key: {apiKey} | Required |
No API key yet? See Authentication.
Path and query parameters
| Name | In | Required | Description |
|---|---|---|---|
id | path | Required | The id returned when the resource was created. |
$limit | query | Optional | Up to 500. A page of a list wants 25; a view that groups the whole record - by signal, say - should ask for the largest page it can, because every call rebuilds the party's whole record before slicing a page out of it. |
$skip | query | Optional | |
$sort | query | Optional | |
$like | query | Optional | Matches the case number, the court and the case type. It does NOT search party names - for that use opponent or alongside, which match on one side of the case. |
caseRef | query | Optional | Fetch ONE case by the ref a link carries, rather than searching for it. Matched against both refs a finding can hold - caseRef (the monitored case) and reportCaseRef (the report's row) - because a case that is both carries both and a link holds whichever its source had. Use it wherever you already know which case you mean: a sum in summary.orders.amounts.items[].caseRef, a row in the changes feed. Returns at most one record.
|
tab | query | Optional | The screen's own three lists. historical is two states at once (report-only and declined), which state cannot express. |
state | query | Optional | |
signal | query | Optional | A signal id from GET /parties/catalog. |
level | query | Optional | |
courtType | query | Optional | |
caseState | query | Optional | The state the court sits in, as the record spells it - one of the keys summary.byState[].key returns. NOT the same as state above, which is where the case stands for this party (watched, declined, never reviewed); the two are named apart because a geographic name sent as state is simply rejected.
|
caseStatus | query | Optional | |
filedFrom | query | Optional | Cases FILED on or after this date, as the court's own record states the filing date. ISO YYYY-MM-DD: every court's spelling of a date is normalised to it before the comparison, which is why a range can be trusted across courts that write "15-10-2026" and "2026-10-15" for the same day.
A case whose record states no filing date at all is OUT of the range rather than quietly inside it - it cannot be placed in one, and including it would widen every answer this filter gives. Either end may be sent on its own.
|
filedTo | query | Optional | Cases filed on or before this date. See filedFrom. |
scoreMin | query | Optional | The CASE score, risk.caseScore.value - 0-1000 where HIGHER IS BETTER, banded by the case's own risk level so a score filter and a level filter can never contradict each other.
Not risk.score, which is the rubric's 0-100 running the other way and is null on a monitored case. A case with no score at all is outside any range given here rather than at the bottom of it.
THE BAND IS THE CLAIM, the position inside it is the ranking. A monitored case is scored here from the assessment its report stored, and on its own page from the live court record read since - so the same case can sit a few points apart on the two screens while always being in the same band, because the band is fixed by a level both of them take from the same place.
|
scoreMax | query | Optional | See scoreMin. |
opponent | query | Optional | A normalised party name from counts.parties.opposing[].key, matched against the OPPOSING side only - the petitioners when this party is the respondent, and the respondents when it brought the case. So this answers "what has this name brought against us", not "where does this name appear".
|
alongside | query | Optional | The same, for this party's OWN side - a co-party. The two are never the same set for one name: a bank named beside this party in an insolvency is a co-respondent, not an adversary. |
Sample request
BASE="https://api.caseprimus.ai/api/caseprimus/v1" curl "$BASE/parties/PARTY_ID/findings" \ -H "X-CasePrimus-Api-Key: $CASEPRIMUS_API_KEY"
const BASE = "https://api.caseprimus.ai/api/caseprimus/v1"; const res = await fetch(BASE + "/parties/PARTY_ID/findings", { method: "GET", headers: { "X-CasePrimus-Api-Key": process.env.CASEPRIMUS_API_KEY, }, }); const data = await res.json();
import os import requests BASE = "https://api.caseprimus.ai/api/caseprimus/v1" res = requests.request( "GET", BASE + "/parties/PARTY_ID/findings", headers={"X-CasePrimus-Api-Key": os.environ["CASEPRIMUS_API_KEY"]}, ) data = res.json()
Responses
| 200 | The party's cases, with the counts of the whole set. |
| 400 | No such party (61482) or malformed input (60001). |
Response fields (HTTP 200)
| Field | Description |
|---|---|
recordsarray of object | |
totalinteger | |
countsobject (free-form) |
{
"readiness": {
"searching": false,
"status": "COMPLETE",
"discovered": 22,
"fetched": 22,
"finishedAt": 1762000000000,
"rerun": null
},
"records": [
{
"key": "HC:HBHC010234872025",
"cnr": "HBHC010234872025",
"courtType": "HC",
"court": "High Court of Punjab and Haryana",
"caseNumber": "CRM-M-12345-2025",
"caseType": "Criminal Misc.",
"caseStatus": "Pending",
"acts": [],
"risk": {
"level": "HIGH",
"score": 70,
"caseScore": {
"value": 260,
"scale": 1000,
"higherIsBetter": true,
"band": "HIGH"
},
"outcome": "ADVERSE",
"category": "INSOLVENCY_RECOVERY",
"reasons": []
},
"signals": [
"cheque.s138"
],
"signalNames": [
{
"id": "cheque.s138",
"name": "Section 138 NI Act complaint (cheque dishonour)"
}
],
"signalsNotWatched": [],
"signalBasis": "RECORD",
"signalConfidence": "MEDIUM",
"depth": "RECORD",
"assessed": true,
"courtRecord": {
"caseHistory": [
{
"businessDate": "26-04-2024",
"purpose": "APPEARANCE",
"judge": "PRL. CIVIL JUDGE And JMFC"
}
],
"objections": []
},
"findingState": "NOT_REVIEWED",
"from": "REPORT"
}
],
"total": 22,
"counts": {
"byState": {
"NOT_REVIEWED": 20,
"WATCHED": 2
},
"byLevel": {
"LOW": 12,
"MODERATE": 6,
"MINIMAL": 3,
"HIGH": 1
},
"byDepth": {
"RECORD": 20,
"ORDER_ALL": 2
},
"bySignal": {
"cheque.s138": 9
},
"byCourtType": {
"HC": 14,
"DC": 8
},
"byCaseState": {
"Punjab": 11,
"Haryana": 7,
"Delhi": 4
},
"byCaseStatus": {
"PENDING": 19,
"DISPOSED": 3
},
"notWatched": 0,
"awaitingBackOffice": 0,
"byFilingYear": [
{
"year": 2024,
"cases": 6,
"against": 1
},
{
"year": 2025,
"cases": 9,
"against": 3
},
{
"year": 2026,
"cases": 7,
"against": 4
}
],
"byFilingMonth": [
{
"month": "2026-09",
"cases": 3,
"against": 1
},
{
"month": "2026-10",
"cases": 5,
"against": 2
},
{
"month": "2026-11",
"cases": 2,
"against": 1
}
],
"againstPending": 5,
"signals": {
"unclassified": {
"noSignalFits": 1,
"evidenceSilent": 3
},
"watched": [
{
"id": "cheque.s138",
"name": "Section 138 NI Act complaint (cheque dishonour)",
"cases": 9,
"level": "HIGH",
"byLevel": {
"HIGH": 2,
"MODERATE": 7
},
"amount": null,
"summary": "All nine Section 138 complaints are pending and in eight of them this company is the complainant, pursuing borrowers whose cheques were dishonoured. That is a lender collecting its own receivables rather than evidence that its own cheques are bouncing.",
"points": [
{
"check": "Ask the company to confirm whether any cheque it has issued in this relationship has been dishonoured, and ask for the status of the one matter where it is the accused.",
"engagement": "Company's own cheques and payments",
"basis": [
"CRM-M-12345-2025"
],
"casesUnderSignal": 9,
"basisNote": "The only case of this kind brought against this party - it filed the other 8 itself."
}
],
"analysisPending": false
},
{
"id": "labour.contract",
"name": "Contract-labour and principal-employer claims",
"cases": 0,
"level": null,
"byLevel": {},
"amount": null,
"summary": "Nothing was found under Contract-labour and principal-employer claims. We looked across every court we cover and this company has no case of this kind.",
"points": [],
"analysisPending": false
}
],
"found": [
{
"id": "tax.income",
"name": "Income-tax appeals and assessments",
"cases": 2,
"level": "HIGH",
"byLevel": {
"HIGH": 2
},
"amount": null,
"summary": "Two pending income-tax appeals, both brought against the company by the Principal Commissioner.",
"points": [],
"analysisPending": false
}
]
},
"parties": {
"opposing": [
{
"key": "PR COMMISSIONER OF INCOME TAX 3 PUNE",
"name": "Pr Commissioner of Income Tax 3 Pune",
"cases": 2,
"broughtAgainstThem": 2,
"level": "HIGH"
},
{
"key": "VIDYA ENTERPRISES",
"name": "Vidya Enterprises",
"cases": 2,
"broughtAgainstThem": 0,
"level": "MODERATE"
}
],
"alongside": [
{
"key": "HDFC BANK",
"name": "Hdfc Bank",
"cases": 15,
"broughtAgainstThem": 0,
"level": "VERY_HIGH"
}
],
"repeatOpponents": 2,
"repeatAlongside": 1,
"shown": 200,
"distinctOpponents": 19,
"unsided": 0
}
}
}{
"records": [
{
"key": "HC:HBHC010234872025",
"cnr": "HBHC010234872025",
"courtType": "HC",
"court": "High Court of Punjab and Haryana",
"caseNumber": "CRM-M-12345-2025",
"caseType": "Criminal Misc.",
"caseStatus": "Pending",
"partySide": "RESPONDENT",
"risk": {
"level": "HIGH",
"score": 70,
"caseScore": {
"value": 260,
"scale": 1000,
"higherIsBetter": true,
"band": "HIGH"
},
"outcome": "ADVERSE",
"category": "INSOLVENCY_RECOVERY",
"reasons": []
},
"signals": [
"tax.income"
],
"findingState": "REPORT_ONLY",
"from": "REPORT"
}
],
"total": 2,
"counts": {
"byState": {
"REPORT_ONLY": 2
},
"byLevel": {
"HIGH": 2
},
"byDepth": {
"RECORD": 2
},
"bySignal": {
"tax.income": 2
},
"byCourtType": {
"ITAT": 2
},
"byCaseState": {
"Maharashtra": 2
},
"byCaseStatus": {
"PENDING": 2
},
"notWatched": 0,
"byFilingYear": [
{
"year": 2025,
"cases": 2,
"against": 2
}
],
"byFilingMonth": [
{
"month": "2025-06",
"cases": 2,
"against": 2
}
],
"againstPending": 2
}
}{
"records": [
{
"key": "DC:MHPU010123452026",
"cnr": "MHPU010123452026",
"courtType": "DC",
"court": "District and Sessions Court, Pune",
"caseNumber": "CC/99/2026",
"caseType": "Criminal Case",
"caseStatus": "Pending",
"partySide": "RESPONDENT",
"reportCaseRef": "cr_1911c7e34dfe5026",
"risk": {
"level": "MODERATE",
"score": 48,
"caseScore": {
"value": 503,
"scale": 1000,
"higherIsBetter": true,
"band": "MODERATE"
},
"outcome": null,
"category": "CHEQUE_DISHONOUR",
"reasons": []
},
"signals": [
"financial.cheque"
],
"findingState": "REPORT_ONLY",
"from": "REPORT"
}
],
"total": 1,
"counts": {
"byState": {
"REPORT_ONLY": 1
},
"byLevel": {
"MODERATE": 1
},
"byDepth": {
"ORDER": 1
},
"bySignal": {
"financial.cheque": 1
},
"byCourtType": {
"DC": 1
},
"byCaseState": {
"Maharashtra": 1
},
"byCaseStatus": {
"PENDING": 1
},
"notWatched": 0,
"byFilingYear": [
{
"year": 2026,
"cases": 1,
"against": 1
}
],
"byFilingMonth": [
{
"month": "2026-03",
"cases": 1,
"against": 1
}
],
"againstPending": 1
}
}Accept a case found for a party
Accepts a case found for this party, so that it is monitored from now on. Accepting spends one of your monitored-case slots.
A case that the court already shows as disposed is added only when you send confirmDisposed: true. Otherwise the call fails with code 60430 and nothing is added. A party that is a one-time assessment has nothing to accept and is refused with code 61490.
Request URL
https://api.caseprimus.ai/api/caseprimus/v1/parties/{id}/findings/{candidateId}/promoteRequest headers
| Type | Name | Value / description | Optional |
|---|---|---|---|
| String | X-CasePrimus-Api-Key | Your API key: {apiKey} | Required |
No API key yet? See Authentication.
Path parameters
| Name | In | Required | Description |
|---|---|---|---|
id | path | Required | The id returned when the resource was created. |
candidateId | path | Required | The id returned when the resource was created. |
Sample request
BASE="https://api.caseprimus.ai/api/caseprimus/v1" curl -X POST "$BASE/parties/PARTY_ID/findings/FINDING_ID/promote" \ -H "X-CasePrimus-Api-Key: $CASEPRIMUS_API_KEY"
const BASE = "https://api.caseprimus.ai/api/caseprimus/v1"; const res = await fetch(BASE + "/parties/PARTY_ID/findings/FINDING_ID/promote", { method: "POST", headers: { "X-CasePrimus-Api-Key": process.env.CASEPRIMUS_API_KEY, }, }); const data = await res.json();
import os import requests BASE = "https://api.caseprimus.ai/api/caseprimus/v1" res = requests.request( "POST", BASE + "/parties/PARTY_ID/findings/FINDING_ID/promote", headers={"X-CasePrimus-Api-Key": os.environ["CASEPRIMUS_API_KEY"]}, ) data = res.json()
Responses
| 200 | The case that is now monitored. |
| 400 | No such party (61482), not monitored (61490), no such candidate (60408), or the case is disposed (60430). |
{
"caseId": "CPWLC0exampledemo0001",
"status": "ACTIVE",
"backOfficeReviewReason": null,
"linkedExisting": false
}Decline a case found for a party
Records that a found case is not this party's, or is not worth monitoring. The case is not deleted. It stays on the party with findingState set to DECLINED, and you can accept it later. Declining does not use a monitored-case slot.
Request URL
https://api.caseprimus.ai/api/caseprimus/v1/parties/{id}/findings/{candidateId}/declineRequest headers
| Type | Name | Value / description | Optional |
|---|---|---|---|
| String | X-CasePrimus-Api-Key | Your API key: {apiKey} | Required |
No API key yet? See Authentication.
Path parameters
| Name | In | Required | Description |
|---|---|---|---|
id | path | Required | The id returned when the resource was created. |
candidateId | path | Required | The id returned when the resource was created. |
Sample request
BASE="https://api.caseprimus.ai/api/caseprimus/v1" curl -X POST "$BASE/parties/PARTY_ID/findings/FINDING_ID/decline" \ -H "X-CasePrimus-Api-Key: $CASEPRIMUS_API_KEY"
const BASE = "https://api.caseprimus.ai/api/caseprimus/v1"; const res = await fetch(BASE + "/parties/PARTY_ID/findings/FINDING_ID/decline", { method: "POST", headers: { "X-CasePrimus-Api-Key": process.env.CASEPRIMUS_API_KEY, }, }); const data = await res.json();
import os import requests BASE = "https://api.caseprimus.ai/api/caseprimus/v1" res = requests.request( "POST", BASE + "/parties/PARTY_ID/findings/FINDING_ID/decline", headers={"X-CasePrimus-Api-Key": os.environ["CASEPRIMUS_API_KEY"]}, ) data = res.json()
Responses
| 200 | The decision was recorded. |
| 400 | No such party (61482), not monitored (61490), or no such candidate (60408). |
{}List what changed for a party
Lists what has happened to this party, a page at a time. kind is one of CASE_FOUND, ORDER_READ, AWAITING_REVIEW, PUT_UNDER_WATCH, DECLINED, RISK_ROSE, RISK_FELL, CASE_STATUS_CHANGED, STAGE_MOVED, HEARING_SET and MONITORING_STARTED. A risk event carries the level the case moved from and to, and is sent only for a real move, never for a case being rated for the first time.
When many events of one kind arrive together, such as a report that found thousands of cases, past a handful they are summarized in batches, one entry per kind with the whole count and the newest few as latest. Ask for that kind in kinds to list them one per row. batches is returned on the first page only.
An API key has no reading history, so every event since the party was created is returned. truncated is true when there is another page.
Request URL
https://api.caseprimus.ai/api/caseprimus/v1/parties/{id}/changesRequest headers
| Type | Name | Value / description | Optional |
|---|---|---|---|
| String | X-CasePrimus-Api-Key | Your API key: {apiKey} | Required |
No API key yet? See Authentication.
Path and query parameters
| Name | In | Required | Description |
|---|---|---|---|
id | path | Required | The id returned when the resource was created. |
$limit | query | Optional | How many items to list. The counts in byKind and total are over the whole window regardless, so a small limit never understates what happened. |
cursor | query | Optional | Where the next page starts: the nextCursor from the previous reply, passed back unchanged. Opaque - it encodes a position per underlying source, not a timestamp, because a report writes all of its cases in a single millisecond and a cursor over a non-unique key silently loses everything sharing the boundary instant. Do not construct or parse it.
|
kinds | query | Optional | List only these kinds. Repeat the parameter or send one comma-separated value. It narrows items ONLY - byKind and total always cover the whole window, so the counts a caller filters by cannot be removed by filtering. Naming a kind also turns off batching for it (see batches): asking for CASE_FOUND means asking for the cases.
|
Sample request
BASE="https://api.caseprimus.ai/api/caseprimus/v1" curl "$BASE/parties/PARTY_ID/changes" \ -H "X-CasePrimus-Api-Key: $CASEPRIMUS_API_KEY"
const BASE = "https://api.caseprimus.ai/api/caseprimus/v1"; const res = await fetch(BASE + "/parties/PARTY_ID/changes", { method: "GET", headers: { "X-CasePrimus-Api-Key": process.env.CASEPRIMUS_API_KEY, }, }); const data = await res.json();
import os import requests BASE = "https://api.caseprimus.ai/api/caseprimus/v1" res = requests.request( "GET", BASE + "/parties/PARTY_ID/changes", headers={"X-CasePrimus-Api-Key": os.environ["CASEPRIMUS_API_KEY"]}, ) data = res.json()
Responses
| 200 | The events in this caller's window, with the counts of the whole of it. |
| 400 | No such party (61482) or malformed input (60001). |
Response fields (HTTP 200)
| Field | Description |
|---|---|
sinceinteger | |
nowinteger | |
totalinteger | |
truncatedboolean | |
byKindobject (free-form) | |
kindsarray of string or null | The kinds asked for, echoed back; null when none were. |
batchesarray of object | One entry per kind that arrived in bulk and was summarised instead of listed. First page only. |
kindenum | CASES_FOUNDORDERS_READMONITORING_BEGAN |
ofstring | The item kind this summarises |
countinteger | How many there are in the whole window. |
atinteger or null | When the newest of them happened. |
latestarray of object | The newest few, so the line can name something rather than only count. |
nextCursorstring or null | Pass back as `cursor` for the next page. Null when this page is the last. |
itemsarray of object |
{
"since": 1793000000000,
"now": 1794045234623,
"total": 4,
"truncated": false,
"byKind": {
"CASE_FOUND": 2,
"ORDER_READ": 1,
"RISK_ROSE": 1
},
"kinds": null,
"batches": [],
"nextCursor": null,
"items": [
{
"kind": "CASE_FOUND",
"at": 1793900000000,
"caseRef": "HC:HBHC010234872025",
"caseNumber": "CRM-M-12345-2025",
"level": "HIGH",
"court": "High Court of Punjab and Haryana",
"caseType": "Criminal Misc.",
"opponent": "Pr Commissioner of Income Tax 3 Pune"
},
{
"kind": "RISK_ROSE",
"at": 1793990000000,
"caseRef": "CPWLC0exampledemo0001",
"caseNumber": "CRM-M-12345-2025",
"level": "HIGH",
"previousLevel": "MODERATE",
"court": "High Court of Punjab and Haryana"
}
]
}{
"since": 1794000000000,
"now": 1794336000000,
"total": 5698,
"truncated": false,
"byKind": {
"CASE_FOUND": 5000,
"ORDER_READ": 698
},
"kinds": null,
"batches": [
{
"kind": "CASES_FOUND",
"of": "CASE_FOUND",
"count": 5000,
"at": 1794332133562,
"latest": [
{
"caseNumber": "173/2026",
"caseRef": "cr_0a1b2c3d4e5f6071"
},
{
"caseNumber": "1194/2026",
"caseRef": "cr_1b2c3d4e5f607182"
},
{
"caseNumber": "1251/2026",
"caseRef": "cr_2c3d4e5f60718293"
}
]
},
{
"kind": "ORDERS_READ",
"of": "ORDER_READ",
"count": 698,
"at": 1794333344112,
"latest": [
{
"caseNumber": "1077/2026",
"caseRef": "cr_3d4e5f6071829304"
}
]
}
],
"nextCursor": null,
"items": []
}{
"since": 1794000000000,
"now": 1794336000000,
"total": 5698,
"truncated": true,
"byKind": {
"CASE_FOUND": 5000,
"ORDER_READ": 698
},
"kinds": [
"CASE_FOUND"
],
"batches": [],
"nextCursor": "eyJDQVNFX0ZPVU5EIjp7ImF0IjoxNzk0MzMyMTMzNTYyLCJpZCI6IkNQTFIwZXhhbXBsZToxIn19",
"items": [
{
"kind": "CASE_FOUND",
"at": 1794332133562,
"caseRef": "cr_0a1b2c3d4e5f6071",
"caseNumber": "173/2026",
"level": "MODERATE",
"court": "District and Sessions Court, Pune",
"courtType": "DC",
"caseType": "Criminal Case",
"opponent": "Ramesh Shantaram Patil",
"opponentCount": 1
},
{
"kind": "CASE_FOUND",
"at": 1794332133562,
"caseRef": "cr_1b2c3d4e5f607182",
"caseNumber": "1194/2026",
"level": "LOW",
"court": "District and Sessions Court, Pune",
"courtType": "DC",
"caseType": "Criminal Case",
"opponent": "Sunita Devi Sharma",
"opponentCount": 1
}
]
}Once, or continuously
| mode | What it does |
|---|---|
ONE_OFF | Assesses the party once, as a litigation report. Nothing keeps watching afterwards. |
MONITOR | Runs the same report, then keeps the party under watch as the courts publish. |
Adding a party can be charged
Help us match the right party
Many Indian companies and people share similar names. The more you tell us, the fewer false matches you will see.
For a company
Give the legal name, and add identifiers such as a registration number, up to three addresses, and any nameVariations you know. Set autoNameVariations to have us derive further spellings.
For a person
Give the full name, plus fatherName and birthDate if you have them.
Where and how far to look
The optional scope object controls the search.
| Field | Values | Default |
|---|---|---|
scope.partyType | PETITIONER, RESPONDENT or BOTH | BOTH |
scope.tier | BASIC reads the court's record. ADVANCED also reads the order documents. | BASIC |
scope.caseStatus | ALL, PENDING or DISPOSED | ALL |
scope.fromYear, scope.toYear | Limit the search to cases filed between two years. | None |
scope.courtTypes | Which courts to look in. Empty means every court. OTHER covers tribunals, consumer commissions and anything that cannot be placed. | Every court |
Where a finding stands
findingState says where a case stands for the party.
| findingState | Meaning |
|---|---|
REPORT_ONLY | Found when the party was assessed. It is not being monitored. |
NOT_REVIEWED | Waiting for you to accept or decline it. |
WATCHED | Accepted, and monitored from now on. |
DECLINED | Declined. It stays on the party's record, and you can accept it later. |
How much was read
depth says how much CasePrimus.ai read for each case.
RECORD
The court record
The case details, including its acts and sections.
ORDER_LATEST
The latest order
The record, and also the most recent order. This is what an ADVANCED assessment reads.
ORDER_ALL
Every order
The record and every order. This is what a monitored case gets.
Alerts and webhooks
Alerts appear in your dashboard. To have the data flow into a system you already run, subscribe a webhook to the events you care about. These are the ones most teams start with.
| Event | What it tells you |
|---|---|
| case.pending_review | A newly discovered case is waiting for your review before monitoring begins. |
| case.added | A new case was detected and added to the watchlist without needing manual review. |
| case.new_order_or_hearing | A new order was uploaded, or a hearing date was added/changed, on a monitored case. |
| case.risk_level_changed | A monitored case's computed risk level moved to a different band (e.g. Medium to High). |
| case.summary_refreshed | A new AI-generated summary was produced for a monitored case after a data refresh. |
| party.reputation_changed | A party's reputation score moved into a different band. Subscriptions naming the retired entity.reputation_changed still receive it. |
| party.historical_scan_completed | The one-time historical case scan for a newly added party finished running. |
See all 15 webhook events and their payloads, or read how deliveries are signed and retried.
Errors
Errors use the HTTP status and a JSON body with a stable numeric code. These are the errors documented for the Parties Watchlist API. The full format, and the limits that apply to every call, are on Rate limits & errors.
| Status | Code | Message |
|---|---|---|
| 400 | 61482 | No party exists with this id |
| 400 | 61483 | Another active party already uses this reference |
| 400 | 61487 | This signal is always on and cannot be switched off. A report that omitted it would be misleading rather than merely narrow |
| 400 | 61489 | Custom / Other cannot be combined with another entity category - it means none of them applies |
Frequently asked questions
What is a party?
Anyone you deal with: a customer, supplier, borrower or counterparty, a company or a person. You say what they are to you, and CasePrimus.ai watches the signals that belong to that relationship.
Can a party be more than one thing?
Yes. entityCategories is a list. A company can be your vendor and your borrower, and it is watched for the signals that matter to both.
What is the difference between ONE_OFF and MONITOR?
ONE_OFF assesses the party once and nothing keeps watching. MONITOR runs the same assessment and then keeps watching as the courts publish. A party can move between the two later without being added again.
Do I have to review every case that is found?
Found cases wait in the review queue until you accept or decline them. Accept one and it is monitored. Decline it and it stays on the party's record as declined, and you can still accept it later. A case the court already shows as disposed is added only when you send confirmDisposed as true.
Does adding a party cost anything?
Adding a party starts work and can be charged against your plan. If your plan does not allow it, the call is refused and nothing is stored. Editing a party never charges you.
How do I get alerted when something changes?
Subscribe a webhook to events such as case.pending_review and case.new_order_or_hearing, or read a party's changes. CasePrimus.ai sends each event to your endpoint, signed and retried.
What happened to the Litigation Watchlist and Third Party Litigation Report APIs?
Parties replaces both. Their endpoints still answer for existing integrations, but a new integration should start with the Parties Watchlist API.
How do I get an API key?
Create one from the Developer console in your CasePrimus.ai dashboard. Don't have an account yet? Request a demo and we will set you up.