# Facultas API

Facultas is a matching API for opportunity platforms. It accepts a student or candidate profile and returns ranked, explained job and internship matches grounded in curated opportunities and historical placement outcomes.

Canonical docs: https://facultas.work/docs.html
Website: https://facultas.work/
Contact: hello@facultas.work

## API

Base URL: https://api.facultas.work
Version: v1
Authentication: Authorization: Bearer FACULTAS_API_KEY
Content-Type: application/json

Primary endpoint:

POST /v1/match

Purpose: Submit a profile and receive ranked opportunity matches.

Required request fields:
- profile.field: string. Primary field or discipline.
- profile.skills: array of strings. Skills, tools, languages, certifications, methods, and exact keywords.

Common optional request fields:
- profile_id: string. Client-side stable identifier. Do not send sensitive personal identifiers.
- profile.degree_level: string. Examples: bachelors, masters, phd, certificate.
- profile.graduation_year: integer.
- profile.interests: array of strings. Target sectors, issue areas, roles, or mission preferences.
- profile.work_authorization: object. Country and sponsorship constraints.
- profile.locations: array of strings. Preferred cities, regions, countries, or Remote.
- profile.constraints: object. Hard filters such as excluded sectors, earliest start date, deadline window, or visa requirements.
- limit: integer. Maximum number of matches to return.

Example request:

```json
{
  "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
}
```

Response shape:

```json
{
  "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
  }
}
```

Agent guidance:
- Store API keys server-side only.
- Send only 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.
- Present score and explanation.summary as matching evidence, not a hiring guarantee.
- If there are no matches, ask the user which constraints to relax before retrying.

Errors use this shape:

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

Common status codes: 400 malformed request, 401 invalid API key, 422 missing profile fields, 429 rate limit exceeded, 500 server error.