Casa Intelligence Leads API

openapi: 3.2.0
info:
  title: Casa Intelligence Engine Leads API
  description: Proprietary data ingestion, analysis, and prediction engine for Queensland property development intelligence.
  version: 2.0.0
tags:
- name: Leads
paths:
  /api/v1/leads:
    post:
      tags:
      - Leads
      summary: Create Lead
      operationId: create_lead_api_v1_leads_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeadIn'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Create Lead Api V1 Leads Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/desk/leads:
    get:
      tags:
      - Leads
      summary: List Leads
      operationId: list_leads_api_v1_desk_leads_get
      parameters:
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
      - name: q
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Q
      - name: claimed
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: unclaimed | <user> | all
          title: Claimed
        description: unclaimed | <user> | all
      - name: internal
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: '''all'' to include Casa''s own test rows'
          title: Internal
        description: '''all'' to include Casa''s own test rows'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 500
          default: 200
          title: Limit
      - name: x-desk-token
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Desk-Token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response List Leads Api V1 Desk Leads Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/desk/leads/{lead_id}/journey:
    get:
      tags:
      - Leads
      summary: Lead Journey
      description: 'Every property this lead''s browsing session looked at, before or after they left their number.


        The join key is the session, not the address on the lead row. That is what makes the ordering

        irrelevant: the events keep arriving on the same session after the number is submitted, so a

        person who asks for a call and then goes looking at three addresses shows all three, and a

        person who looks first and asks after shows the same thing. Neither has to tell us anything.


        Returns ``{linked, addresses, device, channel, first_seen, last_seen, events}``. ``linked`` is

        false when no session could be tied to this lead, which is the honest answer for a lead created

        before this link existed, or by a visitor whose browser refused session storage.'
      operationId: lead_journey_api_v1_desk_leads__lead_id__journey_get
      parameters:
      - name: lead_id
        in: path
        required: true
        schema:
          type: string
          title: Lead Id
      - name: x-desk-token
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Desk-Token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Lead Journey Api V1 Desk Leads  Lead Id  Journey Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/desk/leads/{lead_id}:
    patch:
      tags:
      - Leads
      summary: Patch Lead
      operationId: patch_lead_api_v1_desk_leads__lead_id__patch
      parameters:
      - name: lead_id
        in: path
        required: true
        schema:
          type: string
          title: Lead Id
      - name: x-desk-token
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Desk-Token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeadPatch'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Patch Lead Api V1 Desk Leads  Lead Id  Patch
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/desk/leads/replied:
    post:
      tags:
      - Leads
      summary: Mark Replied
      description: 'Record that a human is now talking to this person, so no automated

        sequence ever speaks over the top of the conversation again.


        Conversion Recovery Spec WS6.1. Replies land in Robbie''s mailbox, which the

        database cannot see, so the desk records them. Writes the

        ``ci_lead_conversations`` suppressor the nurture sweep already gates on

        (the Katherine Clarke row, 2026-09-03), and optionally the opt-out list.

        Idempotent: registering someone twice updates ``last_seen``.


        Absence of a row here is never evidence there is no conversation; this

        only ever suppresses.'
      operationId: mark_replied_api_v1_desk_leads_replied_post
      parameters:
      - name: x-desk-token
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Desk-Token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RepliedIn'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Mark Replied Api V1 Desk Leads Replied Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/desk/leads/{lead_id}/payment-link:
    post:
      tags:
      - Leads
      summary: Send Payment Link
      description: 'Create the Stripe checkout link for a quoted lead.


        notify=true (the desk button) emails the link to the lead from hello@.

        notify=false returns the link without sending anything, for the times

        Robbie puts it in his own reply. Nothing about a report is ever emailed

        automatically either way.'
      operationId: send_payment_link_api_v1_desk_leads__lead_id__payment_link_post
      parameters:
      - name: lead_id
        in: path
        required: true
        schema:
          type: string
          title: Lead Id
      - name: notify
        in: query
        required: false
        schema:
          type: boolean
          default: true
          title: Notify
      - name: x-desk-token
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Desk-Token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Send Payment Link Api V1 Desk Leads  Lead Id  Payment Link Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    LeadIn:
      properties:
        name:
          anyOf:
          - type: string
            maxLength: 200
          - type: 'null'
          title: Name
        email:
          anyOf:
          - type: string
            maxLength: 320
          - type: 'null'
          title: Email
        phone:
          anyOf:
          - type: string
            maxLength: 60
          - type: 'null'
          title: Phone
        address:
          anyOf:
          - type: string
            maxLength: 400
          - type: 'null'
          title: Address
        context:
          anyOf:
          - type: string
            maxLength: 4000
          - type: 'null'
          title: Context
        page_url:
          anyOf:
          - type: string
            maxLength: 1000
          - type: 'null'
          title: Page Url
        source:
          type: string
          maxLength: 40
          title: Source
          default: popup
        check_id:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Check Id
        property_id:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Property Id
        lot_plan:
          anyOf:
          - type: string
            maxLength: 60
          - type: 'null'
          title: Lot Plan
        verdict:
          anyOf:
          - type: string
            maxLength: 40
          - type: 'null'
          title: Verdict
      type: object
      title: LeadIn
    LeadPatch:
      properties:
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        email:
          anyOf:
          - type: string
          - type: 'null'
          title: Email
        phone:
          anyOf:
          - type: string
          - type: 'null'
          title: Phone
        address:
          anyOf:
          - type: string
          - type: 'null'
          title: Address
        address_confirmed:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Address Confirmed
        context:
          anyOf:
          - type: string
          - type: 'null'
          title: Context
        call_context:
          anyOf:
          - type: string
          - type: 'null'
          title: Call Context
        report_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Report Type
        quoted_price_aud:
          anyOf:
          - type: number
          - type: 'null'
          title: Quoted Price Aud
        status:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
        notes:
          anyOf:
          - type: string
          - type: 'null'
          title: Notes
        claimed_by:
          anyOf:
          - type: string
          - type: 'null'
          title: Claimed By
        referrer_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Referrer Name
        referrer_email:
          anyOf:
          - type: string
          - type: 'null'
          title: Referrer Email
        referrer_agency:
          anyOf:
          - type: string
          - type: 'null'
          title: Referrer Agency
        internal:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Internal
      type: object
      title: LeadPatch
    RepliedIn:
      properties:
        email:
          type: string
          maxLength: 320
          title: Email
        note:
          anyOf:
          - type: string
            maxLength: 1000
          - type: 'null'
          title: Note
        unsubscribe:
          type: boolean
          title: Unsubscribe
          default: false
      type: object
      required:
      - email
      title: RepliedIn
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key