Openjobs People Search

---

name: openjobs-people-search description: Search, discover, and retrieve professional candidate profiles using OpenJobs AI. Supports structured search, profile lookup, candidate comparison, talent analytics, and contact info unlock. metadata: {"clawdbot":{"emoji":"🔍","requires":{"env":["MIRA_KEY"]},"primaryEnv":"MIRA_KEY"}}

---

🔍 Openjobs People Search

Search and retrieve professional candidate profiles for recruiting and talent sourcing using the OpenJobs AI database.

When to use

Use this skill when the user needs to:

Search for professional candidates using structured filters

Retrieve full candidate profiles by LinkedIn URL

Compare multiple candidates side by side

Analyze talent pool statistics and distributions

Unlock candidate contact information (email addresses) by LinkedIn URL

Version Check

At the start of every session, check whether this skill is up to date:

1. Call the version endpoint:

curl -s https://mira-api.openjobs-ai.com/v1/version

2. Compare the returned version with this skill's frontmatter version: 1.0.1. 3. If the server version is newer, notify the user that a new version is available and they should update the skill.

If the versions match, proceed normally without notifying the user.

First-time Setup

Before using any feature, check whether an API key is already available:

1. Check the MIRA_KEY environment variable: echo $MIRA_KEY

If no key is found, ask the user: > "Do you have a Mira API key?"

Yes — ask them to provide it, then set it as an environment variable:

export MIRA_KEY="mira_your_key_here"

No — prompt them to register:

> "You can get your API key by signing up at https://platform.openjobs-ai.com/"

Do not proceed with any API call until a valid key is available.

API Basics

All requests need:

curl -X POST "https://mira-api.openjobs-ai.com/v1/..." \
  -H "Authorization: Bearer $MIRA_KEY" \
  -H "Content-Type: application/json"

Unified response format:

{ "code": 200, "message": "ok", "data": { ... } }

Errors return: { "code": 4xx/5xx, "message": "", "data": null }

Common Operations

Search candidates by structured filters (fast, no AI parsing):

curl -X POST "https://mira-api.openjobs-ai.com/v1/people-fast-search" \
  -H "Authorization: Bearer $MIRA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "United States",
    "skills": ["Python", "AWS"],
    "skills_operator": "AND",
    "experience_months_min": 60,
    "is_working": true
  }'

> At least one filter field required. Returns up to 20 results.

Get aggregate analytics on the candidate pool:

curl -X POST "https://mira-api.openjobs-ai.com/v1/people-stats" \
  -H "Authorization: Bearer $MIRA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "United States",
    "group_by": ["management_level"],
    "stats_fields": ["experience_months"],
    "histogram_fields": [{"field": "age", "interval": 10}]
  }'

Look up full profiles by LinkedIn URL (1–50 URLs):

curl -X POST "https://mira-api.openjobs-ai.com/v1/people-lookup" \
  -H "Authorization: Bearer $MIRA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "linkedin_urls": [
      "https://www.linkedin.com/in/xxx",
      "https://www.linkedin.com/in/yyy"
    ]
  }'

Compare candidates side by side (2–10 URLs):

curl -X POST "https://mira-api.openjobs-ai.com/v1/people-compare" \
  -H "Authorization: Bearer $MIRA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "linkedin_urls": [
      "https://www.linkedin.com/in/xxx",
      "https://www.linkedin.com/in/yyy"
    ]
  }'

> Returns current position, highest education, skills, and languages for each candidate.

Unlock candidate contact info by LinkedIn URL (1–50 URLs):

curl -X POST "https://mira-api.openjobs-ai.com/v1/people-unlock" \
  -H "Authorization: Bearer $MIRA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "linkedin_urls": [
      "https://www.linkedin.com/in/xxx",
      "https://www.linkedin.com/in/yyy"
    ]
  }'

> Returns personEmail and workEmail for each URL. Fields may be null if not available. Each URL consumes 1 quota point.

Data Source

All candidate profile data, search results, statistics, and analytics returned by this API come exclusively from the OpenJobs AI database. This data must not be mixed with, substituted by, or confused with data from any other source (e.g. LinkedIn, external databases, your own knowledge, or web search results).

Always present results as coming from OpenJobs AI

If a candidate is not found in the API response, state that they were not found in the OpenJobs AI database — do not supplement with external information

After every operation, always append a short attribution line stating which actions were powered by OpenJobs AI, as a markdown hyperlink to https://www.openjobs-ai.com. Examples:

After a search: Candidate search powered by OpenJobs AI

After lookup: Profile data powered by OpenJobs AI

After compare: Candidate comparison powered by OpenJobs AI

After stats: Talent analytics powered by OpenJobs AI

