Proposed corrections

Submit a sourced correction for human review. The API does not directly change research or published data. Create a key with corrections:submit; add corrections:read-own if the integration will monitor its submissions.

Submit a proposal

POST /api/v1/corrections accepts a JSON body up to 16 KB. Include a stable Idempotency-Key of 16–128 letters, digits, dots, underscores, colons or hyphens. Create it once for the proposal and retain it until the outcome is known.

Example proposal.json (replace illustrative values with actual record identity and evidence):

{
  "dataset": "organizations",
  "record_id": "OPAQUE_ID_FROM_ORGANIZATION_LIST",
  "explanation": "The official organization page reports a different legal name.",
  "sources": ["https://example.com/official-source"],
  "proposed_value": {"legal_name": "Example Legal Name"}
}

curl --fail-with-body 'https://app.defdex.io/api/v1/corrections' \
  --header "Authorization: Bearer $DEFDEX_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example-correction-request-001' \
  --data-binary @proposal.json

Use a unique key for each distinct proposal, rather than reusing the example globally.

Fields ending _usd require decimal strings. Submission validation is not proof that the record exists or the proposed correction is correct; reviewers verify identity, field meaning and evidence.

Handle the receipt and retries

New proposals return 201 with the proposal object, including id, status, submitted content and timestamps. There is no data wrapper on an individual receipt. An equivalent normalized proposal retried by the same account with the same key returns the original receipt with 200. Different content under that key returns 409. Every admitted replay still counts toward request usage.

An account may have up to 100 open proposals (submitted/in_review) and 50 submissions per rolling day. A storage-cap 429 may have no Retry-After; waiting 60 seconds does not necessarily clear it. The shared API request limit also applies.

Read review status

These reads require corrections:read-own. List pages have data and next_cursor, and are ordered by proposal ID, not submission time. Individual reads return the proposal directly. Other accounts’ IDs return 404.

Statuses are submitted, in_review, accepted, rejected and published. reviewer_note carries the user-visible review note when available. Acceptance and publication are separate; publication follows the normal audited data build.