# CivicDataForge integration recipes

Use a scoped Apify token in a secret store. Validate all responses, preserve evidence semantics, and never turn a no-match, source failure, incomplete scope, or review candidate into affirmative clearance.

## REST

`POST https://api.apify.com/v2/acts/civicdataforge~civicdataforge-evidence-gateway/run-sync-get-dataset-items?timeout=120`

Send `Authorization: Bearer $APIFY_TOKEN` and a supported task payload. For the U.S. property task, use `{"task":"us_property_decision","subject":{"address":"100 Sample St, Sampleton, ZZ","city":"Sampleton","state":"ZZ"},"purpose":"property compliance research","retentionDays":0,"transactionGate":true}`. Treat non-2xx responses as unresolved and retain the emitted receipt and decision state.

## Remote MCP

Connect to `https://civicdataforge.pages.dev/mcp` with the caller-owned token in `X-Apify-Token`. See [Connect an AI agent](https://civicdataforge.pages.dev/connect-agent).

## Webhook

Configure an Apify run webhook to your HTTPS endpoint. Verify a shared secret, acknowledge quickly, queue work, and deduplicate using the Actor run ID plus event type because deliveries can be retried.

## Dataset exports

`GET https://api.apify.com/v2/datasets/$DATASET_ID/items?format=jsonl&clean=true`

Apify datasets support JSON, JSONL, CSV, XML, Excel, HTML, and RSS exports. Prefer a named dataset when durable storage is required and apply your own retention policy.

## Hospitable Connect property import

Start at [Connect a Hospitable account](https://civicdataforge.pages.dev/connect-host). The property owner authorizes access through Hospitable, chooses properties, and transfers the selected addresses into the permit-audit intake for review. No Hospitable password or access token is pasted into CivicDataForge, and connecting an account does not start a purchase.

## Hostex read-only property import

Open the [Permit Audit](https://civicdataforge.pages.dev/permit-audit) and expand **Import from Hostex with your own read-only token**. The caller-owned token is sent over HTTPS only for the import request, is not placed in the URL or analytics, is not persisted or echoed by the service, and is cleared from the page after the request. Select 1-25 addresses and review the supported jurisdiction before checkout.

## Scoped adapters

A new source, SFTP route, platform-native app, or private connector is scoped, implemented, and acceptance-tested before it is represented as live. Email [bryan@steellantern.com](https://mail.google.com/mail/?view=cm&fs=1&to=bryan%40steellantern.com&su=CivicDataForge%20integration%20adapter) with the system, identifier, cadence, delivery route, and downstream workflow.