CasePrimus.aiby Attestr
Documentation menu
APIv1Updated 14 November 2026

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

How the Parties Watchlist API worksFour steps: you add a company or person and say what they are to you; CasePrimus.ai searches Indian courts and tribunals; you accept or decline each case found; you receive an alert in the dashboard, by email or by webhook.1Add a partyA company or a person,and what they are to you2Courts searchedCourts and tribunalsacross India3You reviewAccept or declineeach case found4You get alertedDashboard, emailor webhook
Figure 1. The four steps behind every party. You add the party and review what is found; the searching and the alerts run on their own.
  1. 1

    Add a party

    Send a company or a person, and what they are to you, to POST /parties. You do this once.

  2. 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. 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. 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

Send your API key in the X-CasePrimus-Api-Key header. See Authentication, and Rate limits & errors.

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

GEThttps://api.caseprimus.ai/api/caseprimus/v1/parties/catalog

Request headers

TypeNameValue / descriptionOptional
StringX-CasePrimus-Api-KeyYour API key: {apiKey}Required

No API key yet? See Authentication.

Sample request

Request
BASE="https://api.caseprimus.ai/api/caseprimus/v1"

curl "$BASE/parties/catalog" \
  -H "X-CasePrimus-Api-Key: $CASEPRIMUS_API_KEY"

Responses

200The whole catalogue.
403The caller lacks watchlist.read.

Response fields (HTTP 200)

FieldDescription
partyFamilies
array of object
entityCategories
array of object
signalFamilies
array of object
signals
array of object
id
string
family
string
name
string
about
string
availability
enum

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
kind
enum

`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
alwaysOn
array 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
partySides
array of string
Response 200
{
  "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

POSThttps://api.caseprimus.ai/api/caseprimus/v1/parties

Request headers

TypeNameValue / descriptionOptional
StringContent-Typeapplication/jsonRequired
StringX-CasePrimus-Api-KeyYour API key: {apiKey}Required

No API key yet? See Authentication.

Input parameters

FieldDescription
name
string
Required

2 to 255 characters

entityType
enum
Required
PERSONBUSINESS
entityCategories
array 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
mode
enum
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
skipReport
boolean
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).

nameVariations
array 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.

autoNameVariations
boolean
Optional

Ask us to derive further spellings in addition to the ones you send.

identifiers
any 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.

addresses
array 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.

label
string or null
Optional

up to 60 characters

line
string or null
Optional

up to 400 characters

city
string or null
Optional

up to 100 characters

district
string or null
Optional

up to 100 characters

state
string or null
Optional

up to 100 characters

pincode
string or null
Optional
registrationNumber
string or null
Optional

The watchlist entity's older free-text spelling of `identifiers`. Derived from them when you send those

up to 100 characters

location
string or null
Optional

The older free-text spelling of `addresses`

up to 4192 characters

tag
string or null
Optional

up to 100 characters

fatherName
string or null
Optional

up to 256 characters

birthDate
string or null
Optional
labels
array of string or null
Optional
signals
array 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
declined
array 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
scope
object
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.

partyType
enum
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
tier
enum
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
caseStatus
enum
Optional
ALLPENDINGDISPOSED
fromYear
integer or null
Optional
toYear
integer or null
Optional
courtTypes
array of enum
Optional

Which courts to go looking in. Empty means every court. OTHER covers tribunals, consumer commissions and anything unplaceable.

SCHCDCOTHER
maxCases
integer
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

sort
enum
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

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"
    ]
  }'

Responses

200The party as it now stands.
400Malformed 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)

FieldDescription
_id
string
number
string or null
name
string
entityType
enum
PERSONBUSINESS
risk
object 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.

score
integer or null

0-1000, higher is better.

scale
integer
level
enum or null
VERY_HIGHHIGHMODERATELOWMINIMAL
pendingReview
integer

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.

monitoredCases
integer

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.

casesFound
integer 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.

entityCategories
array 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
categories
array 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.

id
string
name
string or null
partyFamily
string or null
partyFamilyName
string or null
retired
boolean
mode
enum

`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
status
enum
ACTIVEARCHIVED
nameVariations
array of string

Other spellings of the same company

autoNameVariations
boolean

Whether you asked us to derive further spellings as well.

identifiers
array 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.

