{"openapi":"3.1.0","info":{"title":"HireHappy API","version":"1"},"paths":{"/organizations/self":{"get":{"tags":["organizations"],"summary":"Retrieve your organization","description":"The organization the API key belongs to. Any key may read it: a quick\nway to check a key works.","operationId":"get_organization","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationResponse"}}}}},"security":[{"ApiKey":[]}]}},"/api-keys/self":{"get":{"tags":["api-keys"],"summary":"Retrieve the API key","description":"The API key the request is made with: its name, what it may do and\nwhen it expires.","operationId":"get_api_key","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyResponse"}}}}},"security":[{"ApiKey":[]}]}},"/jobs":{"get":{"tags":["jobs"],"summary":"List jobs","description":"Newest first. `q` matches the title. Needs `jobs:read`.","operationId":"list_jobs","security":[{"ApiKey":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","enum":["draft","open","closed"]}},{"type":"null"}],"description":"Only jobs with these statuses; repeat for several, e.g. ?status=open&status=draft.","title":"Status"},"description":"Only jobs with these statuses; repeat for several, e.g. ?status=open&status=draft."},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Matches part of the title.","title":"Q"},"description":"Matches part of the title."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LimitOffsetPage_JobResponse_"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-required-scope":"jobs:read"},"post":{"tags":["jobs"],"summary":"Create a job","description":"Create a job with the default pipeline stages and application form,\nto set up further in the app. Needs `jobs:write`.","operationId":"create_job","security":[{"ApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobCreateRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-required-scope":"jobs:write"}},"/jobs/{job_id}":{"get":{"tags":["jobs"],"summary":"Retrieve a job","description":"Needs `jobs:read`.","operationId":"get_job","security":[{"ApiKey":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-required-scope":"jobs:read"},"patch":{"tags":["jobs"],"summary":"Update a job","description":"Change a job's details, or open (post) or close it. Needs\n`jobs:write`.","operationId":"update_job","security":[{"ApiKey":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Job Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobUpdateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-required-scope":"jobs:write"}},"/jobs/{job_id}/job-stages":{"get":{"tags":["job-stages"],"summary":"List a job's stages","description":"The job's pipeline, in order. Needs `jobs:read`.","operationId":"list_job_stages","security":[{"ApiKey":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/JobStageResponse"},"title":"Response List Job Stages"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-required-scope":"jobs:read"}},"/candidates":{"get":{"tags":["candidates"],"summary":"List candidates","description":"Newest first. `q` matches part of the name or email. Needs\n`candidates:read`.","operationId":"list_candidates","security":[{"ApiKey":[]}],"parameters":[{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Matches part of the name or email.","title":"Q"},"description":"Matches part of the name or email."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LimitOffsetPage_CandidateResponse_"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-required-scope":"candidates:read"},"post":{"tags":["candidates"],"summary":"Create a candidate","description":"Add a candidate, to put forward for a job with POST /applications.\n409 when another candidate has the email. Needs `candidates:write`.","operationId":"create_candidate","security":[{"ApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CandidateCreateRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CandidateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-required-scope":"candidates:write"}},"/candidates/{candidate_id}":{"get":{"tags":["candidates"],"summary":"Retrieve a candidate","description":"Needs `candidates:read`.","operationId":"get_candidate","security":[{"ApiKey":[]}],"parameters":[{"name":"candidate_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Candidate Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CandidateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-required-scope":"candidates:read"},"patch":{"tags":["candidates"],"summary":"Update a candidate","description":"Needs `candidates:write`.","operationId":"update_candidate","security":[{"ApiKey":[]}],"parameters":[{"name":"candidate_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Candidate Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CandidateUpdateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CandidateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-required-scope":"candidates:write"},"delete":{"tags":["candidates"],"summary":"Delete a candidate","description":"Delete a candidate for good, with their applications and notes (a\nrequest to erase their data, say). Needs `candidates:write`.","operationId":"delete_candidate","security":[{"ApiKey":[]}],"parameters":[{"name":"candidate_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Candidate Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-required-scope":"candidates:write"}},"/candidates/{candidate_id}/resume":{"put":{"tags":["candidates"],"summary":"Upload a candidate's resume","description":"Set the candidate's resume, a PDF sent as multipart/form-data\n(`resume`), replacing any they had. It's searchable at once; scorecards\nuse it from the next scoring on. Needs `candidates:write`.","operationId":"put_candidate_resume","security":[{"ApiKey":[]}],"parameters":[{"name":"candidate_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Candidate Id"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_put_candidate_resume"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CandidateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-required-scope":"candidates:write"}},"/candidates/{candidate_id}/notes":{"get":{"tags":["notes"],"summary":"List a candidate's notes","description":"The hiring team's notes on the candidate, newest first. Needs\n`candidates:read`.","operationId":"list_notes","security":[{"ApiKey":[]}],"parameters":[{"name":"candidate_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Candidate Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/NoteResponse"},"title":"Response List Notes"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-required-scope":"candidates:read"},"post":{"tags":["notes"],"summary":"Add a note","description":"Add a note for the hiring team; the app shows it as added through the\nAPI. Needs `candidates:write`.","operationId":"create_note","security":[{"ApiKey":[]}],"parameters":[{"name":"candidate_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Candidate Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoteCreateRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoteResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-required-scope":"candidates:write"}},"/applications":{"get":{"tags":["applications"],"summary":"List applications","description":"Newest first, or best match first with `sort=score` (failed\nknockouts and the unscored last). `q` searches\nthe candidate's name, email and resume (every word has to match). Needs\n`applications:read`.","operationId":"list_applications","security":[{"ApiKey":[]}],"parameters":[{"name":"job_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Only applications to this job.","title":"Job Id"},"description":"Only applications to this job."},{"name":"candidate_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Only this candidate's applications.","title":"Candidate Id"},"description":"Only this candidate's applications."},{"name":"stage_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Only applications in this stage of their job.","title":"Stage Id"},"description":"Only applications in this stage of their job."},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","enum":["active","rejected","hired","withdrawn"]}},{"type":"null"}],"description":"Only applications with these statuses; repeat for several, e.g. ?status=active&status=hired.","title":"Status"},"description":"Only applications with these statuses; repeat for several, e.g. ?status=active&status=hired."},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Every word must match the candidate's name, email or resume, e.g. react berlin.","title":"Q"},"description":"Every word must match the candidate's name, email or resume, e.g. react berlin."},{"name":"sort","in":"query","required":false,"schema":{"enum":["newest","score"],"type":"string","description":"newest first, or score: best match first, failed knockouts and the unscored last.","default":"newest","title":"Sort"},"description":"newest first, or score: best match first, failed knockouts and the unscored last."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LimitOffsetPage_ApplicationResponse_"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-required-scope":"applications:read"},"post":{"tags":["applications"],"summary":"Create an application","description":"Put a candidate forward for a job, in its first stage unless\n`stage_id` says otherwise. Scored in the background when the job has a\nrubric. 409 when they already have an application for it. Needs\n`applications:write`.","operationId":"create_application","security":[{"ApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplicationCreateRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplicationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-required-scope":"applications:write"}},"/applications/{application_id}":{"get":{"tags":["applications"],"summary":"Retrieve an application","description":"Needs `applications:read`.","operationId":"get_application","security":[{"ApiKey":[]}],"parameters":[{"name":"application_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Application Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplicationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-required-scope":"applications:read"},"patch":{"tags":["applications"],"summary":"Update an application","description":"Move it to another stage, or change its status: reject, hire (moves\nit to the last stage, and starts onboarding), or back to active. As in\nthe app, a candidate who applied through the job board is emailed on\nmoving on to a later public stage and on being hired; on being rejected\nonly when `notify_candidate` asks. Needs `applications:write`.","operationId":"update_application","security":[{"ApiKey":[]}],"parameters":[{"name":"application_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Application Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplicationUpdateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplicationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-required-scope":"applications:write"}},"/applications/{application_id}/scorecard":{"get":{"tags":["scorecards"],"summary":"Retrieve an application's scorecard","description":"The application scored by AI against its job's rubric, criterion by\ncriterion. 404 until it's been scored. Needs `applications:read`.","operationId":"get_scorecard","security":[{"ApiKey":[]}],"parameters":[{"name":"application_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Application Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScorecardResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-required-scope":"applications:read"}},"/interviews":{"get":{"tags":["interviews"],"summary":"List interviews","description":"The organization's interviews, calls and assessments, soonest first\n(an assessment by when it's due). For a calendar, e.g. the week's\ninterviews: `kind=interview&starts_after=2026-11-02T00:00:00Z&starts_before=2026-11-09T00:00:00Z`.\nTimes are ISO 8601 with a timezone; bounding the start leaves\nassessments out, as they have none. Needs `applications:read`.","operationId":"list_interviews","security":[{"ApiKey":[]}],"parameters":[{"name":"kind","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","enum":["interview","call","assessment"]}},{"type":"null"}],"description":"Only these kinds; repeat for several, e.g. ?kind=interview&kind=call.","title":"Kind"},"description":"Only these kinds; repeat for several, e.g. ?kind=interview&kind=call."},{"name":"job_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Only interviews for this job.","title":"Job Id"},"description":"Only interviews for this job."},{"name":"candidate_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Only this candidate's interviews.","title":"Candidate Id"},"description":"Only this candidate's interviews."},{"name":"application_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Only this application's interviews.","title":"Application Id"},"description":"Only this application's interviews."},{"name":"starts_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only those starting at or after this time, with a timezone, e.g. 2026-11-02T00:00:00Z. Leaves out assessments.","title":"Starts After"},"description":"Only those starting at or after this time, with a timezone, e.g. 2026-11-02T00:00:00Z. Leaves out assessments."},{"name":"starts_before","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only those starting before this time, with a timezone. Leaves out assessments.","title":"Starts Before"},"description":"Only those starting before this time, with a timezone. Leaves out assessments."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LimitOffsetPage_InterviewResponse_"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-required-scope":"applications:read"}},"/applications/{application_id}/interviews":{"get":{"tags":["interviews"],"summary":"List an application's interviews","description":"Every round of the application, the stage it's in now and earlier\nones, latest first. Needs `applications:read`.","operationId":"list_application_interviews","security":[{"ApiKey":[]}],"parameters":[{"name":"application_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Application Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/InterviewResponse"},"title":"Response List Application Interviews"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-required-scope":"applications:read"}}},"components":{"schemas":{"ApiKeyResponse":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id"},"name":{"type":"string","title":"Name"},"scopes":{"items":{"type":"string","enum":["jobs:read","jobs:write","candidates:read","candidates:write","applications:read","applications:write"]},"type":"array","title":"Scopes","description":"What the key may do."},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expires At","description":"Null never expires."}},"type":"object","required":["id","name","scopes","expires_at"],"title":"ApiKeyResponse","description":"The key the request was made with."},"ApplicationCandidateResponse":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id"},"first_name":{"type":"string","title":"First Name"},"last_name":{"type":"string","title":"Last Name"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"}},"type":"object","required":["id","first_name","last_name","email"],"title":"ApplicationCandidateResponse"},"ApplicationCreateRequest":{"properties":{"job_id":{"type":"string","format":"uuid","title":"Job Id"},"candidate_id":{"type":"string","format":"uuid","title":"Candidate Id"},"stage_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Stage Id","description":"A stage of the job; the first one when left out."}},"type":"object","required":["job_id","candidate_id"],"title":"ApplicationCreateRequest"},"ApplicationResponse":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"},"job_id":{"type":"string","format":"uuid4","title":"Job Id"},"candidate_id":{"type":"string","format":"uuid4","title":"Candidate Id"},"candidate":{"$ref":"#/components/schemas/ApplicationCandidateResponse"},"stage_id":{"type":"string","format":"uuid4","title":"Stage Id","description":"A stage of the job (GET /jobs/{job_id}/job-stages)."},"status":{"type":"string","enum":["active","rejected","hired","withdrawn"],"title":"Status","description":"active (in the pipeline), rejected, hired or withdrawn."},"rejection_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rejection Reason","description":"Kept with a rejection; internal, never shown to the candidate."},"withdrawal_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Withdrawal Reason","description":"The candidate's own words on withdrawing, if any."},"reapplied_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reapplied At","description":"Set when a rejected or withdrawn candidate applied again, until its status next changes."},"status_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status Url","description":"The candidate's private status page; null for candidates who didn't apply through the job board."},"scorecard":{"anyOf":[{"$ref":"#/components/schemas/ApplicationScorecardResponse"},{"type":"null"}],"description":"Null until scoring has been asked for (it is, on its own, when the job has a rubric)."}},"type":"object","required":["id","created_at","updated_at","job_id","candidate_id","candidate","stage_id","status","rejection_reason","withdrawal_reason","reapplied_at","status_url","scorecard"],"title":"ApplicationResponse"},"ApplicationScorecardResponse":{"properties":{"status":{"type":"string","enum":["pending","completed","failed"],"title":"Status","description":"pending while being (re)scored."},"score":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Score","description":"0-100 against the job's rubric; null until scored, or when the rubric only has knockouts."},"knockout_result":{"anyOf":[{"type":"string","enum":["passed","unclear","failed"]},{"type":"null"}],"title":"Knockout Result","description":"The worst of its knockout criteria: failed, else unclear, else passed; null without any."},"scored_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Scored At"}},"type":"object","required":["status","score","knockout_result","scored_at"],"title":"ApplicationScorecardResponse","description":"The AI scorecard's headline; the rest from .../scorecard."},"ApplicationUpdateRequest":{"properties":{"stage_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Stage Id","description":"Move it to another stage of its job, at the bottom of it. The last stage marks it hired."},"status":{"anyOf":[{"type":"string","enum":["active","rejected","hired","withdrawn"]},{"type":"null"}],"title":"Status","description":"rejected, hired (moves it to the last stage and starts onboarding) or back to active."},"rejection_reason":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}],"title":"Rejection Reason","description":"Kept with a rejection; internal, never shown to the candidate."},"notify_candidate":{"type":"boolean","title":"Notify Candidate","description":"With status \"rejected\": email the candidate their default rejection email, now. Other emails (moved on to a later public stage, hired) go to candidates who applied through the job board on their own.","default":false}},"type":"object","title":"ApplicationUpdateRequest","description":"Only the fields sent change."},"Body_put_candidate_resume":{"properties":{"resume":{"type":"string","contentMediaType":"application/octet-stream","title":"Resume"}},"type":"object","required":["resume"],"title":"Body_put_candidate_resume"},"CandidateCreateRequest":{"properties":{"first_name":{"type":"string","maxLength":100,"minLength":1,"title":"First Name"},"last_name":{"type":"string","maxLength":100,"minLength":1,"title":"Last Name"},"email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}],"title":"Email","description":"409 when another candidate has it."},"phone":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"title":"Phone"},"location":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Location"},"linkedin_url":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Linkedin Url"},"source":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Source","description":"Where they came from, in your own words: referral, linkedin, agency, ...","examples":["referral"]}},"type":"object","required":["first_name","last_name"],"title":"CandidateCreateRequest"},"CandidateResponse":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"},"first_name":{"type":"string","title":"First Name"},"last_name":{"type":"string","title":"Last Name"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"Unique within the organization."},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone"},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location"},"linkedin_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Linkedin Url"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","description":"Where they came from: \"careers_page\" for the job board, or whatever was set (\"referral\", \"linkedin\", ...)."},"resume_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resume Url","description":"Their resume (PDF); null when there's none."}},"type":"object","required":["id","created_at","updated_at","first_name","last_name","email","phone","location","linkedin_url","source","resume_url"],"title":"CandidateResponse"},"CandidateUpdateRequest":{"properties":{"first_name":{"anyOf":[{"type":"string","maxLength":100,"minLength":1},{"type":"null"}],"title":"First Name"},"last_name":{"anyOf":[{"type":"string","maxLength":100,"minLength":1},{"type":"null"}],"title":"Last Name"},"email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}],"title":"Email"},"phone":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"title":"Phone"},"location":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Location"},"linkedin_url":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Linkedin Url"},"source":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Source"}},"type":"object","title":"CandidateUpdateRequest","description":"Only the fields sent change; null clears an optional one."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"InterviewResponse":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"},"application_id":{"type":"string","format":"uuid4","title":"Application Id"},"job_id":{"type":"string","format":"uuid4","title":"Job Id"},"candidate":{"$ref":"#/components/schemas/ApplicationCandidateResponse"},"stage_id":{"anyOf":[{"type":"string","format":"uuid4"},{"type":"null"}],"title":"Stage Id","description":"The stage it's for; null once that stage is deleted."},"kind":{"type":"string","enum":["interview","call","assessment"],"title":"Kind"},"starts_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Starts At","description":"Interviews: when it's scheduled. Calls: when it was made. Null for assessments."},"ends_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Ends At","description":"Interviews: when it ends (an hour after it starts when no length was set). Calls: when given a length. Null for assessments."},"duration_minutes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Duration Minutes"},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location","description":"Interviews: where, as free text: an address, a meeting link, \"Phone\"."},"interviewers":{"items":{"$ref":"#/components/schemas/InterviewerResponse"},"type":"array","title":"Interviewers","description":"Who's interviewing, or reviewing the work."},"details":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Details","description":"Interviews: what the invite tells the candidate. Calls: how it went."},"due_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Due At","description":"Assessments: when the work is due; null for no due date."},"submitted_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Submitted At","description":"Assessments: when the work was handed in."}},"type":"object","required":["id","created_at","updated_at","application_id","job_id","candidate","stage_id","kind","starts_at","ends_at","duration_minutes","location","interviewers","details","due_at","submitted_at"],"title":"InterviewResponse","description":"An interview with the candidate in one stage of their application,\na call made to them, or work they were set to hand in (an assessment).\nOne per application per stage: rescheduling changes it, cancelling\ndeletes it."},"InterviewerResponse":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id"},"first_name":{"type":"string","title":"First Name"},"last_name":{"type":"string","title":"Last Name"},"email":{"type":"string","title":"Email"}},"type":"object","required":["id","first_name","last_name","email"],"title":"InterviewerResponse","description":"A member of the hiring team."},"JobCreateRequest":{"properties":{"title":{"type":"string","maxLength":200,"minLength":1,"title":"Title"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"HTML, as JobResponse.description; anything else is stripped."},"location":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Location"},"employment_type":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"title":"Employment Type","examples":["Full-time"]},"workplace_type":{"anyOf":[{"type":"string","enum":["onsite","hybrid","remote"]},{"type":"null"}],"title":"Workplace Type"},"status":{"type":"string","enum":["draft","open","closed"],"title":"Status","description":"open posts it to the job board at once.","default":"draft"},"hiring_manager_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Hiring Manager Id","description":"A user id of a member of the organization."}},"type":"object","required":["title"],"title":"JobCreateRequest"},"JobResponse":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"},"title":{"type":"string","title":"Title"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"HTML: p, h2-h4, strong, em, u, s, a, ul, ol, li, blockquote, code, pre."},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location"},"employment_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Employment Type","examples":["Full-time"]},"workplace_type":{"anyOf":[{"type":"string","enum":["onsite","hybrid","remote"]},{"type":"null"}],"title":"Workplace Type"},"status":{"type":"string","enum":["draft","open","closed"],"title":"Status","description":"draft (not posted), open (on the job board, taking applications) or closed."},"hiring_manager_id":{"anyOf":[{"type":"string","format":"uuid4"},{"type":"null"}],"title":"Hiring Manager Id","description":"A member of the hiring team (a user id)."},"job_board_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Board Url","description":"The job's page on the job board, where candidates apply; null unless open."}},"type":"object","required":["id","created_at","updated_at","title","description","location","employment_type","workplace_type","status","hiring_manager_id"],"title":"JobResponse"},"JobStageResponse":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id"},"job_id":{"type":"string","format":"uuid4","title":"Job Id"},"name":{"type":"string","title":"Name"},"position":{"type":"integer","title":"Position","description":"0 first. New applications start in the first stage; the last one is hired."},"kind":{"type":"string","enum":["none","interview","call","assessment","offer"],"title":"Kind","description":"What the team does with an application there: nothing beyond moving it on (none), interview, call, assessment (work to hand in) or offer."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"A line or two on what happens in it, for the candidate."},"is_public":{"type":"boolean","title":"Is Public","description":"Shown to candidates on their status page as a step of their progress."}},"type":"object","required":["id","job_id","name","position","kind","description","is_public"],"title":"JobStageResponse"},"JobUpdateRequest":{"properties":{"title":{"anyOf":[{"type":"string","maxLength":200,"minLength":1},{"type":"null"}],"title":"Title"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"location":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Location"},"employment_type":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"title":"Employment Type"},"workplace_type":{"anyOf":[{"type":"string","enum":["onsite","hybrid","remote"]},{"type":"null"}],"title":"Workplace Type"},"status":{"anyOf":[{"type":"string","enum":["draft","open","closed"]},{"type":"null"}],"title":"Status","description":"open posts it to the job board, closed takes it down."},"hiring_manager_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Hiring Manager Id"}},"type":"object","title":"JobUpdateRequest","description":"Only the fields sent change; null clears an optional one."},"LimitOffsetPage_ApplicationResponse_":{"properties":{"items":{"items":{"$ref":"#/components/schemas/ApplicationResponse"},"type":"array","title":"Items"},"total":{"type":"integer","minimum":0,"title":"Total"},"limit":{"type":"integer","minimum":1,"title":"Limit"},"offset":{"type":"integer","minimum":0,"title":"Offset"}},"type":"object","required":["items","total","limit","offset"],"title":"LimitOffsetPage[ApplicationResponse]"},"LimitOffsetPage_CandidateResponse_":{"properties":{"items":{"items":{"$ref":"#/components/schemas/CandidateResponse"},"type":"array","title":"Items"},"total":{"type":"integer","minimum":0,"title":"Total"},"limit":{"type":"integer","minimum":1,"title":"Limit"},"offset":{"type":"integer","minimum":0,"title":"Offset"}},"type":"object","required":["items","total","limit","offset"],"title":"LimitOffsetPage[CandidateResponse]"},"LimitOffsetPage_InterviewResponse_":{"properties":{"items":{"items":{"$ref":"#/components/schemas/InterviewResponse"},"type":"array","title":"Items"},"total":{"type":"integer","minimum":0,"title":"Total"},"limit":{"type":"integer","minimum":1,"title":"Limit"},"offset":{"type":"integer","minimum":0,"title":"Offset"}},"type":"object","required":["items","total","limit","offset"],"title":"LimitOffsetPage[InterviewResponse]"},"LimitOffsetPage_JobResponse_":{"properties":{"items":{"items":{"$ref":"#/components/schemas/JobResponse"},"type":"array","title":"Items"},"total":{"type":"integer","minimum":0,"title":"Total"},"limit":{"type":"integer","minimum":1,"title":"Limit"},"offset":{"type":"integer","minimum":0,"title":"Offset"}},"type":"object","required":["items","total","limit","offset"],"title":"LimitOffsetPage[JobResponse]"},"NoteCreateRequest":{"properties":{"body":{"type":"string","maxLength":20000,"minLength":1,"title":"Body"}},"type":"object","required":["body"],"title":"NoteCreateRequest"},"NoteResponse":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"candidate_id":{"type":"string","format":"uuid4","title":"Candidate Id"},"author_id":{"anyOf":[{"type":"string","format":"uuid4"},{"type":"null"}],"title":"Author Id","description":"The team member who wrote it; null for a note added through the API (api_key_id) or by someone who's since left."},"api_key_id":{"anyOf":[{"type":"string","format":"uuid4"},{"type":"null"}],"title":"Api Key Id","description":"The API key it was added with; null once that key is revoked."},"body":{"type":"string","title":"Body"}},"type":"object","required":["id","created_at","candidate_id","author_id","api_key_id","body"],"title":"NoteResponse"},"OrganizationResponse":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id"},"name":{"type":"string","title":"Name"},"slug":{"type":"string","title":"Slug","description":"Where its job board is: {jobs site}/{slug}.","examples":["acme"]},"website":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Website"},"timezone":{"type":"string","title":"Timezone","description":"IANA name, e.g. Europe/Berlin.","examples":["Europe/Berlin"]}},"type":"object","required":["id","name","slug","website","timezone"],"title":"OrganizationResponse"},"ScorecardItemResponse":{"properties":{"name":{"type":"string","title":"Name"},"kind":{"type":"string","enum":["scored","knockout"],"title":"Kind","description":"scored (1-5) or knockout (passed, unclear or failed)."},"weight":{"type":"integer","title":"Weight"},"score":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Score","description":"1-5 for a scored criterion: the team's override when there is one, else the AI's."},"result":{"anyOf":[{"type":"string","enum":["passed","unclear","failed"]},{"type":"null"}],"title":"Result","description":"For a knockout criterion: the team's override when there is one, else the AI's."},"justification":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Justification"},"quote":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Quote","description":"Verbatim evidence."},"source":{"anyOf":[{"type":"string","enum":["resume","application","github"]},{"type":"null"}],"title":"Source","description":"Where the quote is from."}},"type":"object","required":["name","kind","weight","score","result","justification","quote","source"],"title":"ScorecardItemResponse","description":"One criterion of the job's rubric, as it was when scored."},"ScorecardResponse":{"properties":{"application_id":{"type":"string","format":"uuid4","title":"Application Id"},"status":{"type":"string","enum":["pending","completed","failed"],"title":"Status","description":"pending while being (re)scored."},"score":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Score","description":"0-100 against the job's rubric; null when the rubric only has knockouts."},"knockout_result":{"anyOf":[{"type":"string","enum":["passed","unclear","failed"]},{"type":"null"}],"title":"Knockout Result"},"summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Summary","description":"A couple of sentences on the overall fit."},"scored_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Scored At"},"items":{"items":{"$ref":"#/components/schemas/ScorecardItemResponse"},"type":"array","title":"Items"}},"type":"object","required":["application_id","status","score","knockout_result","summary","scored_at","items"],"title":"ScorecardResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"ApiKey":{"type":"http","description":"An API key (hh_sk_…), made by an owner or admin in the app under Settings → API keys.","scheme":"bearer"}}},"tags":[{"name":"organizations","description":"The organization the API key belongs to"},{"name":"api-keys","description":"The API key itself: what it may do"},{"name":"jobs","description":"Your jobs: posting them on the job board, closing them, and their details"},{"name":"job-stages","description":"A job's hiring pipeline, from the first stage to hired"},{"name":"candidates","description":"The people you're considering, one per person across all your jobs, with their resumes"},{"name":"notes","description":"The hiring team's notes on candidates"},{"name":"applications","description":"A candidate's candidacy for one job: its stage, status and AI score"},{"name":"scorecards","description":"Applications scored by AI against their job's rubric, with the evidence"},{"name":"interviews","description":"Interviews, calls and assessments of applications"}],"servers":[{"url":"https://api.hirehappy.io/v1"}]}