Build on FastHire.

List searches for the org, most recent first.

{
  "searches": [
    {
      "id": "cknq7x2z10001...",
      "name": "Senior Backend Engineer — Sydney",
      "sourceType": "JOB_DESCRIPTION",
      "createdAt": "2026-08-12T04:11:00Z",
      "updatedAt": "2026-08-12T04:19:00Z"
    }
  ]
}

Create a search from a structured criteria object — the same shape the app’s own search builder submits. Returns 201 with the new search’s id immediately; poll GET /v1/searches/:id for status.

curl https://api.thefasthire.com/v1/searches \
  -X POST -H "Authorization: Bearer $FASTHIRE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceType": "MANUAL",
    "criteria": {
      "searchName": "Senior Backend Engineer — Sydney",
      "roles": ["Senior Backend Engineer", "Staff Software Engineer"],
      "companies": [],
      "languages": ["English"],
      "education": {
        "fieldsOfStudy": ["Computer Science"],
        "degreeTypes": ["Bachelors"],
        "institutions": [],
        "excludedInstitutions": [],
        "minGraduationYear": null,
        "maxGraduationYear": null,
        "minEducationLevel": "Bachelors"
      },
      "location": {
        "radius": 50,
        "entries": [{ "city": "Sydney", "country": "Australia" }]
      }
    }
  }'

{ "id": "cknq7x2z10001..." }

Retrieve one search, including its full criteria.

{
  "id": "cknq7x2z10001...",
  "name": "Senior Backend Engineer — Sydney",
  "sourceType": "JOB_DESCRIPTION",
  "criteria": { /* the structured criteria object, as submitted */ },
  "createdAt": "2026-08-12T04:11:00Z",
  "updatedAt": "2026-08-12T04:19:00Z"
}

List a search’s matched candidates, ranked by matchScore.

{
  "candidates": [
    {
      "resultId": "cknq8f4h20007...",
      "candidateId": "cknq7z1a10004...",
      "name": "Priya Nair",
      "headline": "Staff Engineer at Canva",
      "location": "Sydney, Australia",
      "phone": null,
      "email": "priya.nair@example.com",
      "skills": ["Go", "Kubernetes", "PostgreSQL"],
      "experience": [ { "company": "Canva", "title": "Staff Engineer" } ],
      "education": [ { "school": "UNSW", "degree": "BSc Computer Science" } ],
      "matchScore": 94,
      "matchReasoning": "7 yrs backend, distributed systems at scale, AU-based.",
      "percentile": 98
    }
  ]
}

matchScore is 0–100. percentile is this candidate’s rank among the search’s results. There is no match-tier field.

Retrieve a candidate’s full profile, including intake if they’ve replied.

{
  "id": "cknq7z1a10004...",
  "name": "Priya Nair",
  "headline": "Staff Engineer at Canva",
  "email": "priya.nair@example.com",
  "phone": null,
  "linkedinUrl": "https://linkedin.com/in/priyanair",
  "location": "Sydney, Australia",
  "skills": ["Go", "Kubernetes", "PostgreSQL"],
  "experience": [ { "company": "Canva", "title": "Staff Engineer", "years": 3 } ],
  "education": [ { "school": "UNSW", "degree": "BSc Computer Science" } ],
  "intake": null /* populated once the candidate replies — see below */
}

List the org’s lists.

{
  "lists": [
    {
      "id": "cknqa1k3b0002...",
      "name": "Q3 backend shortlist",
      "createdAt": "2026-08-12T04:11:00Z",
      "candidateCount": 18
    }
  ]
}

{ "id": "cknqa1k3b0002..." }

{
  "sequences": [
    {
      "id": "cknqb7h4c0003...",
      "name": "Backend eng outreach — Sydney",
      "status": "DRAFT",
      "channelStrategy": "LINKEDIN_FIRST",
      "createdAt": "2026-08-12T04:11:00Z",
      "updatedAt": "2026-08-12T04:19:00Z"
    }
  ]
}

Create a sequence — it’s always created as DRAFT, whatever you pass. Sending "activate": true is rejected with a 400: activation is app-only, so no API key — fh_live_… or fh_test_… — can ever trigger real outreach through this endpoint.

{ "id": "cknqb7h4c0003..." }

Retrieve one sequence, including its steps and target lists.

{
  "id": "cknqb7h4c0003...",
  "name": "Backend eng outreach — Sydney",
  "status": "DRAFT",
  "channelStrategy": "LINKEDIN_FIRST",
  "context": "Prioritize distributed-systems experience and AU right-to-work." /* free-text brief used to personalize outreach copy */,
  "listIds": ["cknqa1k3b0002..."],
  "steps": [ /* … */ ],
  "createdAt": "2026-08-12T04:11:00Z",
  "updatedAt": "2026-08-12T04:19:00Z"
}

List conversations, most recently active first.

{
  "conversations": [
    {
      "candidateId": "cknq7z1a10004...",
      "candidateName": "Priya Nair",
      "lastMessageBody": "Thanks for reaching out — happy to chat this week.",
      "lastMessageAt": "2026-08-19T02:04:00Z",
      "lastMessageDirection": "INBOUND",
      "channels": ["EMAIL", "LINKEDIN"],
      "hasUnread": true,
      "hasReplied": true,
      "connectionFailureReason": null,
      "intakeStatus": "COMPLETED"
    }
  ]
}

Retrieve one candidate’s full thread across every channel, plus their sequence context and intake.

{
  "candidateId": "cknq7z1a10004...",
  "candidateName": "Priya Nair",
  "headline": "Staff Engineer at Canva",
  "messages": [
    {
      "channel": "EMAIL",
      "direction": "INBOUND",
      "body": "Thanks for reaching out — happy to chat this week.",
      "sentAt": "2026-08-19T02:04:00Z"
    }
  ],
  "sequenceContext": { /* which sequence/step produced this thread, if any */ },
  "connectionFailureReason": null,
  "intake": null
}

{
  "interviews": [
    {
      "id": "cknqc2m5d0005...",
      "scheduledAt": "2026-08-22T05:30:00Z",
      "timezone": "Australia/Sydney",
      "status": "CONFIRMED",
      "meetingLink": "https://meet.google.com/abc-defg-hij",
      "whatsappReminderSentAt": null,
      "emailReminderSentAt": null,
      "createdAt": "2026-08-19T02:10:00Z",
      "candidate": { "id": "cknq7z1a10004...", "name": "Priya Nair", "email": "priya.nair@example.com" },
      "recruiter": { "id": "cknqzz1x90000...", "name": "Alex Chen", "email": "alex@example.com" }
    }
  ]
}

The recruiter on the interview is always whoever created the API key — there’s no recruiter_id field to set it explicitly.

{
  "interviewId": "cknqc2m5d0005...",
  "calendarConnected": true,
  "calendarProvider": "GOOGLE",
  "calendlyUsed": false,
  "whatsappSent": true,
  "emailSent": true
}