Developers
Build on the Goodfit hiring API
REST endpoints for jobs, applications, candidates, and assessments. Outbound webhooks with signed payloads. OpenAPI 3.1 spec and a maintained Postman collection. Wire Goodfit into the rest of your stack in an afternoon.
curl https://api.goodfit.so/v1/applications \
-H "x-api-key: $GOODFIT_API_KEY" \
-G --data-urlencode "job_id=jb_82bf91"Authenticate with an x-api-key header. Every endpoint returns JSON; every error returns a structured error code and message.
What the API does
Every hiring object, programmatically
Jobs
Create, update, and list roles
Manage every open role programmatically. Push jobs from your HRIS, sync stage changes back to your ATS, and keep your careers page in sync from a single source of truth.
- · GET /v1/jobs
- · POST /v1/jobs
- · PATCH /v1/jobs/{id}
- · GET /v1/jobs/pipeline
Applications
Track candidate progress
Read assessment results, scorecard payloads, and notes. Move candidates between stages, attach evaluation rationale, and trigger downstream automation from each transition.
- · GET /v1/applications
- · POST /v1/applications/assessments
- · POST /v1/applications/notes
- · PATCH /v1/applications/{id}
Candidates
Sync candidate records
Ingest candidates from your sourcing tools or push them out to your data warehouse. Every candidate carries source, referrer, and full assessment history.
- · GET /v1/candidates
- · POST /v1/candidates
- · GET /v1/candidates/{id}
Webhooks
React to anything that happens
Subscribe to events with signed payloads. Application created, assessment completed, candidate stage changed, interview completed - delivered to your endpoint with retries and a dashboard.
- · POST /v1/webhooks
- · GET /v1/webhooks
- · DELETE /v1/webhooks/{id}
Signed webhooks for every event that matters
Subscribe an endpoint, choose your events, and we deliver signed JSON payloads with retries, an activity log, and replay-from-dashboard for failed deliveries. HMAC-SHA256 signatures with timestamp checks prevent replay attacks.
- · HMAC-SHA256 signed, with timestamp in
X-Goodfit-Signature - · Automatic retries with exponential backoff, up to 24 hours
- · Replay any delivery from the dashboard without re-triggering upstream events
- · Per-endpoint secret rotation, no shared keys
Available events
- application.created
- application.stage_changed
- assessment.completed
- interview.completed
- candidate.created
- candidate.updated
- job.published
- job.closed
Built for developers
Documented, versioned, and stable
Per-org API keys
Create, rotate, and revoke keys from the dashboard. Sandbox and production keys are separate. Audit log records every call by key.
OpenAPI 3.1 + Postman
Machine-readable spec at /v1/openapi.json and a maintained Postman collection. Generate clients in any language without us shipping an SDK per stack.
Versioned, predictable
Path-versioned endpoints (/v1/). Breaking changes go through a deprecation window with advance notice. Backwards-compatible additions ship continuously.
Developer FAQ
Common questions
- How do I get an API key?
- API keys are created from the Developers section of your Goodfit dashboard. Keys are scoped to your organization and can be revoked at any time. Production and sandbox environments get separate keys.
- Is there an OpenAPI spec?
- Yes. The OpenAPI 3.1 spec is available at /v1/openapi.json, and a maintained Postman collection ships with the docs. Both stay in sync with every release.
- How are webhooks secured?
- Each webhook payload is signed with HMAC-SHA256 using a per-endpoint secret. The signature is sent in the X-Goodfit-Signature header along with a timestamp to prevent replay attacks.
- What are the rate limits?
- The default rate limit is 600 requests per minute per API key, with burst headroom. Enterprise plans get higher limits and isolated rate-limit pools. All responses include standard X-RateLimit-* headers.
- Can I use the API to build a custom careers page?
- Yes. The Jobs endpoint returns everything you need for a custom careers UI - role metadata, location, team, structured descriptions. If you would rather not build it yourself, the Career Sites product gives you both a hosted page and an embeddable widget out of the box.
- Where do I report bugs or request endpoints?
- Open a ticket from your dashboard or email developers@goodfit.so. Enterprise customers get a dedicated Slack channel for API support.
FAQ
Questions hiring teams ask us
See Goodfit in action
Start hiring smarter today
Get a walkthrough with our team, or sign up and try it yourself. 20 free assessments either way.