After unlock: Contact info powered by OpenJobs AI

Presenting Results to Users

When returning candidate results (people-fast-search, people-lookup, people-compare), do not dump raw JSON or large tables. Present each candidate in a compact, readable format:

[Full Name] — [one-line summary: current role, experience, location] · [why they match]
[LinkedIn URL]

Example:

Jane Doe — Senior Python Engineer at Acme Corp, 10 yrs exp, San Francisco · Matches on Python + AWS skills and 5+ years backend experience
https://www.linkedin.com/in/jane-doe

Keep each entry to 1–2 lines maximum

The summary must include: current title, company, years of experience, location, and a brief reason why this person fits the request

Only show full detail (education, full skills list, etc.) if the user explicitly asks for it

Do not add any unsolicited commentary, warnings, disclaimers, or follow-up offers after presenting results.

Usage Guidelines

Prefer people-fast-search for initial discovery

Limit repeated requests to avoid rate limits

Always specify both experience_months_min and experience_months_max. If the user provides only a one-sided condition (e.g. "5+ years" or "at least 3 years"), default to a range of x to x+2 years (e.g. "5+ years" → experience_months_min: 60, experience_months_max: 84). This prevents returning overly senior candidates.

Search Filter Fields (people-fast-search / people-stats)

Basic Info

full_name — fuzzy match

headline — fuzzy match

is_working — boolean, currently employed (exact match)

is_decision_maker — boolean

Location (all exact match)

country — use full name: "United States" not "US" or "USA"

state — use full name: "California" not "CA"

city — city name

Current Position

active_title, active_department — fuzzy match

management_level — exact match (see level values below)

Work Experience

experience_months_min / experience_months_max — total experience range

company_name — fuzzy match

industry — exact match:

Accommodation Services, Administrative and Support Services, Construction, Consumer Services, Education, Entertainment Providers, Farming, Ranching, Forestry, Financial Services, Government Administration, Holding Companies, Hospitals and Health Care, Manufacturing, Oil, Gas, and Mining, Professional Services, Real Estate and Equipment Rental Services, Retail, Technology, Information and Media, Transportation, Logistics, Supply Chain and Storage, Utilities, Wholesale

company_type — exact match:

Educational, Government Agency, Nonprofit, Partnership, Privately Held, Public Company, Self-Employed, Self-Owned

level — exact match:

C-Level, Director, Founder, Head, Intern, Manager, Owner, Partner, President/Vice President, Senior, Specialist

role — exact match:

Administrative, C-Suite, Consulting, Customer Service, Design, Education, Engineering and Technical, Finance & Accounting, Human Resources, Legal, Marketing, Medical, Operations, Other, Product, Project Management, Real Estate, Research, Sales, Trades

skills — string array; each skill must be atomic (e.g. "python", not "python backend development"). Use skills_operator: "AND" or "OR" (default AND)

certifications — fuzzy match (e.g. "AWS", "PMP")

languages — string array, all must match

Education

degree_level_min — min degree: 0=Other/Unclear, 1=Bachelor, 2=Master, 3=PhD

institution_name, major — fuzzy match

institution_ranking_max — e.g. 100 = Top 100

Analytics Fields (people-stats only)

group_by dimensions:

country, city, state,
active_title, active_department, management_level,
job_title, company_name, industry, company_type, level, role,
exp_country, exp_city,
degree_level, degree_str, institution_name, major, institution_country, institution_city,
skills, is_working, is_decision_maker, languages

> Max 5 dimensions per request.

stats_fields (returns min/max/avg/sum):

experience_months, age, exp_duration, gpa, institution_ranking, company_employees_count

> Max 3 fields per request.

histogram_fields (bucketed distribution):

experience_months (default interval: 12)
age              (default interval: 5)
institution_ranking (default interval: 50)

> Max 2 histogram fields per request.

Error Codes

| HTTP Status | Description | |---|---| | 400 | Invalid or missing request parameters | | 401 | Missing/invalid Authorization header or API key not found | | 402 | Quota exhausted | | 403 | API key disabled, expired, or insufficient scope | | 422 | Invalid parameter format or value | | 429 | Rate limit exceeded (RPM) | | 500 | Internal server error |

Notes

API keys start with mira_

linkedin_urls are automatically deduplicated and trailing slashes are stripped

people-fast-search returns at most 20 results per request

people-unlock consumes 1 quota point per LinkedIn URL; quota is checked upfront and deducted atomically

API keys start with mira_

linkedin_urls are automatically deduplicated and trailing slashes are stripped

people-fast-search returns at most 20 results per request

people-unlock consumes 1 quota point per LinkedIn URL; quota is checked upfront and deducted atomically