Search
Run synchronous people discovery with structured filters and an optional semantic query.
Fast synchronous search
POST /v1/searchUse this endpoint for a one-shot list of up to 50 people. Provide a semantic
query, at least one structured filter, or both.
curl https://api.ploid.com/v1/search \
-H "Authorization: Bearer $PLOID_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "software engineers at fintech companies in San Francisco",
"type": "auto",
"category": "people",
"num_results": 25,
"filters": {
"title": "software engineer",
"seniority": "senior",
"industry": "fintech",
"location": "San Francisco"
},
"contents": {
"fields": ["linkedin", "title", "company", "location"]
}
}'Search types:
instant— retrieve from Ploid's people index.fast— overfetch and rerank index results for better recall.auto— after index retrieval, resolve a named-person miss from the public web and add bounded grounding when results are thin.deep— resolve a named-person miss and always add bounded public-web grounding after index retrieval.
The current people index enforces title, seniority, company, industry,
and location. company_size, company_domain, radius_km, and tenure
return 422 unsupported_filters until those fields are available in the
serving index; they are never silently ignored. Main results always include
person.person_id, which can be passed directly to POST /v1/person, plus
person.resolution_source (ploid_people_index or public_web). Retrieval does
not verify current profile claims, so person.identity_verified is false until
POST /v1/person returns evidence. person.confidence is the normalized
retrieval score when available. Contact fields are deliberately excluded and
reported as person.contact_status: "requires_enrichment"; resolve them through
POST /v1/enrich. Auto/deep search reranks the union of index and corroborated
public-web candidates; evidence pages also remain available under
data.grounding.
Choosing a public surface
| Need | Choose |
|---|---|
| Immediate list, 50 or fewer results | /v1/search |
| Multi-step analysis and synthesis | /v1/agent |
Durable People Sets are a private preview and are not currently available to public API keys.
Errors and limits
| Condition | Status and code |
|---|---|
Category is not people | 422 unsupported_category |
| Filter is not in serving index | 422 unsupported_filters |
| Fast search is not configured | 503 search_unavailable |
| Search timed out without results | 503 search_timeout |
| Search failed without results | 503 search_failed |
POST /v1/search accepts at most 50 results. The workspace plan and API key
set the request rate; rejected calls return Retry-After and are never billed.
Timed-out or shard-partial index responses fail closed with a 503; the endpoint
does not return partial index results. See Errors & rate limits.