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

Recruiting & Candidate Sourcing

Source candidates from a job description with the clodo API. Research professional experience, build recruiting shortlists, enrich profiles, and draft recruiter outreach.

Build a candidate sourcing workflow that starts with a role description and ends with a reviewed shortlist and recruiter outreach. Use clodo to find people with relevant professional experience, inspect their backgrounds, and explain why they may fit the role.

This example searches for engineering leaders who have brought robotics systems into production. The same flow works for specialized individual contributors, industry operators, and leadership searches when you change the job-related criteria.

#1. Turn a job description into a searchable persona

Separate requirements from preferences. Tell the search what the person needs to have done, the environment they worked in, and which experience is optional. Avoid relying on a title alone: two engineering managers can have very different technical and operating backgrounds.

Get specific enough to describe the person your team would be excited to meet: “An engineer who has operated Kubernetes in a regulated financial-services environment, previously worked at an early-stage company, and has presented a production incident case study.” Combine technical experience, career history, and public work; explain which are requirements and which would strengthen a match. Ask for evidence of the actual work, since employment at a company using a technology does not establish personal experience with it.

Hiring requirement Search detail
Relevant technical experience Deployed autonomous robotics systems in a production environment
Leadership background Led an engineering team through a product launch
Location Based in the United States
Preference Prior warehouse or industrial robotics experience

Keep the query focused on role-relevant evidence. Search results support sourcing and professional review; they do not establish availability, interest, or willingness to relocate.

#2. Search for candidates with specific experience

Agentic Search is the canonical endpoint for a detailed persona. It returns fit summaries, proof points, and evidence that help a recruiter understand the match. It requires account enrollment; see its availability section before starting.

Complete the API and webhook setup, then send this body to POST /api/public/v1/agentic-search/ with x-api-key. Replace the example webhook URL with your receiver.

{
  "query": "Find US-based engineering leaders who have taken autonomous robotics systems from prototype to production and led an engineering team through a product launch. Prioritize warehouse or industrial robotics experience. Exclude recruiting firms and consultants. Explain the relevant experience with supporting evidence.",
  "target_results": 25,
  "max_credits": 500,
  "webhook_url": "https://your-app.example/webhooks/clodo"
}

Save the returned job ID. Wait for agentic_search.completed, or poll GET /api/public/v1/agentic-search/{job_id}/. The requested result count is a target, not a guarantee. Check partial and completion_reason before treating the search as complete in your recruiting workflow.

For a broader candidate pool defined by title, industry, and location, use People Search. For a researched shortlist with fit scores and fixed pricing per successful run, use Deep Search.

#3. Build an evidence-based candidate review

For each result, retain the professional URL, current role, company, fit_summary, proof_points, and evidence. In your own recruiting application, show the original requirement next to the supporting information so reviewers can distinguish a demonstrated match from missing information.

An empty field means information was unavailable; it does not prove that the candidate lacks the experience. Use the evidence to decide what to verify in a conversation. Keep hiring decisions with the recruiting team and evaluate candidates against the same job-related criteria.

If the search stops early, review the saved candidates or refine the next query. To stop a running Agentic Search, call POST /api/public/v1/agentic-search/{job_id}/cancel/ and poll until terminal. Work already performed may be billable within the credit cap; cancellation does not necessarily erase the charge.

#4. Enrich shortlisted professional profiles

Call POST /api/public/v1/enrich/professional-profile/ for candidates who need further review, using the professional URL from search.

{
  "professional_url": "https://www.linkedin.com/in/selected-candidate"
}

The placeholder above must be replaced with a real result. Professional Profile Enrichment returns structured current position, work history, education, and location when available. Preserve missing values rather than filling them with assumptions.

Map the results into your ATS or candidate database through your application's integration. Store the source URL and search context alongside the candidate record. The clodo search endpoint does not create an ATS record automatically.

#5. Prepare recruiter outreach

Use Email Enrichment to resolve an email from a selected professional URL. A lookup can return no match; do not create an outreach request until you have a usable address. Connect a sending account, then submit the following structure to POST /api/public/v1/emails/ with actual candidate details.

{
  "to": {
    "email": "jordan@robotics.example",
    "first_name": "Jordan",
    "context": "Engineering leader with production robotics experience, reviewed by our recruiting team."
  },
  "instructions": "Draft a concise recruiting introduction for our robotics engineering leadership role. Mention the relevant production experience without inventing accomplishments. Ask whether they would be open to learning about the role. Do not assume they are job hunting or available to relocate.",
  "review": "required"
}

Poll the email until pending_review, confirm the recipient and factual claims, and edit the draft if necessary. Only approve it when you want it queued for sending. Outreach Emails documents draft edits, approval, cancellation, and reply state.

#Candidate sourcing questions

#How can I source candidates from a job description?

Turn the description into professional requirements, preferences, and exclusions, then submit that persona to Agentic Search. Review returned evidence against the requirements and enrich selected profiles before outreach. Agentic Search queries support up to 2,000 characters; People Search and Deep Search support up to 500.

#Can I use People Search to build a talent pool?

Yes. Describe the roles, industries, and geography you want. After a People Search completes, use search_id to retrieve additional non-overlapping pages. Deduplicate across separate searches in your own talent database.

#Does a match mean the candidate wants a new job?

No. A professional match does not establish job-seeking status or interest. Ask the person directly, and keep outreach grounded in the experience you actually reviewed.

clodo Docs