Skip to content
Trace API & MCP Docs

Data flags API

Use data flags when your integration finds company data that looks wrong, outdated, incomplete, or mismatched. A flag sends the company to Trace’s data-quality review queue. It does not directly change the company record or its detected technologies, firmographics, domains, or partnerships.

All requests require an API key in the X-API-Key header. The path accepts the same company identifier format as the rest of the Companies API: a domain (stripe.com) or a Trace slug (stripe).

Create a flag

Section titled “Create a flag”
POST /v1/companies/{identifier}/flags

The request body is optional. Send description when you can explain what looks wrong or what evidence Trace should review.

Field Type Description
description string, optional Review note, up to 2000 characters. Blank strings are treated as omitted.
Flag company data
curl -X POST "https://api.tracedata.ai/v1/companies/stripe.com/flags" \
  -H "X-API-Key: $TRACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "The listed primary domain appears to be outdated."}'

Successful calls return 201 Created with the queued flag.

201 response
{
  "flag_id": 900,
  "company_id": 123,
  "status": "queued"
}

status is queued because the flag enters Trace’s data-quality review queue. Trace reviews and applies any needed data fixes through that process.

Missing companies

Section titled “Missing companies”

If {identifier} does not resolve to a tracked company, the endpoint returns 404 company_not_found and no flag is created.

404 response
{
  "detail": {
    "error": "company_not_found",
    "message": "No company was found for that identifier.",
    "identifier": "missing.example"
  }
}

See also

Section titled “See also”