Connect a System

Use this when you are wiring a website, a client or lender database, or a lead tool to Appraiser Flow. The key never belongs in a browser, a mobile app, or a public repository.

Where keys live

A company admin opens Settings → Public API.

1. Name the key after the system (Salesforce nightly, Website quotes).
2. Choose Test until the mapping is right. Test keys start with af_test_. Production keys start with af_live_.
3. Check only the scopes that system needs. See the table below.
4. Create the key and copy the secret. It is shown once.
5. Put it in the server environment, Zapier’s secret store, or your host’s secret manager.

export AF_API="https://staging-api.appraiserflow.ai"
export AF_API_KEY="af_test_••••"

Environment	AF_API	Key
Local API	http://localhost:8000	af_test_
Staging	https://staging-api.appraiserflow.ai	af_test_
Production	https://api.appraiserflow.ai	af_live_

Copy API Base URL on that page already ends in /public/v1. The AF_API host in the table does not. Append /public/v1 to the host, or call the copied base directly. Do not append the path twice.

Pick scopes for the connection

Connection	Scopes
Marketing site that requests a quote	products:read, fees:read, quotes:write, quotes:read, files:write
Client or lender database	organizations:read, organizations:write
Lead tool that also creates the company	organizations:read, organizations:write, leads:read, leads:write
Lead tool that only attaches to companies already synced	leads:read, leads:write
Status lookup for a lender portal	orders:read
Your server receives callbacks	Register the webhook in Settings → Public API. webhooks:manage is only needed if the server registers endpoints itself

One key can hold several of these. A second key is better when a vendor should not see orders or quotes.

Prove the key

curl -sS "$AF_API/public/v1/me" \
  -H "Authorization: Bearer $AF_API_KEY"

A working key returns the company name, the key name, and the scopes you granted. 401 means the secret is missing, revoked, or the wrong environment (af_live_ on staging, or af_test_ on production). 403 on a later call means the key is valid and the scope is missing.

Receive events

Still on Settings → Public API, add a webhook:

1. HTTPS URL on your server. Local HTTP is rejected outside local development.
2. Select the events you handle. Directory sync uses organization.upserted and lead.upserted. Quote sites use quote.created and quote.updated.
3. Copy the signing secret once.
4. Send a test delivery and confirm Recent Deliveries shows a success.

Verify X-AF-Signature before you trust the body. The recipe is in Webhooks. Directory and lead payloads contain ids and action only. Call the GET endpoint if you need the full record.

First successful write

Website quote: Get Started and Quotes.

Client or lender database, or a lead system: Directory and leads and the CRM sync recipe.

Every POST that creates or upserts needs Idempotency-Key. For a database sync, also send a stable external_reference from the source system. That id is what updates the same organization on the next run. The idempotency key only protects a single HTTP retry for about 72 hours.

Confirm it in the office

You sent	Staff see it
Organization	Clients. Open the record. External Reference and External Source show when the sync set them.
Lead	CRM, on the stage you sent (lead, qualified, proposal, won, lost).
Quote	Open Quotes, with your external_reference.
Order read	No new record. You are reading an order the office already has.

Go live

1. Create a second key with environment Live and the same scopes.
2. Point production at https://api.appraiserflow.ai and the af_live_ secret.
3. Revoke the test key only if that environment should stop. Revoke is immediate.

To rotate a live key, create the new secret, deploy it, then revoke the old key.

Rules for every connection

• Keep the key on a server you control.
• Phones are 10-digit US numbers. The API stores them as (615) 555-0100.
• Do not send appraisal values, AVMs, or assessed values. Those phrases are removed from notes, and quote responses never include them.
• This API does not email or text the client. Staff still send quotes from Appraiser Flow.