Skip to main content
People search, enrichment, and outreach. Get started with the clodo API
Clododocs
SupportDashboard
DocumentationAPI ReferenceGuides
Search API

Deep Search

Find and qualify sales prospects, candidates, and subject-matter experts against detailed criteria. Turn a targeted people search into a researched shortlist with professional context and fit scores.

#Use case

Use Deep Search to find and qualify people against a focused set of criteria. It returns a researched shortlist with professional details, work experience, and fit scores, giving your team more context for deciding whom to approach.

  • Qualify sales leads before outreach. Search for decision-makers at companies in your target market—for example, technology leaders at regional banks or founders of climate-tech businesses in Germany. Review the returned company context and fit scores to prioritize prospects.
  • Build recruiting shortlists. Find candidates whose roles, industry backgrounds, and career experience align with a position. For a healthcare product leadership role, describe the relevant product and sector experience, then use the returned work history to guide your review.
  • Identify subject-matter experts for a project. Look for supply-chain leaders in manufacturing, executives in renewable energy, or operators in financial services. Compare their professional backgrounds when selecting potential interviewees, advisors, or research participants.

Choose standard or extended mode based on the size of the shortlist you want. Each mode has a fixed price per successful run, making it straightforward to budget recurring prospecting, candidate sourcing, and expert discovery workflows.

#Endpoint

POST https://api-public.clodo.ai/api/public/v1/deep-search/

Send your API key in the x-api-key header. See Authentication.

This endpoint returns 202 Accepted. Create a webhook signing secret and supply a public HTTPS webhook_url before making your first request. See Async Polling for retrieving results.

#Pricing

See Credits & Pricing for credit costs and charging behavior.

#Errors

For error responses and retry guidance, see Handling Errors.

POST /api/public/v1/deep-search/ — async (returns 202 Accepted). Fixed price per run:

  • mode: "standard" — 200 credits, ~25 qualified leads
  • mode: "extended" — 400 credits, ~100 qualified leads

Wall time ~10-15 minutes. Results delivered via signed webhook POST. Polling fallback at GET /api/public/v1/deep-search/{job_id}/.

#Request

Field Type Required Notes
query string yes Natural-language query. ≤500 chars.
mode string no "standard" (default) or "extended".
webhook_url string yes HTTPS URL. Must resolve to a public IP.

Pre-condition: an active webhook signing secret. See Webhook Signing Secrets.

Idempotency-Key header is supported. Same key returns the same job's current state.

#Response (202)

{
  "id": "dj_a1b2c3d4...",
  "status": "pending",
  "created_at": "2026-05-01T12:00:00Z"
}

#Webhook events

deep_search.completed:

{
  "id": "dj_a1b2c3d4...",
  "event_type": "deep_search.completed",
  "results": [
    {
      "first_name": "Patrick",
      "last_name": "Collison",
      "full_name": "Patrick Collison",
      "current_job_title": "CEO",
      "headline": "CEO at Stripe",
      "location": "San Francisco, California, United States",
      "professional_url": "linkedin.com/in/patrickcollison",
      "company": {
        "name": "Stripe",
        "domain": "stripe.com",
        "professional_url": "linkedin.com/company/stripe",
        "industry": "Financial Services",
        "employee_count": 8000
      },
      "email": "patrick@stripe.com",
      "experience": [
        {"company": "Stripe", "title": "CEO", "date_range": "2010–present"}
      ],
      "score": 92
    }
  ],
  "total_returned": 1
}

Company professional_url is optional and may be null.

deep_search.failed:

{
  "id": "dj_a1b2c3d4...",
  "event_type": "deep_search.failed",
  "error": {"code": "error", "message": "Deep search failed; please retry."}
}
error.code error.message
invalid_input Invalid deep-search query.
error Deep search failed; please retry.

A 0-result outcome ships as deep_search.completed with total_returned: 0.

Person and company professional_url values come back in bare-host form (no scheme, no www., no trailing slash). Company professional_url is optional and may be null.

#Billing

Fixed charge per run. Customer pays the full mode price on a successful run regardless of total_returned. Pipeline errors and dispatch failures release the reservation (no charge).

#Example

curl -X POST https://api-public.clodo.ai/api/public/v1/deep-search/ \
  -H "x-api-key: ck_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Climate tech founders in Berlin",
    "mode": "standard",
    "webhook_url": "https://yourapp.com/webhooks/clodo"
  }'

#Rate limit

POST /api/public/v1/deep-search/:

Limit Value
Sustained rate 4 requests / minute
Burst 2 requests

Polling GET /api/public/v1/deep-search/{job_id}/:

Limit Value
Sustained rate 3,600 requests / minute
Burst 100 requests

Exceeding any returns 429.

clodo Docs