Faroquest API

Connect hiring and talent workflows to your own product.

Use Faroquest as the operating layer behind a careers site, recruiting workflow, ATS connection, or talent-development programme.

Quick start

Most companies start with a published experience. Create it in the workspace, copy its hosted link or embed code, and let submissions flow into the Intake inbox.

1. Create a job
2. Publish → Experiences → New experience
3. Connect the experience to the job
4. Publish it
5. Copy the hosted link or embed snippet
6. Submit a test application
7. Review it in /{agency}/intake

Authentication

Workspace API requests use a Faroquest access token. Never expose a workspace token in a browser or public embed. Public experiences and candidate intake are designed for unauthenticated visitors.

Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

Server-to-server intake uses the configured webhook token and an idempotency key.

X-Intake-Webhook-Token: YOUR_INTAKE_TOKEN
X-Idempotency-Key: provider-event-123

Publishing experiences

Experiences hold the candidate-facing content, form configuration, theme, and routing metadata.

GET  https://faroquest.com/api/v1/a/{agency}/experiences
POST https://faroquest.com/api/v1/a/{agency}/experiences
GET  https://faroquest.com/api/v1/a/{agency}/experiences/{id}
PATCH https://faroquest.com/api/v1/a/{agency}/experiences/{id}
POST https://faroquest.com/api/v1/a/{agency}/experiences/{id}/status

{
  "name": "Backend Engineer application",
  "experience_type": "job_application",
  "template_key": "job_application",
  "job_opening_id": "job-id",
  "content": {
    "overview": "Build reliable services...",
    "responsibilities": ["Design APIs"],
    "qualifications": ["5+ years experience"],
    "benefits": ["Flexible working"],
    "hiring_process": ["Application review", "Interview"]
  },
  "form": {"fields": ["full_name", "email", "resume", "consent_given"]},
  "routing": {"job_opening_id": "job-id", "channel": "hosted_form"}
}

Candidate intake

Use this endpoint for an ATS, careers frontend, referral system, or internal integration. Unknown jobs are kept for review instead of discarded.

POST https://faroquest.com/api/v1/a/{agency}/public/intake

{
  "full_name": "Amara Okafor",
  "email": "amara@example.com",
  "job_slug": "backend-engineer",
  "channel": "ats",
  "source": "greenhouse",
  "external_id": "candidate-123",
  "screening_answers": {"work_authorization": "yes"},
  "consent_given": true
}

For email CV intake, send multipart data to /api/v1/a/{agency}/public/inbound-email with the same webhook token.

Embeds and hosted links

Hosted link:

https://faroquest.com/apply/{agency}/{job-slug}?src=company-careers&utm_source=website

Inline widget:

<div data-faroquest-intake
     data-base="https://faroquest.com"
     data-agency="company"
     data-job="backend-engineer"
     data-source="company-careers"></div>
<script src="https://faroquest.com/faroquest-intake.js" defer></script>

Full-page widget:

<div data-faroquest-intake
     data-full-page="true"
     data-base="https://faroquest.com"
     data-agency="company"
     data-job="backend-engineer"
     data-source="company-careers"></div>
<script src="https://faroquest.com/faroquest-intake.js" defer></script>

Talent development

Attach development plans and measurable milestones to candidate or employee records.

GET  https://faroquest.com/api/v1/a/{agency}/talent-development/plans
POST https://faroquest.com/api/v1/a/{agency}/talent-development/plans
GET  https://faroquest.com/api/v1/a/{agency}/talent-development/plans/{id}
POST https://faroquest.com/api/v1/a/{agency}/talent-development/milestones/{id}/status

{
  "candidate_id": "candidate-id",
  "title": "First 90 days",
  "summary": "Build confidence in the platform team",
  "review_cadence": "monthly",
  "milestones": [
    {"title": "Meet the team"},
    {"title": "Ship first measurable improvement"}
  ]
}

Attribution

Preserve the source on every hosted link or widget. Faroquest records source, campaign, UTM values, channel, and connector metadata alongside the intake receipt.

https://faroquest.com/apply/company/backend-engineer?src=linkedin&utm_source=linkedin&utm_medium=paid&utm_campaign=backend-q3

Errors and retries

Responses use standard HTTP status codes and a JSON detail message. Retry transient 5xx responses with the same idempotency key. Do not retry validation errors or 4xx responses without changing the request.

{
  "detail": "This application was already received.",
  "code": "idempotent_replay"
}

Check the Intake inbox for submissions marked needs review, screening incomplete, or processing failed.