Directory and leads

Sync a client database, a lender database, or a lead system into Appraiser Flow. Organizations show under Clients. Leads show under CRM.

Create the key first: Connect a System. A worked nightly job, including the column map, is the CRM sync recipe.

Scopes:

Scope	Use
organizations:read	List and fetch organizations
organizations:write	Create and update organizations and contacts
leads:read	List and fetch leads
leads:write	Create and update leads

client_type is lender, amc, private_party, or other. Lenders and AMCs are both organizations. A lender database and a client database use the same endpoint.

Upsert an organization

POST /public/v1/organizations requires Idempotency-Key. Sending the same external_reference again updates the existing organization.

Match order:

1. external_reference (the id in your CRM or database)
2. account_number, when that number matches exactly one organization
3. Exact organization name

Lenders may omit phone, email, website, and address. Other organization types need phone, email, website, and a street address, the same rule as the staff directory.

curl -sS "$AF_API/public/v1/organizations" \
  -H "Authorization: Bearer $AF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "external_reference": "sf-001xx",
    "external_source": "salesforce",
    "name": "Acme Mortgage",
    "client_type": "lender",
    "email": "orders@acme.example",
    "phone": "(615) 555-0100",
    "contacts": [
      {
        "external_reference": "sf-contact-9",
        "display_name": "Pat Lee",
        "email": "pat@acme.example",
        "phone": "(615) 555-0199",
        "contact_type": "order_assigner",
        "is_primary": true
      }
    ]
  }'

action is created or updated. Phones are stored as (XXX) XXX-XXXX. Contacts match on external_reference, then email. Contacts omitted from a later call are left in place.

Batch up to 100 organizations. Give the batch its own Idempotency-Key.

curl -sS "$AF_API/public/v1/organizations/batch" \
  -H "Authorization: Bearer $AF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "items": [
      {
        "external_reference": "sf-001",
        "external_source": "salesforce",
        "name": "Acme Mortgage",
        "client_type": "lender"
      },
      {
        "external_reference": "sf-002",
        "name": "Northgate AMC",
        "client_type": "amc",
        "phone": "(615) 555-0140",
        "email": "orders@northgate.example",
        "website": "https://northgate.example",
        "address_line1": "10 Commerce St",
        "city": "Nashville",
        "state": "TN",
        "postal_code": "37203"
      }
    ]
  }'

Each item returns created, updated, or error. One row that fails a business rule does not roll back the others. A schema error, such as a phone that is not 10 digits, fails the whole request before any row is saved. Validate phones and client_type before you send the batch.

Update one field later with PATCH /public/v1/organizations/{id}. Patch does not need an idempotency key.

Read:

GET /public/v1/organizations?client_type=lender&q=Acme
GET /public/v1/organizations/by-reference?external_reference=sf-001xx
GET /public/v1/organizations/{id}

Leads

A lead is a CRM opportunity. amount_cents is the expected engagement fee in cents. It is not a property value.

Provide exactly one organization locator: organization_id, organization_external_reference, or a nested organization. The nested object upserts the directory and also requires organizations:write.

curl -sS "$AF_API/public/v1/leads" \
  -H "Authorization: Bearer $AF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "external_reference": "hs-8841",
    "external_source": "hubspot",
    "title": "Acme purchase panel",
    "stage": "lead",
    "amount_cents": 45000,
    "organization_external_reference": "sf-001xx"
  }'

Stages: lead, qualified, proposal, won, lost.

POST /public/v1/leads/batch
GET /public/v1/leads?stage=lead
PATCH /public/v1/leads/{id}

Compliance

Notes that mention an estimated value, AVM, assessed value, or similar are dropped before save. Responses never include an appraisal value. This API does not email or text anyone.

Webhook events organization.upserted and lead.upserted carry ids and the action only. Fetch the record if you need the full directory fields.