type
enum or null
CINPANGSTINUDYAMOTHERnull
value
string
addresses
array 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.

label
string or null
line
string or null
city
string or null
district
string or null
state
string or null
pincode
string or null
registrationNumber
string or null

The watchlist entity's older free-text spelling of `identifiers`

up to 100 characters

location
string or null

The older free-text spelling of `addresses`

tag
string or null

Your own reference for this party. Unique among your active parties; archiving frees it.

fatherName
string or null

PERSON only. Identifying metadata

birthDate
string or null
labels
array of string
signals
array of object
signal
string
name
string or null
family
string or null
availability
enum or null
LIVEPARTIALNOT_AVAILABLE
kind
enum or null
CLASSIFICATIONDERIVED
retired
boolean

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.

declinedSignals
array 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.

scope
object

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.

partyType
enum

Which side of a case to look for this party on. Defaults to BOTH - narrowing to one side silently hides half the cases.

PETITIONERRESPONDENTBOTH
tier
enum

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
caseStatus
enum
ALLPENDINGDISPOSED
fromYear
integer or null
toYear
integer or null
courtTypes
array of enum

Which courts to go looking in. Empty means every court. OTHER covers tribunals, consumer commissions and anything unplaceable.

SCHCDCOTHER
maxCases
integer

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

sort
enum

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
selectionSource
enum 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
source
object 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.

reportId
string

The litigation report that assesses them. Always set - both modes begin with one.

entityId
string or null

The watchlist entity that keeps looking. Null unless `mode` is MONITOR.

rerun
object 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.

previousReportIds
array 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.

decision
object

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.

verdict
enum

`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
note
string or null

The reason

up to 1000 characters

by
string or null

The user who decided. Null for a decision taken with an API key rather than by a signed-in user.

at
integer (int64)

When it was taken.

atScore
integer or null

The reputation score at the time

0 to 1000

atLevel
enum or null

The litigation level at the time

VERY_HIGHHIGHMODERATELOWMINIMALUNCLASSIFIED
decisionHistory
array 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.

verdict
enum

`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
note
string or null

The reason

up to 1000 characters

by
string or null

The user who decided. Null for a decision taken with an API key rather than by a signed-in user.

at
integer (int64)

When it was taken.

atScore
integer or null

The reputation score at the time

0 to 1000

atLevel
enum or null

The litigation level at the time

VERY_HIGHHIGHMODERATELOWMINIMALUNCLASSIFIED
rerun
object

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.

pending
boolean

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.

changed
array 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.

noReport
boolean

No report is answering this party at all. A re-run is how it gets one.

needsDiscovery
boolean

A search input moved

needsIdentityRematch
boolean

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.

tierRaised
boolean

BASIC to ADVANCED. The carried cases have no order read to carry

running
object or null

The re-run in flight, if there is one. Null otherwise.

lastFailure
object or null

The last re-run failed - its discovery could not be collected. The change is pending again; start another.

estimate
object

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.

answeringReportId
string or null

The report the findings on screen actually came from.

answeredAt
integer (int64) or null

When that report finished.

