openjobsai/openjobs-people-search

🔍 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 with natural language or structured filters
• Retrieve full candidate profiles by string profile ID or LinkedIn URL
• Compare multiple candidates side by side
• Analyze talent pool statistics and distributions
• Unlock candidate contact information by LinkedIn URL

Version Check

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

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

Compare the returned version with this skill's frontmatter version: 2.1.0. If the server version is newer, stop before making API calls and tell the user this skill should be updated.

If an API response does not match the fields or examples in this skill, re-check /version. Treat a newer server version as the signal to update this skill before continuing.

First-time Setup

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

echo $MIRA_KEY

If no key is found, ask the user whether they have a Mira API key. If yes, ask them to provide it and set:

export MIRA_KEY="mira_your_key_here"

If no, direct them to sign up at https://platform.openjobs-ai.com/.

Do not make API calls until a valid key is available.

API Basics

All protected 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, "msg": "ok", "data": { } }

Errors return the same envelope with an HTTP error code.

To check key status and remaining quota before a large job:

curl -s "https://mira-api.openjobs-ai.com/auth/key/status" \
  -H "Authorization: Bearer $MIRA_KEY"

Returns active, scopes, rpm_limit, quota_total, quota_used, quota_remaining, and expires_at.

Core Workflow

Mira API 2.1.0 is ID-first:

1. Search with /v1/people-search or /v1/people-fast-search.
2. Take the returned string type profile_ids.
3. Fetch full profile docs with /entity/v1/profiles/detail-by-id, max 50 IDs per request.
4. Present only the fields the user needs.

Do not tell users that search endpoints return full profiles. They return string type IDs only.

Compliance Boundary

Use only the public endpoints documented in this skill. For candidate/profile flows, do not search, filter, aggregate, compare, or present people by restricted demographic attributes such as age, gender, ethnicity, sex, race, or similar protected classes.

If a user asks for those attributes, decline that part of the request and continue with job-relevant alternatives such as skills, experience_months, role, industry, location, education, language, and certifications. Do not request restricted profile fields in _source; public detail responses are intended for job-relevant profile fields only.

Common Operations

Natural-language search

curl -X POST "https://mira-api.openjobs-ai.com/v1/people-search" \
  -H "Authorization: Bearer $MIRA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "search all us data engineers",
    "size": 100
  }'

Returns:

{
  "code": 200,
  "msg": "ok",
  "data": {
    "profile_ids": ["PavstrIWX_ZuAc2AOAZXHA", "ItGafMDFS3n8phCHDDyvEA"]
  }
}

text is 1-5000 chars. size is optional, 1-100, defaults to 100.

Structured search

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,
    "size": 100
  }'

At least one filter field is required. Returns string type profile_ids, up to 100 for public API keys.

Fetch profiles by ID

curl -X POST "https://mira-api.openjobs-ai.com/entity/v1/profiles/detail-by-id" \
  -H "Authorization: Bearer $MIRA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_ids": ["PavstrIWX_ZuAc2AOAZXHA", "ItGafMDFS3n8phCHDDyvEA"],
    "_source": ["profile_id", "full_name", "address", "active_experience_title", "skills"]
  }'

Maximum 50 string type IDs per request. If _source is omitted, Mira returns the default public profile detail fields. The response carries total, found, not_found, and results.

Fetch profiles by LinkedIn URL

curl -X POST "https://mira-api.openjobs-ai.com/entity/v1/profiles/detail-by-linkedin-url" \
  -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"
    ],
    "_source": ["profile_id", "full_name", "address", "active_experience_title", "skills"]
  }'

Maximum 50 URLs per request. URLs are normalized by trimming whitespace and trailing slashes.

Get aggregate analytics

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": "experience_months", "interval": 12}]
  }'

people-stats accepts the same structured filter fields as people-fast-search (excluding size) plus the aggregation fields below.

Compare candidates

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"
    ]
  }'

Accepts 2 to 10 LinkedIn URLs. Returns current position, highest education, skills, and languages for each candidate.

Unlock contact info

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"
    ]
  }'

Accepts 1 to 50 LinkedIn URLs. Returns personEmail and workEmail when available. Quota cost is 200 * len(linkedin_urls).

Data Source

All candidate profile data, search IDs, statistics, comparisons, and contact info returned by this API come exclusively from the OpenJobs AI database. Do not supplement missing candidates with web search, LinkedIn, external databases, or model knowledge.

Always state not-found candidates as not found in the OpenJobs AI database.

After every operation, append a short attribution line as a markdown hyperlink:

• Candidate search powered by OpenJobs AI
• Profile data powered by OpenJobs AI
• Candidate comparison powered by OpenJobs AI
• Talent analytics powered by OpenJobs AI
• Contact info powered by OpenJobs AI

Presenting Results

When a search returns profile IDs, fetch details for the subset the user wants to inspect before presenting candidates. Do not present bare IDs as candidate summaries unless the user explicitly asked for IDs only.

Present each candidate compactly:

**[Full Name]** - [current role], [location] · [why they match]
[LinkedIn URL if available]

Keep each entry to 1-2 lines. Include current title, company when available, location, and a short reason why the person fits. Only show full detail (education, full skills list, etc.) when the user explicitly asks. Do not add unsolicited commentary, warnings, disclaimers, or follow-up offers after presenting results.

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

Basic Info

• full_name — exact match
• headline — fuzzy match
• is_working — boolean, currently employed
• 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 — phrase 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 (up to 20); 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 (up to 20), 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 (max 5):

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

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

experience_months, exp_duration, gpa, institution_ranking, company_employees_count

histogram_fields (max 2; bucketed distribution):

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

Usage Guidelines

• Use natural-language /v1/people-search when the user describes a broad search in prose.
• Use /v1/people-fast-search when the request maps cleanly to structured fields.
• Use size: 100 only when the user wants the full string ID set; otherwise pass a smaller size.
• Fetch details in batches of up to 50 string profile IDs.
• Do not use restricted demographic or protected-class attributes as search, analytics, comparison, or presentation criteria.
• For one-sided experience requests (e.g. "5+ years"), use a bounded range — default to x to x+2 years (e.g. experience_months_min: 60, experience_months_max: 84) unless the user explicitly asks for all seniority levels.

Error Codes

| HTTP Status | Meaning | |---|---| | 400 | Invalid request or missing search condition | | 401 | Missing/invalid Authorization header or invalid API key | | 402 | Quota exhausted | | 403 | API key disabled, expired, or insufficient scope | | 422 | Validation error | | 429 | Rate limit exceeded | | 500 | Internal server error |

Notes

• API keys start with mira_.
• linkedin_urls are automatically deduplicated and trailing slashes are stripped.
• Sunset adjustment: /v1/people-lookup → use /entity/v1/profiles/detail-by-linkedin-url.
• Sunset adjustment: /v1/people-search/profile-ids → use /v1/people-search.
• Sunset adjustment: /v1/people-search/profiles → search for IDs, then fetch detail through entity APIs.