curl --request POST \
--url 'https://api.plyne.ai/v1/leads/search' \
--header 'Authorization: Bearer plyne_...' \
--header 'Content-Type: application/json' \
--data '{
"lead_ids": [
"ld_example_01"
],
"sheet_ids": [
"sh_example_01"
],
"signal_types": [
"hiring_signals"
],
"cursor": {
"limit": 50
}
}'
{
"data": [
{
"id": "ld_example_01",
"full_name": "Jamie Parker",
"job_title": "Engineering Manager",
"profile": {
"platform": "linkedin",
"url": "https://example.com/profiles/jamie-parker"
},
"account": {
"id": "co_example_01",
"name": "Stripe",
"domain": "stripe.com",
"linkedin_url": "https://www.linkedin.com/company/stripe",
"country_code": "US"
},
"source_sheet": {
"id": "sh_example_01",
"name": "Cloud infrastructure hiring"
},
"evaluation": {
"id": "eval_example_02",
"found_at": "2026-11-16T09:42:43.119743Z",
"source_sheet": {
"id": "sh_example_01",
"name": "Cloud infrastructure hiring"
},
"signal_agent_id": "ag_example_01",
"qualification": {
"status": "qualified",
"reason": "Engineering role and backend hiring activity match the configured criteria.",
"reasoning": "Jamie is an Engineering Manager at Stripe. The role and US location match the configured ideal customer profile, and a backend engineering opening matches the tracked hiring criteria.",
"references": [
{
"type": "evidence",
"label": "Senior Backend Engineer",
"url": "https://example.com/jobs/senior-backend-engineer"
},
{
"type": "evidence",
"label": "Stripe",
"url": "https://stripe.com"
}
]
},
"ai_score": {
"value": 82,
"fit": "high",
"reasoning": "The role and location match the configured criteria. The linked backend engineering opening adds relevant hiring context, resulting in a high fit score."
},
"findings": [
{
"id": "sig_example_02",
"type": "hiring_signals",
"name": "Hiring Activity",
"summary": "Stripe has an open Senior Backend Engineer role in this example.",
"reason": "The backend engineering opening matches the tracked hiring criteria and provides context for contacting an engineering decision-maker.",
"found_at": "2026-11-16T09:42:43.119743Z",
"observed_at": "2026-11-16T09:42:43.119743Z",
"source_sheet": {
"id": "sh_example_01",
"name": "Cloud infrastructure hiring"
},
"signal_agent_id": "ag_example_01",
"qualification": null,
"ai_score": null,
"references": [
{
"type": "evidence",
"label": "Senior Backend Engineer",
"url": "https://example.com/jobs/senior-backend-engineer"
}
]
}
],
"findings_cursor": {
"next": "",
"has_more": false
}
},
"country_code": "US",
"found_at": "2026-11-16T09:42:43.119743Z",
"latest_signal_at": "2026-11-16T09:42:43.119743Z",
"signal_count": 1,
"signal_sources": [
{
"type": "hiring_signals",
"name": "Hiring Activity",
"source_sheet": {
"id": "sh_example_01",
"name": "Cloud infrastructure hiring"
},
"signal_agent_id": "ag_example_01",
"finding_id": "sig_example_02",
"is_primary": true
}
]
}
],
"cursor": {
"next": "",
"has_more": false
}
}
Live signals
Leads
Retrieve the latest saved Leads from your Signal Agents, with available qualification, AI scores, and signal context. Filter results for your workflow.
curl --request POST \
--url 'https://api.plyne.ai/v1/leads/search' \
--header 'Authorization: Bearer plyne_...' \
--header 'Content-Type: application/json' \
--data '{
"lead_ids": [
"ld_example_01"
],
"sheet_ids": [
"sh_example_01"
],
"signal_types": [
"hiring_signals"
],
"cursor": {
"limit": 50
}
}'
{
"data": [
{
"id": "ld_example_01",
"full_name": "Jamie Parker",
"job_title": "Engineering Manager",
"profile": {
"platform": "linkedin",
"url": "https://example.com/profiles/jamie-parker"
},
"account": {
"id": "co_example_01",
"name": "Stripe",
"domain": "stripe.com",
"linkedin_url": "https://www.linkedin.com/company/stripe",
"country_code": "US"
},
"source_sheet": {
"id": "sh_example_01",
"name": "Cloud infrastructure hiring"
},
"evaluation": {
"id": "eval_example_02",
"found_at": "2026-11-16T09:42:43.119743Z",
"source_sheet": {
"id": "sh_example_01",
"name": "Cloud infrastructure hiring"
},
"signal_agent_id": "ag_example_01",
"qualification": {
"status": "qualified",
"reason": "Engineering role and backend hiring activity match the configured criteria.",
"reasoning": "Jamie is an Engineering Manager at Stripe. The role and US location match the configured ideal customer profile, and a backend engineering opening matches the tracked hiring criteria.",
"references": [
{
"type": "evidence",
"label": "Senior Backend Engineer",
"url": "https://example.com/jobs/senior-backend-engineer"
},
{
"type": "evidence",
"label": "Stripe",
"url": "https://stripe.com"
}
]
},
"ai_score": {
"value": 82,
"fit": "high",
"reasoning": "The role and location match the configured criteria. The linked backend engineering opening adds relevant hiring context, resulting in a high fit score."
},
"findings": [
{
"id": "sig_example_02",
"type": "hiring_signals",
"name": "Hiring Activity",
"summary": "Stripe has an open Senior Backend Engineer role in this example.",
"reason": "The backend engineering opening matches the tracked hiring criteria and provides context for contacting an engineering decision-maker.",
"found_at": "2026-11-16T09:42:43.119743Z",
"observed_at": "2026-11-16T09:42:43.119743Z",
"source_sheet": {
"id": "sh_example_01",
"name": "Cloud infrastructure hiring"
},
"signal_agent_id": "ag_example_01",
"qualification": null,
"ai_score": null,
"references": [
{
"type": "evidence",
"label": "Senior Backend Engineer",
"url": "https://example.com/jobs/senior-backend-engineer"
}
]
}
],
"findings_cursor": {
"next": "",
"has_more": false
}
},
"country_code": "US",
"found_at": "2026-11-16T09:42:43.119743Z",
"latest_signal_at": "2026-11-16T09:42:43.119743Z",
"signal_count": 1,
"signal_sources": [
{
"type": "hiring_signals",
"name": "Hiring Activity",
"source_sheet": {
"id": "sh_example_01",
"name": "Cloud infrastructure hiring"
},
"signal_agent_id": "ag_example_01",
"finding_id": "sig_example_02",
"is_primary": true
}
]
}
],
"cursor": {
"next": "",
"has_more": false
}
}
POST /v1/leads/search
curl --request POST \
--url 'https://api.plyne.ai/v1/leads/search' \
--header 'Authorization: Bearer plyne_...' \
--header 'Content-Type: application/json' \
--data '{
"lead_ids": [
"ld_example_01"
],
"sheet_ids": [
"sh_example_01"
],
"signal_types": [
"hiring_signals"
],
"cursor": {
"limit": 50
}
}'
{
"data": [
{
"id": "ld_example_01",
"full_name": "Jamie Parker",
"job_title": "Engineering Manager",
"profile": {
"platform": "linkedin",
"url": "https://example.com/profiles/jamie-parker"
},
"account": {
"id": "co_example_01",
"name": "Stripe",
"domain": "stripe.com",
"linkedin_url": "https://www.linkedin.com/company/stripe",
"country_code": "US"
},
"source_sheet": {
"id": "sh_example_01",
"name": "Cloud infrastructure hiring"
},
"evaluation": {
"id": "eval_example_02",
"found_at": "2026-11-16T09:42:43.119743Z",
"source_sheet": {
"id": "sh_example_01",
"name": "Cloud infrastructure hiring"
},
"signal_agent_id": "ag_example_01",
"qualification": {
"status": "qualified",
"reason": "Engineering role and backend hiring activity match the configured criteria.",
"reasoning": "Jamie is an Engineering Manager at Stripe. The role and US location match the configured ideal customer profile, and a backend engineering opening matches the tracked hiring criteria.",
"references": [
{
"type": "evidence",
"label": "Senior Backend Engineer",
"url": "https://example.com/jobs/senior-backend-engineer"
},
{
"type": "evidence",
"label": "Stripe",
"url": "https://stripe.com"
}
]
},
"ai_score": {
"value": 82,
"fit": "high",
"reasoning": "The role and location match the configured criteria. The linked backend engineering opening adds relevant hiring context, resulting in a high fit score."
},
"findings": [
{
"id": "sig_example_02",
"type": "hiring_signals",
"name": "Hiring Activity",
"summary": "Stripe has an open Senior Backend Engineer role in this example.",
"reason": "The backend engineering opening matches the tracked hiring criteria and provides context for contacting an engineering decision-maker.",
"found_at": "2026-11-16T09:42:43.119743Z",
"observed_at": "2026-11-16T09:42:43.119743Z",
"source_sheet": {
"id": "sh_example_01",
"name": "Cloud infrastructure hiring"
},
"signal_agent_id": "ag_example_01",
"qualification": null,
"ai_score": null,
"references": [
{
"type": "evidence",
"label": "Senior Backend Engineer",
"url": "https://example.com/jobs/senior-backend-engineer"
}
]
}
],
"findings_cursor": {
"next": "",
"has_more": false
}
},
"country_code": "US",
"found_at": "2026-11-16T09:42:43.119743Z",
"latest_signal_at": "2026-11-16T09:42:43.119743Z",
"signal_count": 1,
"signal_sources": [
{
"type": "hiring_signals",
"name": "Hiring Activity",
"source_sheet": {
"id": "sh_example_01",
"name": "Cloud infrastructure hiring"
},
"signal_agent_id": "ag_example_01",
"finding_id": "sig_example_02",
"is_primary": true
}
]
}
],
"cursor": {
"next": "",
"has_more": false
}
}
Body fields
| Field | Meaning |
|---|---|
query | Case-insensitive literal substring of a person’s full name or associated company name. Maximum 200 characters. |
account_domains | Exact company domains, such as stripe.com. URLs and www. are normalized; subdomains remain distinct. |
lead_ids | Return specific Leads by ID. |
account_ids | Restrict Leads to the given Accounts. |
signal_types | Stable signal type IDs. Any visible source occurrence may match, including findings outside the selected evaluation. See Accepted Filter Values. |
sheet_ids | Filter by source Sheet IDs. |
lead_country_codes | Lead country, using two-letter country codes. |
account_country_codes | Account country, using two-letter country codes. |
found_at | Date found: when the Lead first entered the portal’s Directory. |
latest_signal_at | Date range for the entity’s latest visible material signal. |
ai_score | Inclusive min and max bounds from 0 to 100. |
sort | field and direction, described below. |
cursor | limit and after, described in Pagination and Filters. |
found_at, latest_signal_at, ai_score, and signal_count. Directions are asc and desc; the default is found_at descending, matching the portal’s Date found order.
Understand the response
Each item is one Lead.evaluation contains the selected assessment and its linked findings; source_sheet identifies its selected source context. These do not represent every finding or Sheet associated with the record. Findings in the selected evaluation can differ from the source that matched your filter.
latest_signal_at and signal_count describe the record across its visible sources. A missing evaluation.ai_score is null; a calculated zero remains a score with value: 0.
See the Data Dictionary for field definitions and Pagination and Filters for date and filter behavior. Use Lead signal history to review individual findings and their evidence.
Evaluations and linked findings
evaluation is the assessment selected for this record, with up to five findings linked to that exact decision. Each finding retains its own qualification, score, and evidence. These can differ from the evaluation’s assessment.
signal_sources matches the portal’s qualified source stack. is_primary marks the row’s displayed source when it belongs to this qualified set. It groups findings by signal type, Sheet, and Signal Agent; it is not a list of every finding.
If evaluation.findings_cursor.has_more is true, call signal history with evaluation_id set to evaluation.id and cursor.after set to evaluation.findings_cursor.next. Leave other filters unset for this continuation.
Use Lead evaluations to review other saved evaluations and the findings behind each one.