# Property Evidence Enrichment API

`POST https://civicdataforge.pages.dev/api/property-enrichment`

This endpoint compares another system's facts with the exact official and permit evidence already bound to a successful paid CivicDataForge property workspace. It preserves the caller's `property_id` and `provider_record_id`; it returns patches and checks instead of replacing the caller's database.

## Access and privacy

- Use the private checkout-session reference from a successful delivery. The session reference is not returned.
- Submit normalized facts only. Credential-shaped fields are rejected.
- Every record must match an exact `property_id` in that paid workspace.
- The request is processed ephemerally and the response states `persisted:false`.
- Do not put checkout references or customer records in URLs, analytics, prompts, tickets, or public logs.

## Field states

Input fields remain distinguishable as absent, null, empty, zero, or populated. A source-backed value can produce `MISSING_FIELD_RECOVERED`, `NULL_OR_EMPTY_RECOVERED`, `INCORRECT_ZERO_PREVENTED`, `STALE_VALUE_DETECTED`, or `VALUE_CONFLICT`.

Missing and null recovery patches are marked safe only after the caller rechecks the exact property ID. Conflicting or stale values require review. Unknown official fields never become zeros or patches.

## Receipts and verification

The response includes a receipt for every patch, record and batch. When production signing is enabled, remove the four transport fields (`batch_receipt_hash`, `signature_state`, `batch_signature`, and `verification_endpoint`) and post the remaining response as `payload` beside `signature` to `/api/property-enrichment-verify`. The verifier recomputes the receipt from the submitted payload before checking the server HMAC, so a changed value does not pass with an old signature.

## Benchmark meaning

The built-in counters measure exactly what this comparison emitted. `false_positive_rate` remains null unless a separate benchmark run receives independently adjudicated labels. Use `foundry/tools/benchmark-property-enrichment.mjs` for that labeled evaluation; do not relabel the gateway's own output as ground truth.

Contracts: [request schema](/schemas/property-enrichment-request-v1.schema.json), [response schema](/schemas/property-enrichment-response-v1.schema.json), [OpenAPI](/openapi/property-enrichment.openapi.json).