Use Facultas to return ranked, explained opportunity matches.

01 Quickstart

Integration flow

1. Request API access and store the issued key server-side.
2. Collect the user profile, preferences, and hard constraints in your product.
3. Send the profile to POST /v1/match.
4. Render the returned matches with employer, title, score, explanation, and source URL.

The API is designed to sit behind your application server. Do not expose API keys in browser JavaScript, mobile apps, or public repositories.

02 Access and auth

Base URL and headers

Production API access is currently issued to approved partners. Confirm your final base URL during onboarding; examples use the public production host.

Base URL

https://api.facultas.work

Version

v1

Authentication

Authorization: Bearer FACULTAS_API_KEY

Content type

application/json

03 Endpoint

POST /v1/match

Submit a profile and receive ranked job or internship matches. Hard constraints are applied before ranking, so returned matches should be eligible candidates for display.

curl https://api.facultas.work/v1/match \
  -H "Authorization: Bearer $FACULTAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": "candidate_123",
    "profile": {
      "field": "International Affairs",
      "degree_level": "masters",
      "graduation_year": 2026,
      "skills": ["Python", "GIS", "policy analysis"],
      "interests": ["climate policy", "public sector"],
      "work_authorization": {
        "country": "US",
        "needs_sponsorship": false
      },
      "locations": ["Washington, DC", "Remote"],
      "constraints": {
        "exclude_sectors": ["defense"],
        "earliest_start_date": "2026-06-01"
      }
    },
    "limit": 10
  }'

04 Request schema

Recommended payload fields

05 Response shape

Ranked matches with explanations

Each match includes a normalized opportunity, canonical source URL, score, and explanation signals that your product can show directly or adapt for its own UI.

{
  "request_id": "req_01hx7m8k9p",
  "matches": [
    {
      "opportunity_id": "opp_wri_4271",
      "title": "Climate Data Intern",
      "employer": "World Resources Institute",
      "location": "Washington, DC",
      "employment_type": "internship",
      "source_url": "https://example.org/jobs/climate-data-intern",
      "score": 0.87,
      "explanation": {
        "summary": "Strong climate-policy fit with GIS and Python requirements.",
        "criteria": [
          { "name": "skills", "score": 0.91, "evidence": ["Python", "GIS"] },
          { "name": "field_fit", "score": 0.86, "evidence": ["climate policy"] },
          { "name": "placement_prior", "score": 0.78, "evidence": ["6 prior placements"] }
        ]
      }
    }
  ],
  "meta": {
    "limit": 10,
    "returned": 1
  }
}

06 Ranking behavior

How Facultas decides what to return

07 Errors

Error format and status codes

{
  "error": {
    "code": "invalid_profile",
    "message": "profile.field and profile.skills are required",
    "request_id": "req_01hx7m8k9p"
  }
}

08 Agent guidance

How agents should use the API

• Use /llms.txt for a compact machine-readable summary, then use this page for full field definitions.
• Send only profile data needed for matching. Avoid names, emails, resumes, transcripts, and private notes unless explicitly required by a partner integration.
• Treat constraints as hard filters, not ranking preferences.
• Show source_url whenever presenting an opportunity so users can verify the live posting.
• Present score and explanation.summary as matching evidence, not as a guarantee of hiring or eligibility.
• When an API response contains no matches, ask the user which constraints to relax before retrying.