Appearance
POST /public/v1/leads
| Auth | Required |
| Scope | leads:write |
| Idempotency-Key | Required |
Creates or updates a CRM lead. Staff see it under CRM on the stage you send.
The same external_reference updates the existing lead. amount_cents is the expected engagement fee in cents, not a property value. Value language in notes is removed.
Point at one organization
Send exactly one of:
| Field | When |
|---|---|
organization_external_reference | You already synced the company and stored its source id |
organization_id | You stored the Appraiser Flow uuid |
organization | The company should be created or updated in this same call |
A nested organization uses the organization upsert body and also requires organizations:write. Without that scope the lead call returns 403 / insufficient_scope and writes nothing.
Request
json
{
"external_reference": "deal-4421",
"external_source": "hubspot",
"title": "Acme — 123 Main St",
"stage": "qualified",
"amount_cents": 55000,
"organization_external_reference": "sf-001"
}stage is lead (default), qualified, proposal, won, or lost.
Response fields
| Field | Type |
|---|---|
id | uuid |
action | created or updated |
external_reference, external_source | string or null |
title | string |
stage | string |
amount_cents | int or null |
notes | string or null |
organization_id | uuid |
organization_name | string or null |
organization_external_reference | string or null |
created_at, updated_at | datetime |
Webhook: lead.upserted (id, external reference, stage, 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.
Errors
| Status | Code | When |
|---|---|---|
| 400 | idempotency_key_required | Header missing |
| 409 | idempotency_conflict | Same key, different body |
| 403 | insufficient_scope | Missing leads:write, or nested organization without organizations:write |
| 404 | not_found | organization_id or organization_external_reference does not match a company in this account |
| 422 | validation_error | Not exactly one organization locator, or the nested organization is incomplete |