# Parties Watchlist API

Source: https://caseprimus.ai/docs/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.

## 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**

`GET https://api.caseprimus.ai/api/caseprimus/v1/parties/catalog`

**Request headers**

| Type | Name | Value | Optional |
| --- | --- | --- | --- |
| String | `X-CasePrimus-Api-Key` | Your API key | Required |

**Sample request**

```bash
BASE="https://api.caseprimus.ai/api/caseprimus/v1"

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

**Responses**

- `200`: The whole catalogue.
- `403`: The caller lacks watchlist.read.

**Response fields (HTTP 200)**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `partyFamilies` | array of object |  |  |
| `entityCategories` | array of object |  |  |
| `signalFamilies` | array of object |  |  |
| `signals` | array of object |  |  |
| `signals[].id` | string |  |  |
| `signals[].family` | string |  |  |
| `signals[].name` | string |  |  |
| `signals[].about` | string |  |  |
| `signals[].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.  One of: LIVE, PARTIAL, NOT_AVAILABLE |
| `signals[].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.  One of: CLASSIFICATION, DERIVED |
| `alwaysOn` | array of enum |  | One of: insolvency.petition, insolvency.admitted, insolvency.liquidation, insolvency.resolved, insolvency.s95.personal, insolvency.nclat.appeal, insolvency.avoidance.preferential, secured.drt.recovery, secured.drat.appeal, secured.sarfaesi.enforcement, secured.recovery.certificate, secured.enforcement.same, cheque.s138, cheque.velocity, cheque.s148.appellate, cheque.other.instruments, civil.summary.suit, civil.commercial.court, civil.original.side, civil.specific.performance, civil.execution, arbitration.s9.interim, arbitration.s11.arbitrator, arbitration.s34.challenge, arbitration.s36.enforcement, arbitration.s37.appeal, tax.income.itat, tax.indirect.cestat, tax.gst.appellate, tax.recovery.attachment, tax.writ, tax.prosecution.statutory, corporate.oppression.mismanagement, corporate.company.compromise, corporate.director.disqualification, corporate.class.action, corporate.serious.fraud, securities.sat.appeal, securities.sebi.penalties, securities.rbi.enforcement, securities.wilful.defaulter, consumer.complaint, consumer.volume.pattern, consumer.unfair.trade, property.title.partition, property.land.acquisition, property.tenancy.eviction, property.mortgage.charge, labour.industrial.dispute, labour.epf.s7a, labour.epfo.defaulter, labour.esi, labour.writ.employment, labour.wage.gratuity, labour.factory.safety, environment.ngt, environment.pcb, environment.writ, environment.aptel, environment.tdsat, environment.competition.appeals, criminal.economic, criminal.directors, criminal.quashing, criminal.bail.anticipatory, criminal.fir.registration, ip.infringement, ip.passing.off, ip.injunction, appeal.supreme.court, appeal.high.court, appeal.adverse.order, appeal.costs.imposed, appeal.adverse.judicial, behaviour.filing.velocity, behaviour.respondent.side, behaviour.creditor.diversity, behaviour.escalation.rate, behaviour.adjournment.delay, behaviour.abandonment, behaviour.forum.spread, behaviour.counsel.churn, behaviour.dormancy.break, network.adversary.map, network.coparty.map, network.shared.counsel, network.common.address, network.group.company, registry.mca.status, registry.registered.secured, registry.directorship.signatory, registry.related.company, registry.gstin.status, registry.udyam.msme, registry.filed.financials, registry.credit.bureau, extended.guarantee.enforcement, extended.franchise.distribution, extended.agency.commission, extended.carriage.cargo, extended.admiralty.ship, extended.demurrage.detention, extended.customs.valuation, extended.debarment.blacklisting, extended.insurance.coverage, extended.motor.mact, extended.medical.negligence, extended.insurance.fraud, extended.repeat.claimant, extended.non.compete, extended.professional.disciplinary, extended.encumbrance.competing, provider.deempanelment, provider.clinical.establishment, provider.fire.safety, provider.biomedical.hazardous, provider.drug.pharmacy, provider.regulated.practice, provider.counterfeit.spurious, provider.workshop.licensing, sector.product.liability, sector.fssai, sector.metrology, sector.nppa.price, sector.patent.linkage, sector.clinical.trial, sector.public.liability, sector.mining, sector.forest.clearance, sector.essential.commodities, sector.bis, sector.epr.waste, sector.data.protection |
| `partySides` | array of string |  |  |

**Example response (200)**

```json
{
  "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**

`POST https://api.caseprimus.ai/api/caseprimus/v1/parties`

**Request headers**

| Type | Name | Value | Optional |
| --- | --- | --- | --- |
| String | `Content-Type` | `application/json` | Required |
| String | `X-CasePrimus-Api-Key` | Your API key | Required |

**Input parameters**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Required | 2 to 255 characters |
| `entityType` | enum | Required | One of: PERSON, BUSINESS |
| `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 One of: borrower.equipment, borrower.receivables, borrower.secured, borrower.unsecured, colender, collateral.provider, guarantor, trade.counterparty, agent, channel.partner, logistics, service.provider, vendor, acquisition.target, group.company, joint.venture, key.hire, professional, promoter, claimant, insured, insured.asset, provider.empanelment, provider.leakage, reinsurance, subrogation, landlord, tenant, government, opposing.party, own.entity, other.custom, lender, debt.assignee, platform.fintech, principal.brand, acquirer.parent, investor.fund, divesting.seller, insurer, broker.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 of: ONE_OFF, MONITOR |
| `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. |
| `addresses[].label` | string or null | Optional | up to 60 characters |
| `addresses[].line` | string or null | Optional | up to 400 characters |
| `addresses[].city` | string or null | Optional | up to 100 characters |
| `addresses[].district` | string or null | Optional | up to 100 characters |
| `addresses[].state` | string or null | Optional | up to 100 characters |
| `addresses[].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. One of: insolvency.petition, insolvency.admitted, insolvency.liquidation, insolvency.resolved, insolvency.s95.personal, insolvency.nclat.appeal, insolvency.avoidance.preferential, secured.drt.recovery, secured.drat.appeal, secured.sarfaesi.enforcement, secured.recovery.certificate, secured.enforcement.same, cheque.s138, cheque.velocity, cheque.s148.appellate, cheque.other.instruments, civil.summary.suit, civil.commercial.court, civil.original.side, civil.specific.performance, civil.execution, arbitration.s9.interim, arbitration.s11.arbitrator, arbitration.s34.challenge, arbitration.s36.enforcement, arbitration.s37.appeal, tax.income.itat, tax.indirect.cestat, tax.gst.appellate, tax.recovery.attachment, tax.writ, tax.prosecution.statutory, corporate.oppression.mismanagement, corporate.company.compromise, corporate.director.disqualification, corporate.class.action, corporate.serious.fraud, securities.sat.appeal, securities.sebi.penalties, securities.rbi.enforcement, securities.wilful.defaulter, consumer.complaint, consumer.volume.pattern, consumer.unfair.trade, property.title.partition, property.land.acquisition, property.tenancy.eviction, property.mortgage.charge, labour.industrial.dispute, labour.epf.s7a, labour.epfo.defaulter, labour.esi, labour.writ.employment, labour.wage.gratuity, labour.factory.safety, environment.ngt, environment.pcb, environment.writ, environment.aptel, environment.tdsat, environment.competition.appeals, criminal.economic, criminal.directors, criminal.quashing, criminal.bail.anticipatory, criminal.fir.registration, ip.infringement, ip.passing.off, ip.injunction, appeal.supreme.court, appeal.high.court, appeal.adverse.order, appeal.costs.imposed, appeal.adverse.judicial, behaviour.filing.velocity, behaviour.respondent.side, behaviour.creditor.diversity, behaviour.escalation.rate, behaviour.adjournment.delay, behaviour.abandonment, behaviour.forum.spread, behaviour.counsel.churn, behaviour.dormancy.break, network.adversary.map, network.coparty.map, network.shared.counsel, network.common.address, network.group.company, registry.mca.status, registry.registered.secured, registry.directorship.signatory, registry.related.company, registry.gstin.status, registry.udyam.msme, registry.filed.financials, registry.credit.bureau, extended.guarantee.enforcement, extended.franchise.distribution, extended.agency.commission, extended.carriage.cargo, extended.admiralty.ship, extended.demurrage.detention, extended.customs.valuation, extended.debarment.blacklisting, extended.insurance.coverage, extended.motor.mact, extended.medical.negligence, extended.insurance.fraud, extended.repeat.claimant, extended.non.compete, extended.professional.disciplinary, extended.encumbrance.competing, provider.deempanelment, provider.clinical.establishment, provider.fire.safety, provider.biomedical.hazardous, provider.drug.pharmacy, provider.regulated.practice, provider.counterfeit.spurious, provider.workshop.licensing, sector.product.liability, sector.fssai, sector.metrology, sector.nppa.price, sector.patent.linkage, sector.clinical.trial, sector.public.liability, sector.mining, sector.forest.clearance, sector.essential.commodities, sector.bis, sector.epr.waste, sector.data.protection |
| `declined` | array of enum | Optional | One of: insolvency.petition, insolvency.admitted, insolvency.liquidation, insolvency.resolved, insolvency.s95.personal, insolvency.nclat.appeal, insolvency.avoidance.preferential, secured.drt.recovery, secured.drat.appeal, secured.sarfaesi.enforcement, secured.recovery.certificate, secured.enforcement.same, cheque.s138, cheque.velocity, cheque.s148.appellate, cheque.other.instruments, civil.summary.suit, civil.commercial.court, civil.original.side, civil.specific.performance, civil.execution, arbitration.s9.interim, arbitration.s11.arbitrator, arbitration.s34.challenge, arbitration.s36.enforcement, arbitration.s37.appeal, tax.income.itat, tax.indirect.cestat, tax.gst.appellate, tax.recovery.attachment, tax.writ, tax.prosecution.statutory, corporate.oppression.mismanagement, corporate.company.compromise, corporate.director.disqualification, corporate.class.action, corporate.serious.fraud, securities.sat.appeal, securities.sebi.penalties, securities.rbi.enforcement, securities.wilful.defaulter, consumer.complaint, consumer.volume.pattern, consumer.unfair.trade, property.title.partition, property.land.acquisition, property.tenancy.eviction, property.mortgage.charge, labour.industrial.dispute, labour.epf.s7a, labour.epfo.defaulter, labour.esi, labour.writ.employment, labour.wage.gratuity, labour.factory.safety, environment.ngt, environment.pcb, environment.writ, environment.aptel, environment.tdsat, environment.competition.appeals, criminal.economic, criminal.directors, criminal.quashing, criminal.bail.anticipatory, criminal.fir.registration, ip.infringement, ip.passing.off, ip.injunction, appeal.supreme.court, appeal.high.court, appeal.adverse.order, appeal.costs.imposed, appeal.adverse.judicial, behaviour.filing.velocity, behaviour.respondent.side, behaviour.creditor.diversity, behaviour.escalation.rate, behaviour.adjournment.delay, behaviour.abandonment, behaviour.forum.spread, behaviour.counsel.churn, behaviour.dormancy.break, network.adversary.map, network.coparty.map, network.shared.counsel, network.common.address, network.group.company, registry.mca.status, registry.registered.secured, registry.directorship.signatory, registry.related.company, registry.gstin.status, registry.udyam.msme, registry.filed.financials, registry.credit.bureau, extended.guarantee.enforcement, extended.franchise.distribution, extended.agency.commission, extended.carriage.cargo, extended.admiralty.ship, extended.demurrage.detention, extended.customs.valuation, extended.debarment.blacklisting, extended.insurance.coverage, extended.motor.mact, extended.medical.negligence, extended.insurance.fraud, extended.repeat.claimant, extended.non.compete, extended.professional.disciplinary, extended.encumbrance.competing, provider.deempanelment, provider.clinical.establishment, provider.fire.safety, provider.biomedical.hazardous, provider.drug.pharmacy, provider.regulated.practice, provider.counterfeit.spurious, provider.workshop.licensing, sector.product.liability, sector.fssai, sector.metrology, sector.nppa.price, sector.patent.linkage, sector.clinical.trial, sector.public.liability, sector.mining, sector.forest.clearance, sector.essential.commodities, sector.bis, sector.epr.waste, sector.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.  |
| `scope.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. One of: PETITIONER, RESPONDENT, BOTH |
| `scope.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. One of: BASIC, ADVANCED |
| `scope.caseStatus` | enum | Optional | One of: ALL, PENDING, DISPOSED |
| `scope.fromYear` | integer or null | Optional |  |
| `scope.toYear` | integer or null | Optional |  |
| `scope.courtTypes` | array of enum | Optional | Which courts to go looking in. Empty means every court. OTHER covers tribunals, consumer commissions and anything unplaceable. One of: SC, HC, DC, OTHER |
| `scope.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 |
| `scope.sort` | enum | Optional | The default ordering for this party's findings. A findings view can still sort differently; this is what it opens on. One of: score_desc, filing_desc, filing_asc, order_adverse, order_favourable |

**Sample request**

```bash
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**

- `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 | Type | Required | Description |
| --- | --- | --- | --- |
| `_id` | string |  |  |
| `number` | string or null |  |  |
| `name` | string |  |  |
| `entityType` | enum |  | One of: PERSON, BUSINESS |
| `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.  |
| `risk.score` | integer or null |  | 0-1000, higher is better. |
| `risk.scale` | integer |  |  |
| `risk.level` | enum or null |  | One of: VERY_HIGH, HIGH, MODERATE, LOW, MINIMAL |
| `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. One of: borrower.equipment, borrower.receivables, borrower.secured, borrower.unsecured, colender, collateral.provider, guarantor, trade.counterparty, agent, channel.partner, logistics, service.provider, vendor, acquisition.target, group.company, joint.venture, key.hire, professional, promoter, claimant, insured, insured.asset, provider.empanelment, provider.leakage, reinsurance, subrogation, landlord, tenant, government, opposing.party, own.entity, other.custom, lender, debt.assignee, platform.fintech, principal.brand, acquirer.parent, investor.fund, divesting.seller, insurer, broker.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. |
| `categories[].id` | string |  |  |
| `categories[].name` | string or null |  |  |
| `categories[].partyFamily` | string or null |  |  |
| `categories[].partyFamilyName` | string or null |  |  |
| `categories[].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 of: ONE_OFF, MONITOR |
| `status` | enum |  | One of: ACTIVE, ARCHIVED |
| `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. |
| `identifiers[].type` | enum or null |  | One of: CIN, PAN, GSTIN, UDYAM, OTHER,  |
| `identifiers[].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. |
| `addresses[].label` | string or null |  |  |
| `addresses[].line` | string or null |  |  |
| `addresses[].city` | string or null |  |  |
| `addresses[].district` | string or null |  |  |
| `addresses[].state` | string or null |  |  |
| `addresses[].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 |  |  |
| `signals[].signal` | string |  |  |
| `signals[].name` | string or null |  |  |
| `signals[].family` | string or null |  |  |
| `signals[].availability` | enum or null |  | One of: LIVE, PARTIAL, NOT_AVAILABLE |
| `signals[].kind` | enum or null |  | One of: CLASSIFICATION, DERIVED |
| `signals[].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.  |
| `scope.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. One of: PETITIONER, RESPONDENT, BOTH |
| `scope.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. One of: BASIC, ADVANCED |
| `scope.caseStatus` | enum |  | One of: ALL, PENDING, DISPOSED |
| `scope.fromYear` | integer or null |  |  |
| `scope.toYear` | integer or null |  |  |
| `scope.courtTypes` | array of enum |  | Which courts to go looking in. Empty means every court. OTHER covers tribunals, consumer commissions and anything unplaceable. One of: SC, HC, DC, OTHER |
| `scope.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 |
| `scope.sort` | enum |  | The default ordering for this party's findings. A findings view can still sort differently; this is what it opens on. One of: score_desc, filing_desc, filing_asc, order_adverse, order_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?". One of: CATEGORY_DEFAULTS, CUSTOMER |
| `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.  |
| `source.reportId` | string |  | The litigation report that assesses them. Always set - both modes begin with one. |
| `source.entityId` | string or null |  | The watchlist entity that keeps looking. Null unless `mode` is MONITOR. |
| `source.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. |
| `source.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.  |
| `decision.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.  One of: CLEAR, CONDITIONS, ESCALATE |
| `decision.note` | string or null |  | The reason up to 1000 characters |
| `decision.by` | string or null |  | The user who decided. Null for a decision taken with an API key rather than by a signed-in user. |
| `decision.at` | integer (int64) |  | When it was taken. |
| `decision.atScore` | integer or null |  | The reputation score at the time 0 to 1000 |
| `decision.atLevel` | enum or null |  | The litigation level at the time One of: VERY_HIGH, HIGH, MODERATE, LOW, MINIMAL, UNCLASSIFIED |
| `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.  |
| `decisionHistory[].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.  One of: CLEAR, CONDITIONS, ESCALATE |
| `decisionHistory[].note` | string or null |  | The reason up to 1000 characters |
| `decisionHistory[].by` | string or null |  | The user who decided. Null for a decision taken with an API key rather than by a signed-in user. |
| `decisionHistory[].at` | integer (int64) |  | When it was taken. |
| `decisionHistory[].atScore` | integer or null |  | The reputation score at the time 0 to 1000 |
| `decisionHistory[].atLevel` | enum or null |  | The litigation level at the time One of: VERY_HIGH, HIGH, MODERATE, LOW, MINIMAL, UNCLASSIFIED |
| `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. |
| `rerun.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.  |
| `rerun.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.  |
| `rerun.noReport` | boolean |  | No report is answering this party at all. A re-run is how it gets one. |
| `rerun.needsDiscovery` | boolean |  | A search input moved |
| `rerun.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.  |
| `rerun.tierRaised` | boolean |  | BASIC to ADVANCED. The carried cases have no order read to carry |
| `rerun.running` | object or null |  | The re-run in flight, if there is one. Null otherwise. |
| `rerun.lastFailure` | object or null |  | The last re-run failed - its discovery could not be collected. The change is pending again; start another. |
| `rerun.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.  |
| `rerun.answeringReportId` | string or null |  | The report the findings on screen actually came from. |
| `rerun.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 |  |  |

**Example response (200)**

```json
{
  "_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**

`POST https://api.caseprimus.ai/api/caseprimus/v1/parties/search`

**Request headers**

| Type | Name | Value | Optional |
| --- | --- | --- | --- |
| String | `Content-Type` | `application/json` | Required |
| String | `X-CasePrimus-Api-Key` | Your API key | Required |

**Input parameters**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `$limit` | integer | Optional | 1 to 200 |
| `$skip` | integer | Optional | minimum 0 |
| `$sort` | enum | Optional | One of: created, created_desc, name, name_desc, updated, updated_desc |
| `$like` | string | Optional | Matches the name |
| `status` | enum | Optional | One of: ACTIVE, ARCHIVED |
| `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 of: ONE_OFF, MONITOR |
| `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.  One of: borrower.equipment, borrower.receivables, borrower.secured, borrower.unsecured, colender, collateral.provider, guarantor, trade.counterparty, agent, channel.partner, logistics, service.provider, vendor, acquisition.target, group.company, joint.venture, key.hire, professional, promoter, claimant, insured, insured.asset, provider.empanelment, provider.leakage, reinsurance, subrogation, landlord, tenant, government, opposing.party, own.entity, other.custom, lender, debt.assignee, platform.fintech, principal.brand, acquirer.parent, investor.fund, divesting.seller, insurer, broker.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. One of: borrower.equipment, borrower.receivables, borrower.secured, borrower.unsecured, colender, collateral.provider, guarantor, trade.counterparty, agent, channel.partner, logistics, service.provider, vendor, acquisition.target, group.company, joint.venture, key.hire, professional, promoter, claimant, insured, insured.asset, provider.empanelment, provider.leakage, reinsurance, subrogation, landlord, tenant, government, opposing.party, own.entity, other.custom, lender, debt.assignee, platform.fintech, principal.brand, acquirer.parent, investor.fund, divesting.seller, insurer, broker.intermediary |
| `entityType` | enum | Optional | One of: PERSON, BUSINESS |
| `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. One of: VERY_HIGH, HIGH, MODERATE, LOW, MINIMAL |
| `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**

```bash
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**

- `200`: A page of parties.

**Response fields (HTTP 200)**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `records` | array of object |  |  |
| `records[]._id` | string |  |  |
| `records[].number` | string or null |  |  |
| `records[].name` | string |  |  |
| `records[].entityType` | enum |  | One of: PERSON, BUSINESS |
| `records[].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.  |
| `records[].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.  |
| `records[].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.  |
| `records[].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.  |
| `records[].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. One of: borrower.equipment, borrower.receivables, borrower.secured, borrower.unsecured, colender, collateral.provider, guarantor, trade.counterparty, agent, channel.partner, logistics, service.provider, vendor, acquisition.target, group.company, joint.venture, key.hire, professional, promoter, claimant, insured, insured.asset, provider.empanelment, provider.leakage, reinsurance, subrogation, landlord, tenant, government, opposing.party, own.entity, other.custom, lender, debt.assignee, platform.fintech, principal.brand, acquirer.parent, investor.fund, divesting.seller, insurer, broker.intermediary |
| `records[].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. |
| `records[].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 of: ONE_OFF, MONITOR |
| `records[].status` | enum |  | One of: ACTIVE, ARCHIVED |
| `records[].nameVariations` | array of string |  | Other spellings of the same company |
| `records[].autoNameVariations` | boolean |  | Whether you asked us to derive further spellings as well. |
| `records[].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. |
| `records[].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. |
| `records[].registrationNumber` | string or null |  | The watchlist entity's older free-text spelling of `identifiers` up to 100 characters |
| `records[].location` | string or null |  | The older free-text spelling of `addresses` |
| `records[].tag` | string or null |  | Your own reference for this party. Unique among your active parties; archiving frees it. |
| `records[].fatherName` | string or null |  | PERSON only. Identifying metadata |
| `records[].birthDate` | string or null |  |  |
| `records[].labels` | array of string |  |  |
| `records[].signals` | array of object |  |  |
| `records[].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.  |
| `records[].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.  |
| `records[].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?". One of: CATEGORY_DEFAULTS, CUSTOMER |
| `records[].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.  |
| `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.  |
| `records[].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.  |
| `records[].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. |
| `records[].created` | integer (int64) |  |  |
| `records[].createdBy` | string or null |  |  |
| `records[].updated` | integer (int64) or null |  |  |
| `records[].updatedBy` | string or null |  |  |
| `total` | integer |  |  |
| `limit` | integer |  |  |
| `skip` | integer |  |  |

**Example response (200)**

```json
{
  "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**

`GET https://api.caseprimus.ai/api/caseprimus/v1/parties/{id}`

**Request headers**

| Type | Name | Value | Optional |
| --- | --- | --- | --- |
| String | `X-CasePrimus-Api-Key` | Your API key | Required |

**Parameters**

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Required |  |

**Sample request**

```bash
BASE="https://api.caseprimus.ai/api/caseprimus/v1"

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

**Responses**

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

**Response fields (HTTP 200)**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `_id` | string |  |  |
| `number` | string or null |  |  |
| `name` | string |  |  |
| `entityType` | enum |  | One of: PERSON, BUSINESS |
| `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.  |
| `risk.score` | integer or null |  | 0-1000, higher is better. |
| `risk.scale` | integer |  |  |
| `risk.level` | enum or null |  | One of: VERY_HIGH, HIGH, MODERATE, LOW, MINIMAL |
| `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. One of: borrower.equipment, borrower.receivables, borrower.secured, borrower.unsecured, colender, collateral.provider, guarantor, trade.counterparty, agent, channel.partner, logistics, service.provider, vendor, acquisition.target, group.company, joint.venture, key.hire, professional, promoter, claimant, insured, insured.asset, provider.empanelment, provider.leakage, reinsurance, subrogation, landlord, tenant, government, opposing.party, own.entity, other.custom, lender, debt.assignee, platform.fintech, principal.brand, acquirer.parent, investor.fund, divesting.seller, insurer, broker.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. |
| `categories[].id` | string |  |  |
| `categories[].name` | string or null |  |  |
| `categories[].partyFamily` | string or null |  |  |
| `categories[].partyFamilyName` | string or null |  |  |
| `categories[].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 of: ONE_OFF, MONITOR |
| `status` | enum |  | One of: ACTIVE, ARCHIVED |
| `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. |
| `identifiers[].type` | enum or null |  | One of: CIN, PAN, GSTIN, UDYAM, OTHER,  |
| `identifiers[].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. |
| `addresses[].label` | string or null |  |  |
| `addresses[].line` | string or null |  |  |
| `addresses[].city` | string or null |  |  |
| `addresses[].district` | string or null |  |  |
| `addresses[].state` | string or null |  |  |
| `addresses[].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 |  |  |
| `signals[].signal` | string |  |  |
| `signals[].name` | string or null |  |  |
| `signals[].family` | string or null |  |  |
| `signals[].availability` | enum or null |  | One of: LIVE, PARTIAL, NOT_AVAILABLE |
| `signals[].kind` | enum or null |  | One of: CLASSIFICATION, DERIVED |
| `signals[].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.  |
| `scope.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. One of: PETITIONER, RESPONDENT, BOTH |
| `scope.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. One of: BASIC, ADVANCED |
| `scope.caseStatus` | enum |  | One of: ALL, PENDING, DISPOSED |
| `scope.fromYear` | integer or null |  |  |
| `scope.toYear` | integer or null |  |  |
| `scope.courtTypes` | array of enum |  | Which courts to go looking in. Empty means every court. OTHER covers tribunals, consumer commissions and anything unplaceable. One of: SC, HC, DC, OTHER |
| `scope.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 |
| `scope.sort` | enum |  | The default ordering for this party's findings. A findings view can still sort differently; this is what it opens on. One of: score_desc, filing_desc, filing_asc, order_adverse, order_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?". One of: CATEGORY_DEFAULTS, CUSTOMER |
| `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.  |
| `source.reportId` | string |  | The litigation report that assesses them. Always set - both modes begin with one. |
| `source.entityId` | string or null |  | The watchlist entity that keeps looking. Null unless `mode` is MONITOR. |
| `source.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. |
| `source.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.  |
| `decision.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.  One of: CLEAR, CONDITIONS, ESCALATE |
| `decision.note` | string or null |  | The reason up to 1000 characters |
| `decision.by` | string or null |  | The user who decided. Null for a decision taken with an API key rather than by a signed-in user. |
| `decision.at` | integer (int64) |  | When it was taken. |
| `decision.atScore` | integer or null |  | The reputation score at the time 0 to 1000 |
| `decision.atLevel` | enum or null |  | The litigation level at the time One of: VERY_HIGH, HIGH, MODERATE, LOW, MINIMAL, UNCLASSIFIED |
| `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.  |
| `decisionHistory[].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.  One of: CLEAR, CONDITIONS, ESCALATE |
| `decisionHistory[].note` | string or null |  | The reason up to 1000 characters |
| `decisionHistory[].by` | string or null |  | The user who decided. Null for a decision taken with an API key rather than by a signed-in user. |
| `decisionHistory[].at` | integer (int64) |  | When it was taken. |
| `decisionHistory[].atScore` | integer or null |  | The reputation score at the time 0 to 1000 |
| `decisionHistory[].atLevel` | enum or null |  | The litigation level at the time One of: VERY_HIGH, HIGH, MODERATE, LOW, MINIMAL, UNCLASSIFIED |
| `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. |
| `rerun.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.  |
| `rerun.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.  |
| `rerun.noReport` | boolean |  | No report is answering this party at all. A re-run is how it gets one. |
| `rerun.needsDiscovery` | boolean |  | A search input moved |
| `rerun.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.  |
| `rerun.tierRaised` | boolean |  | BASIC to ADVANCED. The carried cases have no order read to carry |
| `rerun.running` | object or null |  | The re-run in flight, if there is one. Null otherwise. |
| `rerun.lastFailure` | object or null |  | The last re-run failed - its discovery could not be collected. The change is pending again; start another. |
| `rerun.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.  |
| `rerun.answeringReportId` | string or null |  | The report the findings on screen actually came from. |
| `rerun.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 |  |  |

**Example response (200)**

```json
{
  "_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**

`GET https://api.caseprimus.ai/api/caseprimus/v1/parties/review-queue`

**Request headers**

| Type | Name | Value | Optional |
| --- | --- | --- | --- |
| String | `X-CasePrimus-Api-Key` | Your API key | Required |

**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**

```bash
BASE="https://api.caseprimus.ai/api/caseprimus/v1"

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

**Responses**

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

**Response fields (HTTP 200)**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `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. |
| `byParty[].partyId` | string |  |  |
| `byParty[].name` | string or null |  |  |
| `byParty[].count` | integer |  |  |
| `byParty[].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 |  |  |

**Example response (200)**

```json
{
  "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**

`GET https://api.caseprimus.ai/api/caseprimus/v1/parties/{id}/findings`

**Request headers**

| Type | Name | Value | Optional |
| --- | --- | --- | --- |
| String | `X-CasePrimus-Api-Key` | Your API key | Required |

**Parameters**

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Required |  |
| `$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**

```bash
BASE="https://api.caseprimus.ai/api/caseprimus/v1"

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

**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 | Type | Required | Description |
| --- | --- | --- | --- |
| `records` | array of object |  |  |
| `total` | integer |  |  |
| `counts` | object (free-form) |  |  |

**Example response (200)**

```json
{
  "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**

`POST https://api.caseprimus.ai/api/caseprimus/v1/parties/{id}/findings/{candidateId}/promote`

**Request headers**

| Type | Name | Value | Optional |
| --- | --- | --- | --- |
| String | `X-CasePrimus-Api-Key` | Your API key | Required |

**Parameters**

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Required |  |
| `candidateId` | path | Required |  |

**Sample request**

```bash
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**

- `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).

**Example response (200)**

```json
{
  "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**

`POST https://api.caseprimus.ai/api/caseprimus/v1/parties/{id}/findings/{candidateId}/decline`

**Request headers**

| Type | Name | Value | Optional |
| --- | --- | --- | --- |
| String | `X-CasePrimus-Api-Key` | Your API key | Required |

**Parameters**

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Required |  |
| `candidateId` | path | Required |  |

**Sample request**

```bash
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**

- `200`: The decision was recorded.
- `400`: No such party (61482), not monitored (61490), or no such candidate (60408).

**Example response (200)**

```json
{}
```

### 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**

`GET https://api.caseprimus.ai/api/caseprimus/v1/parties/{id}/changes`

**Request headers**

| Type | Name | Value | Optional |
| --- | --- | --- | --- |
| String | `X-CasePrimus-Api-Key` | Your API key | Required |

**Parameters**

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Required |  |
| `$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**

```bash
BASE="https://api.caseprimus.ai/api/caseprimus/v1"

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

**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 | Type | Required | Description |
| --- | --- | --- | --- |
| `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. |
| `batches[].kind` | enum |  | One of: CASES_FOUND, ORDERS_READ, MONITORING_BEGAN |
| `batches[].of` | string |  | The item kind this summarises |
| `batches[].count` | integer |  | How many there are in the whole window. |
| `batches[].at` | integer or null |  | When the newest of them happened. |
| `batches[].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 |  |  |

**Example response (200)**

```json
{
  "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

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

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

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