created
integer (int64)
createdBy
string or null
updated
integer (int64) or null
updatedBy
string or null
Response 200
{
  "_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

POSThttps://api.caseprimus.ai/api/caseprimus/v1/parties/search

Request headers

TypeNameValue / descriptionOptional
StringContent-Typeapplication/jsonRequired
StringX-CasePrimus-Api-KeyYour API key: {apiKey}Required

No API key yet? See Authentication.

Input parameters

FieldDescription
$limit
integer
Optional

1 to 200

$skip
integer
Optional

minimum 0

$sort
enum
Optional
createdcreated_descnamename_descupdatedupdated_desc
$like
string
Optional

Matches the name

status
enum
Optional
ACTIVEARCHIVED
mode
enum
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
entityCategory
enum
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
entityCategories
array 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
entityType
enum
Optional
PERSONBUSINESS
labels
array of string
Optional
addedFrom
integer (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.

addedTo
integer (int64)
Optional

Added on or before this time.

level
enum
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
scoreMin
integer
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

scoreMax
integer
Optional

0 to 1000

Sample request

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"
  }'

Responses

200A page of parties.

Response fields (HTTP 200)

FieldDescription
records
array of object
_id
string
number
string or null
name
string
entityType
enum
PERSONBUSINESS
risk
object 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.

pendingReview
integer

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.

monitoredCases
integer

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.

casesFound
integer 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.

entityCategories
array 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
categories
array 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.

mode
enum

`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
status
enum
ACTIVEARCHIVED
nameVariations
array of string

Other spellings of the same company

autoNameVariations
boolean

Whether you asked us to derive further spellings as well.

identifiers
array 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.

addresses
array 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.

registrationNumber
string or null

The watchlist entity's older free-text spelling of `identifiers`

up to 100 characters

location
string or null

The older free-text spelling of `addresses`

tag
string or null

Your own reference for this party. Unique among your active parties; archiving frees it.

fatherName
string or null

PERSON only. Identifying metadata

birthDate
string or null
labels
array of string
signals
array of object
declinedSignals
array 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.

scope
object

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.

selectionSource
enum 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
source
object 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.

decision
object

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.

decisionHistory
array 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.

rerun
object

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.

created
integer (int64)
createdBy
string or null
updated
integer (int64) or null
updatedBy
string or null
total
integer
limit
integer
skip
integer
Response 200
{
  "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

GEThttps://api.caseprimus.ai/api/caseprimus/v1/parties/{id}

Request headers

TypeNameValue / descriptionOptional
StringX-CasePrimus-Api-KeyYour API key: {apiKey}Required

No API key yet? See Authentication.

Path parameters

NameInRequiredDescription
idpathRequiredThe id returned when the resource was created.

Sample request

Request
BASE="https://api.caseprimus.ai/api/caseprimus/v1"

curl "$BASE/parties/PARTY_ID" \
  -H "X-CasePrimus-Api-Key: $CASEPRIMUS_API_KEY"

Responses

200The party.
400No such party (61482), or the id is malformed (60001).

Response fields (HTTP 200)

FieldDescription
_id
string
number
string or null
name
string
entityType
enum
PERSONBUSINESS
risk
object 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.

score
integer or null

0-1000, higher is better.

scale
integer
level
enum or null
VERY_HIGHHIGHMODERATELOWMINIMAL
pendingReview
integer

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.

monitoredCases
integer

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.

casesFound
integer 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.

entityCategories
array 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
categories
array 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.

id
string
name
string or null
partyFamily
string or null
partyFamilyName
string or null
retired
boolean
mode
enum

`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
status
enum
ACTIVEARCHIVED
nameVariations
array of string

Other spellings of the same company

autoNameVariations
boolean

Whether you asked us to derive further spellings as well.

identifiers
array 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.

type
enum or null
CINPANGSTINUDYAMOTHERnull
value
string
addresses
array 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.

label
string or null
line
string or null
city
string or null
district
string or null
state
string or null
pincode
string or null
registrationNumber
string or null

The watchlist entity's older free-text spelling of `identifiers`

up to 100 characters

location
string or null

The older free-text spelling of `addresses`

tag
string or null

Your own reference for this party. Unique among your active parties; archiving frees it.

fatherName
string or null

PERSON only. Identifying metadata

birthDate
string or null
labels
array of string
signals
array of object
signal
string
name
string or null
family
string or null
availability
enum or null
LIVEPARTIALNOT_AVAILABLE
kind
enum or null
CLASSIFICATIONDERIVED
retired
boolean

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.

declinedSignals
array 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.

scope
object

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.

partyType
enum

Which side of a case to look for this party on. Defaults to BOTH - narrowing to one side silently hides half the cases.

PETITIONERRESPONDENTBOTH
tier
enum

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
caseStatus
enum
ALLPENDINGDISPOSED
fromYear
integer or null
toYear
integer or null
courtTypes
array of enum

Which courts to go looking in. Empty means every court. OTHER covers tribunals, consumer commissions and anything unplaceable.

SCHCDCOTHER
maxCases
integer

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

sort
enum

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
selectionSource
enum 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
source
object 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.

reportId
string

The litigation report that assesses them. Always set - both modes begin with one.

entityId
string or null

The watchlist entity that keeps looking. Null unless `mode` is MONITOR.

rerun
object 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.

previousReportIds
array 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.

decision
object

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.

verdict
enum

`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
note
string or null

The reason

up to 1000 characters

by
string or null

The user who decided. Null for a decision taken with an API key rather than by a signed-in user.

at
integer (int64)

When it was taken.

atScore
integer or null

The reputation score at the time

0 to 1000

atLevel
enum or null

The litigation level at the time

VERY_HIGHHIGHMODERATELOWMINIMALUNCLASSIFIED
decisionHistory
array 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.

verdict
enum

`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
note
string or null

The reason

up to 1000 characters

by
string or null

The user who decided. Null for a decision taken with an API key rather than by a signed-in user.

at
integer (int64)

When it was taken.

atScore
integer or null

The reputation score at the time

0 to 1000

atLevel
enum or null

The litigation level at the time

VERY_HIGHHIGHMODERATELOWMINIMALUNCLASSIFIED
rerun
object

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.

pending
boolean

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.

changed
array 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.

noReport
boolean

No report is answering this party at all. A re-run is how it gets one.

needsDiscovery
boolean

A search input moved

needsIdentityRematch
boolean

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.

tierRaised
boolean

BASIC to ADVANCED. The carried cases have no order read to carry

running
object or null

The re-run in flight, if there is one. Null otherwise.

lastFailure
object or null

The last re-run failed - its discovery could not be collected. The change is pending again; start another.

estimate
object

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.

answeringReportId
string or null

The report the findings on screen actually came from.

answeredAt
integer (int64) or null

When that report finished.

created
integer (int64)
createdBy
string or null
updated
integer (int64) or null
updatedBy
string or null
Response 200
{
  "_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

GEThttps://api.caseprimus.ai/api/caseprimus/v1/parties/review-queue

Request headers

TypeNameValue / descriptionOptional
StringX-CasePrimus-Api-KeyYour API key: {apiKey}Required

No API key yet? See Authentication.

Path and query parameters

NameInRequiredDescription
$limitqueryOptional
$skipqueryOptional
partyIdqueryOptionalOne party's share of the queue. byParty on the response says which parties have anything waiting.
levelqueryOptional

Sample request

Request
BASE="https://api.caseprimus.ai/api/caseprimus/v1"

curl "$BASE/parties/review-queue" \
  -H "X-CasePrimus-Api-Key: $CASEPRIMUS_API_KEY"

Responses

200The cases waiting for a decision.
401Not signed in.

Response fields (HTTP 200)

FieldDescription
records
array of object
total
integer
byParty
array 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.

partyId
string
name
string or null
count
integer
oldestAt
integer 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.

limit
integer
skip
integer
Response 200
{
  "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

GEThttps://api.caseprimus.ai/api/caseprimus/v1/parties/{id}/findings

Request headers

TypeNameValue / descriptionOptional
StringX-CasePrimus-Api-KeyYour API key: {apiKey}Required

No API key yet? See Authentication.

Path and query parameters

NameInRequiredDescription
idpathRequiredThe id returned when the resource was created.
$limitqueryOptionalUp 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.
$skipqueryOptional
$sortqueryOptional
$likequeryOptionalMatches 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.
caseRefqueryOptionalFetch 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.
tabqueryOptionalThe screen's own three lists. historical is two states at once (report-only and declined), which state cannot express.
statequeryOptional
signalqueryOptionalA signal id from GET /parties/catalog.
levelqueryOptional
courtTypequeryOptional
caseStatequeryOptionalThe 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.
caseStatusqueryOptional
filedFromqueryOptionalCases 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.
filedToqueryOptionalCases filed on or before this date. See filedFrom.
scoreMinqueryOptionalThe 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.
scoreMaxqueryOptionalSee scoreMin.
opponentqueryOptionalA 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".
alongsidequeryOptionalThe 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

Request
BASE="https://api.caseprimus.ai/api/caseprimus/v1"

curl "$BASE/parties/PARTY_ID/findings" \
  -H "X-CasePrimus-Api-Key: $CASEPRIMUS_API_KEY"

Responses

200The party's cases, with the counts of the whole set.
400No such party (61482) or malformed input (60001).

Response fields (HTTP 200)

FieldDescription
records
array of object
total
integer
counts
object (free-form)
Response 200
{
  "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
    }
  }
}

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

POSThttps://api.caseprimus.ai/api/caseprimus/v1/parties/{id}/findings/{candidateId}/promote

Request headers

TypeNameValue / descriptionOptional
StringX-CasePrimus-Api-KeyYour API key: {apiKey}Required

No API key yet? See Authentication.

Path parameters

NameInRequiredDescription
idpathRequiredThe id returned when the resource was created.
candidateIdpathRequiredThe id returned when the resource was created.

Sample request

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"

Responses

200The case that is now monitored.
400No such party (61482), not monitored (61490), no such candidate (60408), or the case is disposed (60430).
Response 200
{
  "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

POSThttps://api.caseprimus.ai/api/caseprimus/v1/parties/{id}/findings/{candidateId}/decline

Request headers

TypeNameValue / descriptionOptional
StringX-CasePrimus-Api-KeyYour API key: {apiKey}Required

No API key yet? See Authentication.

Path parameters

NameInRequiredDescription
idpathRequiredThe id returned when the resource was created.
candidateIdpathRequiredThe id returned when the resource was created.

Sample request

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"

Responses

200The decision was recorded.
400No such party (61482), not monitored (61490), or no such candidate (60408).
Response 200
{}

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

GEThttps://api.caseprimus.ai/api/caseprimus/v1/parties/{id}/changes

Request headers

TypeNameValue / descriptionOptional
StringX-CasePrimus-Api-KeyYour API key: {apiKey}Required

No API key yet? See Authentication.

Path and query parameters

NameInRequiredDescription
idpathRequiredThe id returned when the resource was created.
$limitqueryOptionalHow many items to list. The counts in byKind and total are over the whole window regardless, so a small limit never understates what happened.
cursorqueryOptionalWhere 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.
kindsqueryOptionalList 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

Request
BASE="https://api.caseprimus.ai/api/caseprimus/v1"

curl "$BASE/parties/PARTY_ID/changes" \
  -H "X-CasePrimus-Api-Key: $CASEPRIMUS_API_KEY"

Responses

200The events in this caller's window, with the counts of the whole of it.
400No such party (61482) or malformed input (60001).

Response fields (HTTP 200)

FieldDescription
since
integer
now
integer
total
integer
truncated
boolean
byKind
object (free-form)
kinds
array of string or null

The kinds asked for, echoed back; null when none were.

batches
array of object

One entry per kind that arrived in bulk and was summarised instead of listed. First page only.

kind
enum
CASES_FOUNDORDERS_READMONITORING_BEGAN
of
string

The item kind this summarises

count
integer

How many there are in the whole window.

at
integer or null

When the newest of them happened.

latest
array of object

The newest few, so the line can name something rather than only count.

nextCursor
string or null

Pass back as `cursor` for the next page. Null when this page is the last.

items
array of object
Response 200
{
  "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"
    }
  ]
}

