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.

The partner API and member browser API use different bearer credentials. Partner integrations use an issued Facultas API key. The member resume library uses a short-lived Google ID token for the signed-in person and never places a partner key in browser code.

Base URL

https://api.facultas.work

Version

v1

Authentication

X-API-Key: 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 "X-API-Key: $FACULTAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": "candidate_123",

    "background": {
      "field_of_study": "International Affairs",
      "degree_level": "masters",
      "years_experience": 2,
      "experience_summary": "Graduate student in international affairs with quantitative research experience.",
      "languages": ["English", "Spanish"],
      "work_authorized_countries": ["USA"]
    },

    "interests": ["climate policy", "public sector"],
    "hard_skills": ["Python", "GIS", "policy analysis"],

    "hard_constraints": {
      "job_types": ["internship"],
      "excluded_sectors": ["defense"],
      "availability_start": "2026-06-01",
      "needs_visa_sponsorship": false
    },

    "preferences": {
      "preferred_locations": ["Washington", "Remote"],
      "preferred_sectors": ["Public/Government"]
    },

    "options": {
      "limit": 10,
      "include_explanations": true
    }
  }'

04 Request schema

Request 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 Prioritizing constraints

Deal-breakers, gates, and preferences

Facultas applies candidate requirements in three tiers. Choosing the right tier matters more than any other request decision: put something too high and you get an empty page, too low and it barely registers.

Tier 1 — Hard constraints (hard_constraints)

Deal-breakers. Applied in SQL before retrieval, so an excluded posting can never appear at any rank. Use these only for things that make a posting genuinely unusable.

Tier 2 — Eligibility gates (options.require_*)

Opt-in gates evaluated after retrieval and before ranking. Each produces a reasoned verdict — eligible, ineligible, unknown, or not_applicable — returned per match in eligibility_evaluation. Only a confirmed ineligible removes a posting. Every one of these defaults to off.

Tier 3 — Preferences (preferences)

Soft signals. They move a posting up or down, never remove it. preferred_locations, preferred_sectors, and minimum_compensation (which stays soft unless you set require_min_compensation).

Location and sector currently score as matched or not matched rather than on a gradient, so they carry more weight than their nominal share suggests. Listing many preferred locations dilutes the signal; listing one or two concentrates it. If your results skew heavily toward a single employer or city, over-specified preferences are the first thing to check.

How unknown data is treated

Missing information is never read as a mismatch. A posting that does not state a requirement produces unknown, and the default policy allows it through — the reasoning being that our extraction gaps should not cost a candidate an opportunity. The single exception is job_type, which blocks on unknown, because a request for internships should not return roles of indeterminate type. You can override this per constraint with options.eligibility_unknown_policy, for example {"security_clearance": "block"}.

Practical ordering

1. Start with only genuine deal-breakers in hard_constraints — usually just job_types.
2. Supply background facts (years_experience, languages, work_authorized_countries, clearance_status). Several gates activate on their own once the facts are present.
3. Express everything else as preferences and let ranking sort it out.
4. Add require_* gates only after seeing results that are genuinely unusable rather than simply imperfect.
5. Inspect score_breakdown and eligibility_evaluation on real responses to see which signals actually moved.

08 Member resume API

Independent resume variants for authenticated members

These endpoints back the Facultas member resume library. They accept Authorization: Bearer GOOGLE_ID_TOKEN; the local development bypass may use X-Dev-Email only when both the page and API are running directly on loopback and the backend bypass flag is enabled.

Batch upload

Send repeated files multipart fields and an optional metadata JSON array in the same order. Each metadata item may contain a label of up to 80 characters and a non-null archetype such as general, policy, or data. The response reports each file independently, so accepted files remain accepted when a sibling fails.

curl https://api.facultas.work/v1/member/resumes \
  -H "Authorization: Bearer $GOOGLE_ID_TOKEN" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F 'metadata=[{"label":"Policy","archetype":"policy"},{"label":"Data","archetype":"data"}]'

List and upload responses expose only safe metadata: public id, label, archetype, default state, parse status and safe parse_error, original filename, content type, parser/schema versions, timestamps, and archive state. Storage paths and internal database identifiers are never part of the browser contract.

Single and all-resume matching

{ "mode": "single", "resume_id": "7b55d3b7-...", "limit": 10 }

{ "mode": "all", "limit": 10 }

Single mode requires one owned, ready resume and never merges another variant. All mode evaluates ready variants, deduplicates opportunities, and annotates each job with best_resume and optional alternate_resume_fits. The response also includes mode, request_id, match provenance, normal match fields, and metadata.

Account settings and explicit request overrides are authoritative for visa, citizenship, work authorization, clearance, geography, paid-only, compensation, and job-type constraints. A resume contributes retrieval and ranking signals only; it cannot silently relax or replace those constraints. Per-search overrides may narrow account hard constraints, but cannot loosen them.

{
  "eligibility": {
    "is_us_citizen": true,
    "citizenships": ["United States"],
    "work_authorized_countries": ["United States"],
    "needs_visa_sponsorship": false,
    "clearance_status": "active",
    "clearance_level": "Public Trust"
  },
  "hard_constraints": {
    "job_types": ["Full-time"],
    "allowed_countries": ["United States"],
    "remote_ok": true,
    "excluded_sectors": ["Defense"],
    "needs_visa_sponsorship": false,
    "paid_only": true,
    "availability_start": "2026-08-01"
  },
  "preferences": {
    "preferred_locations": ["Washington DC"],
    "preferred_sectors": ["Climate"],
    "minimum_compensation": 65000
  },
  "options": {}
}

minimum_compensation is annual USD. The current engine does not accept a currency or pay-period field.

09 Errors

Error format and status codes

{
  "detail": [
    {
      "type": "int_parsing",
      "loc": ["body", "options", "limit"],
      "msg": "Input should be a valid integer",
      "input": "ten"
    }
  ]
}

10 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.