Buyer Desk API

Endpoints to create and manage buyer briefs and their compliance gates (bilateral marketplace, Side B). Authenticate with Authorization: Bearer <jwt>. See the Buyer Desk guide.

Create brief


POST /api/dashboard/buyer/briefs
Authorization: Bearer <agent-jwt>
Content-Type: application/json
 
{
  "buyerName": "María García",
  "buyerContact": "maria@example.com",
  "jurisdiction": "MX",
  "zoneQuery": "CDMX Polanco",
  "goal": {
    "kind": "first_home",
    "currency": "USD",
    "availableCash": 150000,
    "maxMonthlyPayment": 3500,
    "horizonYears": 3
  }
}

Request body:

Field	Type	Required	Description
`buyerName`	string	✓	Buyer’s name
`buyerContact`	string	✓	Email or phone
`jurisdiction`	string	✓	`LATAM` (per country, e.g. `MX`) · `CA-ON` · `US` · `AE`
`zoneQuery`	string		Target zone (e.g. “CDMX Polanco”)
`goal.kind`	`first_home\|rental_income`	✓	Goal type
`goal.currency`	string	✓	Goal currency
`goal.availableCash`	number	✓	Available cash
`goal.maxMonthlyPayment`	number		Max monthly payment (first_home)
`goal.horizonYears`	number		Horizon in years

Response:


{
  "id": "brief_abc123",
  "status": "active",
  "targetProfile": { "priceMin": 850000, "priceMax": 1050000, "currency": "MXN" },
  "complianceChecks": [
    { "type": "aml_kyc", "status": "pending", "jurisdiction": "MX" }
  ]
}

Errors:

Status	Error	Cause
422	`unsupported_jurisdiction`	Jurisdiction not supported (LATAM, CA-ON, US, AE)
422	`invalid_goal`	Impossible goal (down payment > available cash)
403	`not_an_agent`	Caller is not an agent role

Get brief


GET /api/dashboard/buyer/briefs/{id}
Authorization: Bearer <jwt>

Returns the brief with its status, targetProfile, candidates, and gate states.

Verify compliance gate

Brokers only. Fail-closed: the brief stays blocked_compliance until all of its jurisdiction’s gates are verified.


PATCH /api/dashboard/buyer/briefs/{id}/compliance
Authorization: Bearer <broker-jwt>
Content-Type: application/json
 
{ "type": "aml_kyc", "status": "verified" }

Response:


{
  "ok": true,
  "allVerified": true,
  "retriggered": true
}

allVerified — all of the brief’s gates are verified.
retriggered — the brief returned to active and matching was re-triggered.

Errors:

Status	Error	Cause
403	`forbidden`	Caller is not a broker
404	`not_found`	Brief or gate does not exist
409	`already_verified`	Gate was already verified

Per-jurisdiction gates (aml_kyc, fintrac, bra, state_license, fincen_aml, firpta, rera_registration, freehold_eligibility, uae_aml, …) are documented in Compliance Gates.