POST/watchlist/entities

Add entity to watchlist

Adds a company or person to the account's watchlist.

Overview

Adds a company or person to the account's watchlist. For a BUSINESS entity, this also generates AI name variations to search for (best-effort, it never blocks the response) and, if fetchHistoricalCases is true, starts a one-time historical court-case lookup across our verification data partners. The lookup runs in the background: results arrive later as candidates, readable through POST /watchlist/entities/{id}/candidates/search, not in this response. Requires watchlist.write.

Auth API keyPermission watchlist.writeContent-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.

Request body

Field	Description
`name` string Required	2 to 255 characters
`entityType` enum Required	`PERSONBUSINESS`
`fatherName` string or null Optional	PERSON entities only - ignored for BUSINESS. up to 256 characters
`birthDate` string or null Optional	DD-MM-YYYY. PERSON entities only - ignored for BUSINESS.
`location` string or null Optional	Free-text address. up to 4192 characters
`registrationNumber` string or null Optional	up to 50 characters
`monitoredCourts` array of enum Optional	'ALL' must be the sole entry if used - cannot combine with specific court codes. Recorded with the entity. Monitoring is not currently restricted by this value. at least 1 item `ALLDCSCHCCCNCLTNCLATGSTATDRTDRATCESTAT`
`sharedWith` array of object Optional
`type` enum Required	`teamuser`
`id` string Required	A team ID when type is 'team', a user ID otherwise.
`fetchHistoricalCases` boolean Optional	One-time historical case lookup, fired asynchronously right after creation. BUSINESS entities only - silently a no-op for PERSON.

Body: Success

{
  "name": "Acme Traders Pvt Ltd",
  "entityType": "BUSINESS",
  "monitoredCourts": [
    "ALL"
  ],
  "fetchHistoricalCases": false
}

Example request

Replace CASEPRIMUS_API_KEY with your key.

Request

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

curl -X POST "$BASE/watchlist/entities" \
  -H "X-CasePrimus-Api-Key: $CASEPRIMUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Traders Pvt Ltd",
    "entityType": "BUSINESS",
    "monitoredCourts": [
      "ALL"
    ],
    "fetchHistoricalCases": false
  }'

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

const res = await fetch(BASE + "/watchlist/entities", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-CasePrimus-Api-Key": process.env.CASEPRIMUS_API_KEY,
  },
  body: JSON.stringify({
    "name": "Acme Traders Pvt Ltd",
    "entityType": "BUSINESS",
    "monitoredCourts": [
      "ALL"
    ],
    "fetchHistoricalCases": false
  }),
});

const data = await res.json();

import os
import requests

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

res = requests.request(
    "POST",
    BASE + "/watchlist/entities",
    headers={"X-CasePrimus-Api-Key": os.environ["CASEPRIMUS_API_KEY"]},
    json={
        "name": "Acme Traders Pvt Ltd",
        "entityType": "BUSINESS",
        "monitoredCourts": ["ALL"],
        "fetchHistoricalCases": False,
    },
)

data = res.json()

Responses

200Entity created.

Field	Description
`_id` string

Response 200

{
  "_id": "CPWLE0exampledemo0001"
}

400Malformed input.

Response 400

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

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

401Missing/invalid/expired access token.

403Caller lacks the watchlist.write permission.

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

Add entity to watchlist

Overview

Request body

Example request

Responses

Related