Reports

Reports are regulatory filings about transfers. The only kind today is suspicion: a suspicious transaction or activity report (an STR, SAR or SMR, depending on the jurisdiction). Through the API you read report types, list and read reports, and download them. Drafting, editing, submitting and filing reports happen in the dashboard.

Access

Every report endpoint needs the reports:read and strs:read scopes, and the key's owner's role needs the reports:view and strs:view permissions: a suspicion report falls under tipping-off rules. A key without strs:read is refused with 403 INSUFFICIENT_PERMISSION.

A role without pii:view (an analyst) reads reports with the narrative, each risk indicator, and the regulatory fields about the subject masked as ***, and meta.piiMasked: true. It cannot download a report, since the file holds it in full.

Endpoints

Method	Endpoint	Scope	Description
GET	/api/v2/report-types	reports:read, strs:read	Report types by kind and jurisdiction
GET	/api/v2/reports	reports:read, strs:read	List reports
GET	/api/v2/reports/:id	reports:read, strs:read	Get a report
GET	/api/v2/reports/:id/download	reports:read, strs:read, transfers:read	Download a report as a PDF

Jurisdictions are ISO 3166-1 alpha-2 codes, stored and returned in upper case. A jurisdiction parameter takes a code in any case, and UK for GB. EU is not a jurisdiction: each EU member state has its own code.

Report Types

What each jurisdiction's report is called, where it is filed, the fields it holds, and the formats it downloads in: build forms and filters from it rather than encoding each regulator yourself.

curl "$COVALENT_URL/api/v2/report-types?jurisdiction=us" \
  -H "x-api-key: $COVALENT_API_KEY"

Parameter	Description
kind	suspicion.
jurisdiction	One jurisdiction's type.

{
  "data": [
    {
      "kind": "suspicion",
      "jurisdiction": "US",
      "label": "SAR (Suspicious Activity Report)",
      "reportTo": "FinCEN",
      "fields": [
        { "key": "subjectName", "label": "Subject Name", "type": "text", "pii": true }
      ],
      "narrative": { "required": true, "minLength": 50 },
      "formats": ["pdf"],
      "filingDeadline": {
        "days": 30,
        "source": "system_default",
        "regulation": null,
        "regulatoryBody": null
      }
    }
  ],
  "meta": {
    "apiVersion": 2,
    "timestamp": "2026-10-09T12:00:00.000Z"
  }
}

A field with pii: true is about the subject, and is masked for a role without pii:view. filingDeadline is your company's: from its jurisdiction thresholds (source: "threshold"), else the system default (source: "system_default").

List Reports

curl "$COVALENT_URL/api/v2/reports?status=draft&jurisdiction=us" \
  -H "x-api-key: $COVALENT_API_KEY"

Parameter	Description
kind	suspicion.
status	draft, pending_review, submitted or filed.
jurisdiction	One jurisdiction's reports.
transferId	The reports about one transfer.
search	Part of the report number, the transfer ID or the filing reference, any case, at most 100 characters.
from, to	Created at or after, and before: a day (2026-10-09, from its start in UTC) or an ISO 8601 instant with its offset.
limit	Items per page, 1 to 200, default 50.
cursor	meta.cursor of the previous page.

Any other parameter or value is 400 INVALID_QUERY. Reports are listed newest first, without their narrative or subject details:

{
  "id": "report_id",
  "kind": "suspicion",
  "label": "SAR (Suspicious Activity Report)",
  "reportTo": "FinCEN",
  "reportNumber": "STR-20261009-00001",
  "transferId": "transfer_id",
  "status": "draft",
  "jurisdiction": "US",
  "detectionMethod": "manual_review",
  "generatedBy": "user_id",
  "generatedAt": "2026-10-09T10:00:00.000Z",
  "filedAt": null,
  "filedBy": null,
  "filingReference": null,
  "filingReady": false,
  "filingDeadline": {
    "deadline": "2026-11-08T10:00:00.000Z",
    "daysRemaining": 30,
    "isOverdue": false,
    "isApproaching": false,
    "source": "system_default",
    "daysConfigured": 30,
    "regulation": null,
    "regulatoryBody": null
  },
  "createdAt": "2026-10-09T10:00:00.000Z",
  "updatedAt": "2026-10-09T10:00:00.000Z",
  "generatedByMember": { "id": "user_id", "name": "Jordan Lee", "email": "jordan@example.com" },
  "filedByMember": null
}

Field	Description
label, reportTo	What the report is called in its jurisdiction, and where it is filed. reportTo is null for a jurisdiction without a report type of its own.
generatedBy	system, or the ID of the member who drafted it. generatedByMember names them, or is null.
filedBy	The member who submitted it. filedByMember names them, or is null.
filingReady	Whether its regulatory data is complete enough to file. A PDF of a report that is not ready is marked DRAFT.
filingDeadline	When it is due, and whether it is overdue or the deadline is approaching. A filed report is never overdue.

Get Report

curl "$COVALENT_URL/api/v2/reports/report_id" \
  -H "x-api-key: $COVALENT_API_KEY"

The answer is the report as listed, plus:

Field	Description
narrative	The narrative, or null. *** for a role without pii:view.
riskIndicators	The risk indicators. Each is *** for a role without pii:view.
regulatoryData	The jurisdiction's regulatory fields, decrypted. For a role without pii:view, the fields about the subject are ***; the others, such as the filing institution, are shown.

A report of the other environment is 404 REPORT_NOT_FOUND.

Download Report

curl "$COVALENT_URL/api/v2/reports/report_id/download?format=pdf" \
  -H "x-api-key: $COVALENT_API_KEY" \
  -o report.pdf

format is pdf, the default and the only format today; GET /api/v2/report-types lists each type's formats. The download also needs the transfers:read scope (the file shows the report's transfer), and a role with pii:view.

A successful download is the file itself, not JSON:

Header	Value
Content-Type	application/pdf
Content-Length	The file's size in bytes.
Content-Disposition	attachment; filename="STR-20261009-00001.pdf", or ..._DRAFT.pdf for a report that is not ready to file.
x-content-sha256	The file's SHA-256, in hex. The download's audit log entry records the same hash.
api-version	2
cache-control	no-store

Every download is recorded in the audit log (entity TransactionReport, action str.downloaded) before the file is sent. HEAD is 405 METHOD_NOT_ALLOWED: it would record a download and send nothing.

A failure is the usual JSON envelope:

Status	Code	When
400	INVALID_QUERY	A format other than pdf, or another parameter.
403	INSUFFICIENT_PERMISSION	The key lacks strs:read or transfers:read, or its owner's role a matching permission.
403	PII_ACCESS_REQUIRED	The key's owner's role lacks pii:view. GET /api/v2/reports/:id shows the report masked.
404	REPORT_NOT_FOUND	No such report in the key's environment.
409	TRANSFER_NOT_FOUND	The report's transfer is not in the key's environment.
422	REPORT_TOO_LONG_FOR_PDF	The report's text is over 100,000 characters, more than its PDF draws. GET /api/v2/reports/:id has it in full.
503	PDF_RENDERER_BUSY	Another report with Chinese, Japanese or Korean text is being drawn. Retry-After: 5.