BrightshoalDocsOpen console
    MenuLeads

    API reference

    Leads

    The details an assistant captured from a visitor, and the outcome you report back once your team follows up.

    List leads

    GET/api/leads

    Leads assistants captured from web chat and WhatsApp, newest first, one cursor page at a time. A lead is created when the assistant takes the visitor's details and updated as the conversation goes on; subscribe to the lead.captured webhook to hear about each one as it happens.

    Secret API key. How it works

    Query parameters

    • project_idstring

      Only this project's leads.

    • fromstringISO 8601 timestamp

      Created at or after this time.

    • tostringISO 8601 timestamp

      Created at or before this time.

    • modestring

      Only leads captured in chats of this mode: live by default, so test and preview chats' leads are left out unless asked for. all lists every lead.

      One of live test preview all

      Default "live"

    • cursorstring

      Opaque next_cursor from the previous page. Legacy ISO timestamp cursors are also accepted.

    • limitinteger1 to 200

      Page size.

      Default 50

    Returns

    200 OK

    Response attributes

    • dataarray of Leadrequired

      20 attributes

      • idstringrequired

      • org_idstringrequired

      • project_idstringrequired

      • assistant_idstringrequired

      • conversation_idstring | null

      • namestring | null

      • emailstring | nullemail

      • phonestring | null

      • fieldsobject | null

      • sourcestringrequired

        One of web_chat whatsapp

      • modestring

        The mode of the chat that captured it: test and preview leads are left out of lists unless asked for.

        One of live test preview

      • outcomestring | null

        What became of the lead, as your CRM reports it (PUT /leads/{id}/outcome).

        One of open booked lost

      • outcome_valuestring | null

        Booking value as a decimal string.

      • outcome_currencystring | null

      • outcome_atstring | nullISO 8601 timestamp

      • outcome_refstring | null

        The CRM's own id for the booking.

      • customer_idstring | null

        The customer's own id for this person, set with PUT /v1/leads/{id}/outcome.

      • attributionChatAttribution | null

        Where the lead's chat came from. Returned by the list and detail reads; null when none was recorded.

        One of 2 shapes

        ChatAttribution

        • chat_pagestring

          The path the visitor started chatting on.

        • visitChatAttributionTouch

          This visit's landing.

          12 attributes

          • landing_pagestring

            A path starting with /, without query or fragment.

          • referrer_hoststring

          • utm_sourcestring

          • utm_mediumstring

          • utm_campaignstring

          • utm_termstring

          • utm_contentstring

          • gclidstring

          • gbraidstring

          • wbraidstring

          • fbclidstring

          • msclkidstring

        • firstobject

          The visitor's first-ever landing.

          13 attributes

          • landing_pagestring

            A path starting with /, without query or fragment.

          • referrer_hoststring

          • utm_sourcestring

          • utm_mediumstring

          • utm_campaignstring

          • utm_termstring

          • utm_contentstring

          • gclidstring

          • gbraidstring

          • wbraidstring

          • fbclidstring

          • msclkidstring

          • atstringISO 8601 timestamp

            When the visitor first landed.

        Option 2

      • created_atstringISO 8601 timestamp

      • updated_atstringISO 8601 timestamp

    • next_cursorstring | nullrequired

      Opaque cursor for the next page.

    • has_morebooleanrequired

    • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
    • 401 Missing, malformed, unknown or revoked API key (unauthorized)
    • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
    GET /api/leads
    curl "https://api.myleadsfactory.tech/api/leads" \
  -H "Authorization: Bearer $MLF_API_KEY"
    Response 200
    {
  "data": [
    {
      "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "name": "Front desk",
      "email": "ana@example.com",
      "phone": "+14155550123",
      "fields": {
        "key": "string"
      },
      "source": "web_chat",
      "mode": "live",
      "outcome": "open",
      "outcome_value": "string",
      "outcome_currency": "string",
      "outcome_at": "2026-10-28T09:30:00.000Z",
      "outcome_ref": "string",
      "customer_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "attribution": {
        "chat_page": "string",
        "visit": {
          "landing_page": {},
          "referrer_host": {},
          "utm_source": {},
          "utm_medium": {},
          "utm_campaign": {},
          "utm_term": {},
          "utm_content": {},
          "gclid": {},
          "gbraid": {},
          "wbraid": {},
          "fbclid": {},
          "msclkid": {}
        },
        "first": {
          "landing_page": {},
          "referrer_host": {},
          "utm_source": {},
          "utm_medium": {},
          "utm_campaign": {},
          "utm_term": {},
          "utm_content": {},
          "gclid": {},
          "gbraid": {},
          "wbraid": {},
          "fbclid": {},
          "msclkid": {},
          "at": {}
        }
      },
      "created_at": "2026-10-28T09:30:00.000Z",
      "updated_at": "2026-10-28T09:30:00.000Z"
    }
  ],
  "next_cursor": "eyJ0IjoiMjAyNi0xMC0yOCJ9",
  "has_more": true
}

    Get a lead

    GET/api/leads/{id}

    One lead with the details the assistant captured, the conversation it came from and any outcome you reported.

    Secret API key. How it works

    Path parameters

    • idstringrequired

      Lead id, lead_....

    Returns

    200 OK

    Response attributes

    • dataLeadrequired

      20 attributes

      • idstringrequired

      • org_idstringrequired

      • project_idstringrequired

      • assistant_idstringrequired

      • conversation_idstring | null

      • namestring | null

      • emailstring | nullemail

      • phonestring | null

      • fieldsobject | null

      • sourcestringrequired

        One of web_chat whatsapp

      • modestring

        The mode of the chat that captured it: test and preview leads are left out of lists unless asked for.

        One of live test preview

      • outcomestring | null

        What became of the lead, as your CRM reports it (PUT /leads/{id}/outcome).

        One of open booked lost

      • outcome_valuestring | null

        Booking value as a decimal string.

      • outcome_currencystring | null

      • outcome_atstring | nullISO 8601 timestamp

      • outcome_refstring | null

        The CRM's own id for the booking.

      • customer_idstring | null

        The customer's own id for this person, set with PUT /v1/leads/{id}/outcome.

      • attributionChatAttribution | null

        Where the lead's chat came from. Returned by the list and detail reads; null when none was recorded.

        One of 2 shapes

        ChatAttribution

        • chat_pagestring

          The path the visitor started chatting on.

        • visitChatAttributionTouch

          This visit's landing.

          12 attributes

          • landing_pagestring

            A path starting with /, without query or fragment.

          • referrer_hoststring

          • utm_sourcestring

          • utm_mediumstring

          • utm_campaignstring

          • utm_termstring

          • utm_contentstring

          • gclidstring

          • gbraidstring

          • wbraidstring

          • fbclidstring

          • msclkidstring

        • firstobject

          The visitor's first-ever landing.

          13 attributes

          • landing_pagestring

            A path starting with /, without query or fragment.

          • referrer_hoststring

          • utm_sourcestring

          • utm_mediumstring

          • utm_campaignstring

          • utm_termstring

          • utm_contentstring

          • gclidstring

          • gbraidstring

          • wbraidstring

          • fbclidstring

          • msclkidstring

          • atstringISO 8601 timestamp

            When the visitor first landed.

        Option 2

      • created_atstringISO 8601 timestamp

      • updated_atstringISO 8601 timestamp

    • 401 Missing, malformed, unknown or revoked API key (unauthorized)
    • 404 Not found, or outside what the key can see
    • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
    GET /api/leads/{id}
    curl "https://api.myleadsfactory.tech/api/leads/LEAD_ID" \
  -H "Authorization: Bearer $MLF_API_KEY"
    Response 200
    {
  "data": {
    "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "name": "Front desk",
    "email": "ana@example.com",
    "phone": "+14155550123",
    "fields": {
      "key": "string"
    },
    "source": "web_chat",
    "mode": "live",
    "outcome": "open",
    "outcome_value": "string",
    "outcome_currency": "string",
    "outcome_at": "2026-10-28T09:30:00.000Z",
    "outcome_ref": "string",
    "customer_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "attribution": {
      "chat_page": "string",
      "visit": {
        "landing_page": "string",
        "referrer_host": "string",
        "utm_source": "string",
        "utm_medium": "string",
        "utm_campaign": "string",
        "utm_term": "string",
        "utm_content": "string",
        "gclid": "string",
        "gbraid": "string",
        "wbraid": "string",
        "fbclid": "string",
        "msclkid": "string"
      },
      "first": {
        "landing_page": "string",
        "referrer_host": "string",
        "utm_source": "string",
        "utm_medium": "string",
        "utm_campaign": "string",
        "utm_term": "string",
        "utm_content": "string",
        "gclid": "string",
        "gbraid": "string",
        "wbraid": "string",
        "fbclid": "string",
        "msclkid": "string",
        "at": "2026-10-28T09:30:00.000Z"
      }
    },
    "created_at": "2026-10-28T09:30:00.000Z",
    "updated_at": "2026-10-28T09:30:00.000Z"
  }
}

    Report a lead's outcome

    PUT/api/leads/{id}/outcome

    Call from your CRM when a lead turns into a booking, is lost, or goes back to open, so chat analytics can count bookings and revenue. Replaces the whole outcome: a field you leave out is cleared, and at defaults to now. customer_id is separate: leaving it out keeps the stored one.

    Secret API key, not read-only. How it works

    Path parameters

    • idstringrequired

      Lead id, lead_....

    Request body

    • outcomestringrequired

      One of open booked lost

    • valuenumbermin 0

      Booking value, stored to two decimal places.

    • currencystring

      ISO 4217 code in capitals, for example GBP. Required when value is given.

    • atstringISO 8601 timestamp

      When it happened, ISO 8601 with an offset. Default: now.

    • refstringup to 128 characters

      Your CRM's id for the booking.

    • customer_idstringup to 128 characters

      The customer's own id for this person in their CRM (trimmed). Stored on the lead and used to link this person's chats across devices. Left unchanged when omitted.

    Returns

    200 OK

    Response attributes

    • dataLeadrequired

      20 attributes

      • idstringrequired

      • org_idstringrequired

      • project_idstringrequired

      • assistant_idstringrequired

      • conversation_idstring | null

      • namestring | null

      • emailstring | nullemail

      • phonestring | null

      • fieldsobject | null

      • sourcestringrequired

        One of web_chat whatsapp

      • modestring

        The mode of the chat that captured it: test and preview leads are left out of lists unless asked for.

        One of live test preview

      • outcomestring | null

        What became of the lead, as your CRM reports it (PUT /leads/{id}/outcome).

        One of open booked lost

      • outcome_valuestring | null

        Booking value as a decimal string.

      • outcome_currencystring | null

      • outcome_atstring | nullISO 8601 timestamp

      • outcome_refstring | null

        The CRM's own id for the booking.

      • customer_idstring | null

        The customer's own id for this person, set with PUT /v1/leads/{id}/outcome.

      • attributionChatAttribution | null

        Where the lead's chat came from. Returned by the list and detail reads; null when none was recorded.

        One of 2 shapes

        ChatAttribution

        • chat_pagestring

          The path the visitor started chatting on.

        • visitChatAttributionTouch

          This visit's landing.

          12 attributes

          • landing_pagestring

            A path starting with /, without query or fragment.

          • referrer_hoststring

          • utm_sourcestring

          • utm_mediumstring

          • utm_campaignstring

          • utm_termstring

          • utm_contentstring

          • gclidstring

          • gbraidstring

          • wbraidstring

          • fbclidstring

          • msclkidstring

        • firstobject

          The visitor's first-ever landing.

          13 attributes

          • landing_pagestring

            A path starting with /, without query or fragment.

          • referrer_hoststring

          • utm_sourcestring

          • utm_mediumstring

          • utm_campaignstring

          • utm_termstring

          • utm_contentstring

          • gclidstring

          • gbraidstring

          • wbraidstring

          • fbclidstring

          • msclkidstring

          • atstringISO 8601 timestamp

            When the visitor first landed.

        Option 2

      • created_atstringISO 8601 timestamp

      • updated_atstringISO 8601 timestamp

    • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
    • 401 Missing, malformed, unknown or revoked API key (unauthorized)
    • 403 Refused, for example a read-only key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
    • 404 Not found, or outside what the key can see
    • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
    PUT /api/leads/{id}/outcome
    curl -X PUT "https://api.myleadsfactory.tech/api/leads/LEAD_ID/outcome" \
  -H "Authorization: Bearer $MLF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "outcome": "booked",
  "value": 1840,
  "currency": "EUR",
  "ref": "BK-20931"
}'
    Response 200
    {
  "data": {
    "id": "lead_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "conversation_id": "conv_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "name": "Front desk",
    "email": "ana@example.com",
    "phone": "+14155550123",
    "fields": {
      "key": "string"
    },
    "source": "web_chat",
    "mode": "live",
    "outcome": "open",
    "outcome_value": "string",
    "outcome_currency": "string",
    "outcome_at": "2026-10-28T09:30:00.000Z",
    "outcome_ref": "string",
    "customer_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "attribution": {
      "chat_page": "string",
      "visit": {
        "landing_page": "string",
        "referrer_host": "string",
        "utm_source": "string",
        "utm_medium": "string",
        "utm_campaign": "string",
        "utm_term": "string",
        "utm_content": "string",
        "gclid": "string",
        "gbraid": "string",
        "wbraid": "string",
        "fbclid": "string",
        "msclkid": "string"
      },
      "first": {
        "landing_page": "string",
        "referrer_host": "string",
        "utm_source": "string",
        "utm_medium": "string",
        "utm_campaign": "string",
        "utm_term": "string",
        "utm_content": "string",
        "gclid": "string",
        "gbraid": "string",
        "wbraid": "string",
        "fbclid": "string",
        "msclkid": "string",
        "at": "2026-10-28T09:30:00.000Z"
      }
    },
    "created_at": "2026-10-28T09:30:00.000Z",
    "updated_at": "2026-10-28T09:30:00.000Z"
  }
}