API overview
Base URLs, response conventions, endpoint families, and the machine-readable OpenAPI document.
Base URL
https://api.ploid.com/v1All public operations other than API discovery require one of the authentication modes declared by that operation. External server integrations normally use an API key. The OpenAPI document itself is intentionally unauthenticated so clients can inspect the contract before creating a key.
curl https://api.ploid.com/v1/account/usage \
-H "Authorization: Bearer $PLOID_API_KEY"OpenAPI 3.1
Download the current machine-readable API contract from:
https://api.ploid.com/v1/openapi.jsonNo authorization header is required for this URL.
Endpoint families
| Family | Primary endpoint | Use it for |
|---|---|---|
| Search | POST /v1/search | Find people with a single query. |
| GitHub | POST /v1/github/search (beta) | Find GitHub accounts by company, repository, and profile flags. |
| Datasets | POST /v1/sets (preview) | Build curated lists of people from your criteria. |
| Profiles | POST /v1/socials, GET /v1/linkedin/profile | Pull full public profiles from social sites. |
| Contacts | POST /v1/enrich | Find work emails, personal emails, and phone numbers. |
| Monitors | POST /v1/monitors | Get notified when people or lists change. Documented in the OpenAPI Monitors tag. |
| Person | POST /v1/person | Evidence-backed person records and provenance |
| Account | /v1/account/* | Credits, usage context, and revoking the calling key |
The account surface consists of GET /v1/account/credits, GET /v1/account/usage, and DELETE /v1/account/key. The delete operation revokes the same key that authenticated the request.
Standard success envelope
Most JSON endpoints return a top-level data value and a meta object.
{
"data": {},
"meta": {
"request_id": "req_..."
}
}Version policy
The /v1 response envelopes are stable. Ranking, providers, and cache strategy may evolve without a version change when field names and response semantics remain compatible.
Server-side only
Do not call the Ploid API directly from public browser code. Keep the API key on your server and expose only the application-specific operation your frontend needs.
Failures and limits
Every surface uses the same public error envelope and plan limits. Individual endpoint pages list their additional validation errors, budgets, and route-specific ceilings.