> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plyne.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Leads

> Read qualified Leads surfaced by Signal Agents.

The leads endpoint returns qualified Leads that matched your ICP and showed relevant intent.

Each lead includes company details directly in the response so you can show who to contact and why the timing matters.

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://api.plyne.ai/v1/signals/leads' \
    --header 'Authorization: Bearer plyne_...' \
    --header 'Content-Type: application/json' \
    --data '{
      "signals": ["topic_engagement_signal"],
      "sheet_ids": ["sh_6P9vR3"],
      "lead_country_codes": ["US"],
      "company_country_codes": ["US"],
      "latest_signal": {
        "start_time": "2026-06-01T00:00:00Z",
        "end_time": "2026-07-01T00:00:00Z"
      },
      "sort": { "field": "date_found", "direction": "SORT_DIRECTION_DESC" },
      "cursor": { "limit": 100 }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [
      {
        "id": "ld_8K2mQ9",
        "full_name": "Sarah Carter",
        "title": "Head of Engineering",
        "country_code": "US",
        "profile": {
          "platform": "linkedin",
          "url": "https://linkedin.com/in/sarah-carter"
        },
        "company": {
          "id": "co_4F7xN2",
          "name": "Acme",
          "domain": "acme.com",
          "linkedin_url": "https://linkedin.com/company/acme",
          "country_code": "US"
        },
        "sheet": {
          "id": "sh_6P9vR3",
          "name": "AI infrastructure buyers"
        },
        "signal": {
          "type": "topic_engagement_signal",
          "name": "Post Engagers",
          "summary": "Engaged with relevant topic content recently",
          "reason": "Sarah engaged with content related to cloud infrastructure modernization.",
          "observed_at": "2026-06-15T08:00:00Z"
        },
        "qualification": {
          "status": "qualified",
          "reason": "Strong ICP fit based on seniority, role, company profile, and recent intent.",
          "reasoning": "The lead matches the target persona and ICP criteria. Head of Engineering matches the target buyer persona, Acme matches the company profile, and recent engagement supports current intent.",
          "references": [
            {
              "type": "evidence",
              "label": "Topic engagement",
              "url": "https://linkedin.com/posts/example"
            }
          ]
        },
        "score": {
          "value": 86,
          "fit": "high",
          "reasoning": "High lead priority because the person has strong title fit, resolved company context, and recent relevant signal evidence."
        }
      }
    ],
    "cursor": {
      "next": "",
      "has_more": false
    }
  }
  ```
</ResponseExample>

```http theme={null}
POST /v1/signals/leads
```

<div className="plyne-api-meta">
  <section className="plyne-api-section">
    <h2>Authorizations</h2>

    <div className="plyne-param">
      <div className="plyne-param-title">
        <span className="plyne-param-name">Authorization</span>
        <span className="plyne-pill">string</span>
        <span className="plyne-pill">header</span>
        <span className="plyne-pill plyne-pill-required">required</span>
      </div>

      <p>Bearer authentication header of the form <code>Bearer \<token></code>, where <code>\<token></code> is your API key.</p>
    </div>
  </section>

  <section className="plyne-api-section">
    <h2>Body</h2>

    <div className="plyne-param">
      <div className="plyne-param-title">
        <span className="plyne-param-name">signals</span>
        <span className="plyne-pill">string\[]</span>
      </div>

      <p>Filter by signal type, matching the <code>signal.type</code> values returned with each lead. See <a href="/api/accepted-filter-values">Accepted Filter Values</a>.</p>
      <p className="plyne-param-example">Example: <code>\["topic\_engagement\_signal"]</code></p>
    </div>

    <div className="plyne-param">
      <div className="plyne-param-title">
        <span className="plyne-param-name">sheet\_ids</span>
        <span className="plyne-pill">string\[]</span>
      </div>

      <p>Filter leads to one or more sheets configured in the dashboard.</p>
      <p className="plyne-param-example">Example: <code>\["sh\_6P9vR3"]</code></p>
    </div>

    <div className="plyne-param">
      <div className="plyne-param-title">
        <span className="plyne-param-name">lead\_ids</span>
        <span className="plyne-pill">string\[]</span>
      </div>

      <p>Return specific leads by ID.</p>
      <p className="plyne-param-example">Example: <code>\["ld\_8K2mQ9"]</code></p>
    </div>

    <div className="plyne-param">
      <div className="plyne-param-title">
        <span className="plyne-param-name">company\_ids</span>
        <span className="plyne-pill">string\[]</span>
      </div>

      <p>Filter leads to one or more companies.</p>
      <p className="plyne-param-example">Example: <code>\["co\_4F7xN2"]</code></p>
    </div>

    <div className="plyne-param">
      <div className="plyne-param-title">
        <span className="plyne-param-name">lead\_country\_codes</span>
        <span className="plyne-pill">string\[]</span>
      </div>

      <p>Filter by lead country code using two-letter country codes. See <a href="/api/accepted-filter-values">Accepted Filter Values</a>.</p>
      <p className="plyne-param-example">Example: <code>\["US", "GB"]</code></p>
    </div>

    <div className="plyne-param">
      <div className="plyne-param-title">
        <span className="plyne-param-name">company\_country\_codes</span>
        <span className="plyne-pill">string\[]</span>
      </div>

      <p>Filter by company country code using two-letter country codes. See <a href="/api/accepted-filter-values">Accepted Filter Values</a>.</p>
      <p className="plyne-param-example">Example: <code>\["US", "CA"]</code></p>
    </div>

    <div className="plyne-param">
      <div className="plyne-param-title">
        <span className="plyne-param-name">date\_found</span>
        <span className="plyne-pill">object</span>
      </div>

      <p>Restrict results by when the lead first entered the Directory.</p>
    </div>

    <div className="plyne-param">
      <div className="plyne-param-title">
        <span className="plyne-param-name">latest\_signal</span>
        <span className="plyne-pill">object</span>
      </div>

      <p>Restrict results to when the latest matching distinct signal was observed.</p>
    </div>

    <div className="plyne-param">
      <div className="plyne-param-title">
        <span className="plyne-param-name">ai\_score</span>
        <span className="plyne-pill">object</span>
      </div>

      <p>Restrict results using inclusive <code>min</code> and <code>max</code> score values from 0 to 100.</p>
    </div>

    <div className="plyne-param">
      <div className="plyne-param-title">
        <span className="plyne-param-name">sort</span>
        <span className="plyne-pill">object</span>
      </div>

      <p>Sort by <code>date\_found</code>, <code>latest\_signal</code>, <code>ai\_score</code>, or <code>signal\_count</code>. Direction is <code>SORT\_DIRECTION\_DESC</code> or <code>SORT\_DIRECTION\_ASC</code>. The default is <code>date\_found</code> descending, matching the Leads dashboard.</p>
    </div>

    <div className="plyne-param">
      <div className="plyne-param-title">
        <span className="plyne-param-name">cursor.limit</span>
        <span className="plyne-pill">integer</span>
      </div>

      <p>Number of leads to return per page.</p>
      <p className="plyne-param-example">Example: <code>100</code></p>
    </div>

    <div className="plyne-param">
      <div className="plyne-param-title">
        <span className="plyne-param-name">cursor.after</span>
        <span className="plyne-pill">string</span>
      </div>

      <p>Opaque cursor returned as <code>cursor.next</code> from the previous response.</p>
    </div>
  </section>
</div>