POST/watchlist/entities/{id}/candidates/search

Search discovered case candidates for an entity

Customer's own view of court-case candidates found against this company.

Overview

Customer's own view of court-case candidates found against this company. tab is required: - historical: candidates the customer can decide on directly, no CasePrimus review needed (one-time fetchHistoricalCases results, plus any daily-discovery candidate the customer already declined). - pendingReview: daily-discovery candidates CasePrimus has approved, awaiting the customer's decision. Cases already added to the watchlist are not a candidates tab at all - list those via POST /watchlist/cases/search instead.

Auth API keyContent-Type application/json

Send your API key in the X-CasePrimus-Api-Key header. See Authentication for how to create a key, and Rate limits & errors for how requests are counted.

Parameters

Name	In	Description
`id` string Required	path	The id returned when the resource was created.

Request body

Field	Description
`$filter` object (free-form) Optional	Exact-match field filters, e.g. {"status": "ACTIVE"}.
`$like` object (free-form) Optional	Case-insensitive substring filters, e.g. {"name": "trip"}.
`$skip` integer Optional	minimum 0
`$sort` object (free-form) Optional	Field to +1/-1 (ascending/descending), e.g. {"created": -1}.
`$limit` integer Optional	0 to 100
`tab` enum Required	`historicalpendingReview`

Body: Success

{
  "tab": "pendingReview",
  "$skip": 0,
  "$limit": 10
}

Example request

Replace CASEPRIMUS_API_KEY with your key.

Request

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

curl -X POST "$BASE/watchlist/entities/ENTITY_ID/candidates/search" \
  -H "X-CasePrimus-Api-Key: $CASEPRIMUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tab": "pendingReview",
    "$skip": 0,
    "$limit": 10
  }'

const BASE = "https://api.caseprimus.ai/api/caseprimus/v1";

const res = await fetch(BASE + "/watchlist/entities/ENTITY_ID/candidates/search", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-CasePrimus-Api-Key": process.env.CASEPRIMUS_API_KEY,
  },
  body: JSON.stringify({
    "tab": "pendingReview",
    "$skip": 0,
    "$limit": 10
  }),
});

const data = await res.json();

import os
import requests

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

res = requests.request(
    "POST",
    BASE + "/watchlist/entities/ENTITY_ID/candidates/search",
    headers={"X-CasePrimus-Api-Key": os.environ["CASEPRIMUS_API_KEY"]},
    json={
        "tab": "pendingReview",
        "$skip": 0,
        "$limit": 10,
    },
)

data = res.json()

Responses

200Matching candidates.

Field	Description
`recordsFiltered` integer
`records` array of object
`_id` string
`number` integer
`accountId` string
`watchlistEntityId` string
`rawMatch` object (free-form)	The discovered court record as found (shape varies by data source), plus, if a possible duplicate was seen but not auto-merged, possibleMatchConflict. Does not include which underlying provider(s) found it - that's stripped before this response is built.
`caseIdentifier` object
`status` enum	CasePrimus's data-quality check - is this a real, usable match at all. `PENDING_REVIEWAPPROVEDREJECTEDPROMOTED`
`discoveryMode` enum	HISTORICAL candidates skip the CasePrimus check entirely - the customer decides directly. `HISTORICALONGOING`
`customerDecision` enum or null	null means not yet decided by the customer. `ADDEDDECLINED`
`promotedCaseId` string or null
`created` integer (int64)
`updated` integer (int64) or null

Response 200

{
  "recordsFiltered": 1,
  "records": [
    {
      "_id": "CPWLCC0exampledemo0001",
      "number": 400001,
      "accountId": "CPA0exampledemo0001",
      "watchlistEntityId": "CPWLE0exampledemo0001",
      "rawMatch": {
        "court": "District Court, Delhi",
        "parties": {
          "respondent": "Jane Doe"
        }
      },
      "caseIdentifier": {
        "courtType": "DC",
        "cnr": "DLCT010098762024"
      },
      "status": "APPROVED",
      "discoveryMode": "ONGOING",
      "customerDecision": null,
      "promotedCaseId": null,
      "created": 1757550000000,
      "updated": null
    }
  ]
}

400Entity does not exist, or missing/invalid tab.

Response 400

{
  "httpStatusCode": 400,
  "code": 60001,
  "message": "Malformed data or missing required parameter values",
  "appError": true
}

403This entity has not been shared with you.

Error responses share one shape, listed on Rate limits & errors.