orkasa
ESEntrar

Guides

Lead to viewing

The whole path with real calls: create the lead, read its operation, book the viewing.

export ORKASA_KEY="ork_live_…"
export ORKASA_API="https://orkasa.app/api/v1"

1. Create the lead

One call does what the app does: find-or-create the contact (matched on normalized phone and email), insert the lead, round-robin an agent, open the operation, and fire the sanctions screen.

curl -X POST "$ORKASA_API/leads" \
  -H "Authorization: Bearer $ORKASA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "Ana Torrijos",
    "phone": "+507 6123 4567",
    "email": "ana.torrijos@example.com",
    "origin": "web",
    "intent": "primary_residence",
    "budget_max": 250000,
    "bedrooms_min": 2,
    "operation_type": "buy"
  }'
{
  "data": {
    "id": "4af8325e-02c0-4882-8c1c-99e7c4326751",
    "full_name": "Ana Torrijos",
    "temperature": "warm",
    "assigned_agent_id": "6bd960d8-2d5a-43c0-a4cc-abb5e7c481db",
    "contact_id": "5ccee837-bdd6-4bdd-ac43-14c429d96c1a",
    "operation_id": "053655cc-47f4-43fd-9369-6f9dee659a28"
  }
}

Keep the operation_id: it is the thread everything else hangs from.

When you do not know yet what they want

A cold email does not say whether the person is buying or renting. Omit operation_type and the lead is born with no operation, with operation_id: null. It is not stranded: the first qualification the CRM confirms on it — a detection card, or the bot's first qualified turn — is what opens the operation.

curl -X POST "$ORKASA_API/leads" \
  -H "Authorization: Bearer $ORKASA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "Luis Bernal",
    "email": "luis.bernal@example.com",
    "origin": "email",
    "email_subject": "Consulta",
    "email_body": "Me interesa el apartamento en El Cangrejo, ¿está disponible para alquilar?"
  }'

Send email_subject and email_body and the AI reads the mail, exactly as it reads an inbound WhatsApp message: it is recorded as a message on the conversation thread, and detection emits cards with the intent and criteria it found. Neither field is stored on the lead.

That work happens after the response. The call is not slowed by it, and a detection failure can never cost you the lead: you always get your 201, and the lead is simply left raw, as if the mail had not been sent.

2. Read the operation

curl "$ORKASA_API/operations?lead_id=4af8325e-02c0-4882-8c1c-99e7c4326751&open_only=true" \
  -H "Authorization: Bearer $ORKASA_KEY"
{
  "data": [
    {
      "id": "053655cc-47f4-43fd-9369-6f9dee659a28",
      "operation_type": "buy",
      "flow": "buy",
      "stage": "interested",
      "stage_label": "Interesado",
      "is_terminal": false
    }
  ],
  "meta": { "next_cursor": null, "limit": 25 }
}

Always compare against stage. stage_label is for showing a person — see Stages.

3. Book the viewing

curl -X POST "$ORKASA_API/viewings" \
  -H "Authorization: Bearer $ORKASA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "lead_id": "4af8325e-02c0-4882-8c1c-99e7c4326751",
    "property_id": "b81f2a10-9c4e-4d55-bb0f-1e2f3a4b5c6d",
    "scheduled_at": "2026-09-18T16:00:00-05:00",
    "notes": "Wants to see the building before the unit."
  }'

scheduled_at is ISO 8601 and is validated. Send an explicit offset: a time without one gets interpreted, and a 4pm viewing that shows up at 9pm is a viewing that does not happen.

A viewing is scoped to the brokerage through its lead — the table has no brokerage column of its own. A viewing with no lead_id is invisible to the API: not a permission error, it simply does not exist for it.

Continue in Operation to close.