POST /public/v1/organizations

Auth	Required
Scope	organizations:write
Idempotency-Key	Required

Creates a client, lender, AMC, or other organization, or updates the one that already matches. Staff see the record under Clients.

Send external_reference from your database on every run. That id is how later calls update the same company after the idempotency key expires.

Match order

1. external_reference
2. account_number, when exactly one organization has that number
3. Exact name

A name or account number already tied to a different external_reference returns 409. The office record is left unchanged.

Request

{
  "external_reference": "sf-001",
  "external_source": "salesforce",
  "name": "Acme Mortgage",
  "client_type": "lender",
  "phone": "(615) 555-0100",
  "email": "orders@acme.example",
  "account_number": "ACME-100",
  "contacts": [
    {
      "external_reference": "sf-contact-9",
      "display_name": "Jordan Lee",
      "email": "jordan@acme.example",
      "phone": "(615) 555-0101",
      "contact_type": "order_assigner",
      "is_primary": true
    }
  ]
}

client_type is lender, amc, private_party, or other.

Lenders may omit phone, email, website, and address. Every other type needs phone, email, website, address_line1, city, state (two letters), and postal_code.

Phones are 10-digit US numbers and are stored as (615) 555-0100.

Contacts are optional, up to 25. Each contact needs display_name, email, and contact_type (order_assigner, account_manager, billing, or other). other also needs other_label. One contact may be is_primary. Contacts you leave out of the array are not deleted. A contact matches external_reference, then email.

Phrases that state an appraisal value are removed from notes.

Response fields

Field	Type
id	uuid
action	created or updated
external_reference	string or null
external_source	string or null
name	string
client_type	string
phone, email, website	string or null
address_line1, address_line2, city, state, postal_code	string or null
account_number, amc_license_number	string or null
notes	string or null
is_active, paid_when_paid	bool
contacts	array of contact records, each with id
created_at, updated_at	datetime

Webhook after commit: organization.upserted (id, external reference, type, and action only).

Try It

Try It calls https://staging-api.appraiserflow.ai/public/v1 with an af_test_ key. The key stays in sessionStorage. af_live_ keys are blocked. Live server calls use https://api.appraiserflow.ai/public/v1 with an af_live_ key kept on your server.

API Key (af_test_…)JSON Body{"external_reference":"sf-001","external_source":"salesforce","name":"Acme Mortgage","client_type":"lender","phone":"(615) 555-0100","email":"orders@acme.example"}

Errors

Status	Code	When
400	idempotency_key_required	Header missing
409	idempotency_conflict	Same key, different body
403	insufficient_scope	Key lacks organizations:write
409	name_conflict	Name is already linked to another external id
409	ambiguous_match	Account number matches more than one organization
409	external_reference_conflict	Account number is linked to another external id
409	contact_conflict	Contact email is linked to another external id
422	validation_error	Missing required fields, bad phone, or bad email