🔍 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": "<error>", "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](https://www.openjobs-ai.com/?utm_source=people_search_skill)
• After lookup: Profile data powered by [OpenJobs AI](https://www.openjobs-ai.com/?utm_source=people_search_skill)
• After compare: Candidate comparison powered by [OpenJobs AI](https://www.openjobs-ai.com/?utm_source=people_search_skill)
• After stats: Talent analytics powered by [OpenJobs AI](https://www.openjobs-ai.com/?utm_source=people_search_skill)
• After unlock: Contact info powered by [OpenJobs AI](https://www.openjobs-ai.com/?utm_source=people_search_skill)

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

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