Once, or continuously

modeWhat it does
ONE_OFFAssesses the party once, as a litigation report. Nothing keeps watching afterwards.
MONITORRuns the same report, then keeps the party under watch as the courts publish.

Adding a party can be charged

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.

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.

FieldValuesDefault
scope.partyTypePETITIONER, RESPONDENT or BOTHBOTH
scope.tierBASIC reads the court's record. ADVANCED also reads the order documents.BASIC
scope.caseStatusALL, PENDING or DISPOSEDALL
scope.fromYear, scope.toYearLimit the search to cases filed between two years.None
scope.courtTypesWhich 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.

findingStateMeaning
REPORT_ONLYFound when the party was assessed. It is not being monitored.
NOT_REVIEWEDWaiting for you to accept or decline it.
WATCHEDAccepted, and monitored from now on.
DECLINEDDeclined. 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.

EventWhat it tells you
case.pending_reviewA newly discovered case is waiting for your review before monitoring begins.
case.addedA new case was detected and added to the watchlist without needing manual review.
case.new_order_or_hearingA new order was uploaded, or a hearing date was added/changed, on a monitored case.
case.risk_level_changedA monitored case's computed risk level moved to a different band (e.g. Medium to High).
case.summary_refreshedA new AI-generated summary was produced for a monitored case after a data refresh.
party.reputation_changedA party's reputation score moved into a different band. Subscriptions naming the retired entity.reputation_changed still receive it.
party.historical_scan_completedThe 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.

StatusCodeMessage
40061482No party exists with this id
40061483Another active party already uses this reference
40061487This signal is always on and cannot be switched off. A report that omitted it would be misleading rather than merely narrow
40061489Custom / 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.