Build with Ploid

Quickstart

Create a Set with a natural-language query. Ploid derives criteria, verifies candidates, and can enrich accepted people in the same workflow.

curl https://api.ploid.com/v1/sets \
  -H "Authorization: Bearer $PLOID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "search": {
      "query": "ML engineers at Google in San Francisco",
      "count": 50
    },
    "enrichments": [
      { "description": "Work email", "format": "email" }
    ],
    "webhook_url": "https://example.com/webhooks/ploid"
  }'

The 201 response includes the Set ID, item and event URLs, and a pricing estimate. Poll the Set, stream its events, or receive the idle event at your webhook.

curl https://api.ploid.com/v1/sets/set_123 \
  -H "Authorization: Bearer $PLOID_API_KEY"

curl "https://api.ploid.com/v1/sets/set_123/items?status=admitted" \
  -H "Authorization: Bearer $PLOID_API_KEY"

Authentication

Send a ploid_live_… key as a Bearer token or in the x-api-key header. Secrets are shown only once and stored hashed by Ploid.

Authorization: Bearer $PLOID_API_KEY

# Or
x-api-key: $PLOID_API_KEY

Scopes

Give each key only the scopes its integration needs. Calling an endpoint without its required scope returns 403 insufficient_scope.

Sets workflow

Use /v1/sets for production people discovery. It supports criteria verification, incremental items, enrichment columns, imports, recurring monitors, webhooks, SSE, and exports. Use /v1/search only when you need a synchronous list of up to 100 people.

Stream progress

Connect to the returned events_url. Resume after a disconnect with after_seq. Important events include set.item.created, set.item.enriched, set.search.completed, and set.idle.

curl -N "https://api.ploid.com/v1/sets/set_123/events?after_seq=-1" \
  -H "Authorization: Bearer $PLOID_API_KEY"

Batch enrichment

Estimate first, then create an asynchronous job for up to 500 people. Set max_cost_usd to enforce a hard budget and webhook_url to receive batch.completed. Results can be paged while the job is still running.

curl https://api.ploid.com/v1/people/batch/enrich \
  -H "Authorization: Bearer $PLOID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "people": [
      { "identifier": "https://www.linkedin.com/in/example" },
      { "identifier": "person@example.com" }
    ],
    "fields": ["linkedin", "github", "work_email"],
    "max_cost_usd": 25,
    "webhook_url": "https://example.com/webhooks/ploid"
  }'

Endpoint reference

All routes below use https://api.ploid.com. Download the machine-readable OpenAPI 3.1 document for request and response schemas.

Responses and errors

Successful JSON responses use a data object and may include meta for request IDs, warnings, pagination, usage, and cost. List endpoints use cursor-based pagination where noted.

{
  "data": { "id": "set_123", "status": "running" },
  "meta": { "request_id": "req_123" }
}

Errors have a stable code, a readable message, and a request ID to include when contacting support.

{
  "error": {
    "code": "insufficient_credits",
    "message": "Out of credits. Top up to continue.",
    "request_id": "req_123"
  }
}

Common error codes

missing_api_key, invalid_api_key, paid_plan_required, insufficient_scope, insufficient_credits, daily_budget_exceeded, monthly_budget_exceeded, max_cost_exceeded, rate_limited, and queue_unavailable.

A 429 rate_limited response includes a Retry-After header. Retry idempotent requests after that delay with exponential backoff.

Pricing and limits

One credit is $0.10. Responses expose dollar amounts such as estimated_cost_usd, cost_usd, and remaining_balance_usd, so integrations do not need to convert credits. Clean not-found enrichment fields are not charged.

Search and enrichment pricing is returned with each request because the exact cost depends on the requested result count and fields. Use /v1/people/estimate before batch enrichment and set max_cost_usd on jobs.

Limits apply at the organization and key levels. Keys can also have daily and monthly budgets. Inspect the active limits and reset windows at GET /v1/account/usage.

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.