Send a lead

Each request creates (or reuses) a contact and opens a deal for the agent who receives the lead. The minimum valid body is a name, a phone and an email.

{
  "full_name": "John Doe",
  "phone": "8091234567",
  "email": "johndoe@email.com"
}

Assignment and duplicates

• Without related or round_robin, the lead goes to the owner of the API key.
• round_robin always wins over related.
• The contact belongs to whoever registered it. The deal belongs to whoever generated this lead.
• If the agency does not allow duplicates and the phone, email or WhatsApp username matches an existing contact, that contact is kept and is not reassigned. The generator’s deal with that contact is reused in any status (open, won, closed or lost, open first). The response is 200 with duplicate: true and deal_reused: true. If the generator has no deal with that contact, AlterEstate creates one and responds 201 with duplicate: true and deal_reused: false. Contact custom fields you send still update the existing contact.
• If the agency allows duplicates (Settings → Company configuration), each inquiry creates a new contact record and a new deal.
• Use duplicate to see whether the contact already existed. deal_reused is true when an existing deal was kept. Store log_id to trace the request with support.
• Agencies in prospect mode get the deal created as a prospect automatically.

Custom fields

List your company’s field keys first, then send the values in custom_fields. Formats, types and validation live on the Custom fields page.

• List custom fields

Free-form metadata

For attribution or debugging data you don’t want to model as a custom field, send metadata. It is saved as a timeline activity on the contact and deal, but it is not indexed or filterable.

{
  "full_name": "John Doe",
  "phone": "8091234567",
  "email": "johndoe@email.com",
  "metadata": {
    "landing_page": "https://example.com/june-promo",
    "user_agent": "Mozilla/5.0...",
    "session_id": "abc-123"
  }
}

Best practices

• Send any local phone format; AlterEstate normalizes it to E.164.
• Always send UTMs when you have them. They drive attribution reports.
• Send property_uid when the lead comes from a listing page so the deal is pre-filled.
• Use custom_fields for data you want to filter and report on; use metadata for raw payloads.
• With duplicates disabled, repeating a request reuses the generator’s deal when one exists and creates a deal only when that person has none.
• Call this endpoint from your server. Never expose the account token in browser code.

Status codes