API Reference

Review Flags

Submit data corrections and review flags for entities.

Controlled by data-flags:write

Any live API key with data-flags:write can submit and list review/data flags owned by that API user. Approval, rejection, and deletion are reserved for Hillwinds reviewers. Sandbox/test keys cannot manage flags.

Two paths, one resource

This resource is also reachable at /v1/data-flags — both paths return the same data. data-flags is the more accurate semantic; either path is supported indefinitely.

Body schema (write endpoints)

Write endpoints accept either the human-friendly alias or the canonical field name. Responses always return the canonical name.

Parameter	Type	Description
`entity_id`required	string	ID of the entity being flagged.
`entity_type`	string	One of: companies, personnel, broker-offices, brokers. Alias: resource.
`resource`	string	Alias of entity_type.
`entity_name`	string	Optional human label (e.g., company name) so reviewers can triage without resolving the ID.
`field_key`	string	The field being flagged (e.g., primary_broker). Alias: field.
`field`	string	Alias of field_key.
`reason`	string	Why the field is wrong. Alias: issue.
`issue`	string	Alias of reason.
`suggested_value`	string	Optional one-shot correction. Use corrections[] for multi-field or sourced suggestions.
`corrections`	object[]	Optional structured correction array. Each item: { field, current_value, suggested_value, source? }.

Submit Flag (simple)

POST/v1/review-flags0 credits

Single-field correction with a free-text reason. For multi-field or sourced corrections, use corrections[] (next section).

bash

curl -X POST -H "Authorization: Bearer ss_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "companies",
    "entity_id": "84629153",
    "field_key": "primary_broker",
    "reason": "Broker changed in Q1 2026 — record is stale",
    "suggested_value": "MARSH & MCLENNAN AGENCY"
  }' \
  "https://api.hillwinds.ai/v1/review-flags"

Submit Flag (structured corrections)

Use corrections[] to flag multiple fields at once, attach a source URL, or include the current value for context. Each correction: field, current_value, suggested_value, optional source.

bash

curl -X POST -H "Authorization: Bearer ss_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "companies",
    "entity_id": "84629153",
    "entity_name": "ACME HOLDINGS",
    "reason": "Two stale fields — verified against Q1 10-K",
    "corrections": [
      {
        "field": "primary_broker",
        "current_value": "AON",
        "suggested_value": "MARSH & MCLENNAN AGENCY",
        "source": "https://example.com/acme-q1-10k"
      },
      {
        "field": "total_number_of_employees",
        "current_value": "12000",
        "suggested_value": "15400"
      }
    ]
  }' \
  "https://api.hillwinds.ai/v1/review-flags"

Delete Flag (reviewers only)

DELETE/v1/review-flags/:flag_id0 credits

Customer API keys cannot delete submitted reviews. Hillwinds reviewers may delete a flag through an internal authenticated workflow when removal is required.

Approve or Reject Flags (reviewers only)

PATCH/v1/review-flags/:flag_id0 credits

Customer API keys cannot moderate submitted reviews. Hillwinds reviewers may send {"action":"approve"} or {"action":"reject"} through an internal authenticated workflow. Approved flags return status=resolved and an applied_at timestamp.

For up to 100 flags, send the same action with flag_ids to PATCH /v1/review-flags/bulk.

PreviousWriting Next API Keys

Need a key?

Keys are issued by our team, not a signup form. Book a 25-minute walkthrough and you'll leave with sandbox and live credentials.

Get access Explore the platform