Goodfit

Build on the Goodfit API

Read interview scores into your own systems, and get a webhook when anything changes. The REST API covers jobs, applications, candidates and reports, with an OpenAPI 3.1 spec.

Get an API keyRead the documentation
Request
BASE=https://apidocs.goodfit.so/api/v1
curl -G "$BASE/applications/$APP_ID/report" \
  -H "x-api-key: $GOODFIT_API_KEY" \
  -d verbosity=summary
Response
{
  "data": {
    "candidate": { "name": "Maya Torres" },
    "job": { "title": "Customer Support Agent" },
    "assessments": [{
      "type": "voice",
      "score": 8,
      "maxScore": 10,
      "skills": [{
        "name": "Calming an upset customer",
        "score": 9,
        "quote": "I'd say sorry first, then check the order.",
        "at": "03:12"
      },
      { "name": "Clear explanations", "score": 8 },
      { "name": "Product knowledge", "score": 7 }]
    }],
    "reportLink": "https://dashboard.goodfit.so/…"
  }
}

Authenticate with an x-api-key header. Every endpoint returns JSON, and every error returns an error code and a message.

The same report in Goodfit. The overall score is the average of the skill scores.

What you can read and change with the API

Jobs

Create, update and list roles

Push jobs from your HRIS, send stage changes back to your ATS, and feed your careers page from the same job list.

  • GET /v1/jobs
  • POST /v1/jobs
  • PATCH /v1/jobs/{id}
  • GET /v1/jobs/{jobId}/pipeline

Applications

Read scores and move candidates

Read interview and test scores, the full report and notes. Move candidates between stages, add notes, and start your own automations when a candidate moves stage.

  • GET /v1/applications
  • GET /v1/applications/{id}/report
  • POST /v1/applications/{id}/notes
  • POST /v1/applications/{id}/advance

Candidates

Copy candidate records

Pull candidates into your data warehouse or other tools. Add a candidate by inviting them to a job with POST /v1/applications.

  • GET /v1/candidates
  • GET /v1/candidates/{id}
  • GET /v1/candidates/{id}/resume

Claude (MCP)

Ask Claude about your candidates

Connect Goodfit to Claude Code or Claude Desktop from the API Keys page. Claude can then call the same endpoints with your key, so you can ask about candidates in plain English.

  • claude mcp add --transport http goodfit …

Webhooks for 17 hiring events, signed with HMAC-SHA256

Add an endpoint and choose your events. Goodfit sends a signed JSON payload each time one happens. Every attempt is logged, failed deliveries retry on their own, and you can retry any delivery with one call.

  • HMAC-SHA256 signed, in X-Webhook-Signature
  • Automatic retries with backoff for about 20 hours
  • Retry any delivery without re-triggering the event that caused it
  • A separate signing secret for each endpoint

All 17 events

  • job.created
  • job.updated
  • job.closed
  • application.created
  • application.status_changed
  • application.stage_advanced
  • application.pipeline_completed
  • application.rejected
  • application.hired
  • application.deleted
  • assessment.started
  • assessment.completed
  • assessment.evaluated
  • candidate.created
  • prescreening.submitted
  • prescreening.passed
  • prescreening.failed

Versioned endpoints, an OpenAPI spec and keys for each organization

API keys for each organization

Create and revoke keys from the dashboard. Each key only sees its own organization's data.

OpenAPI 3.1 spec

Machine-readable spec at /api/v1/openapi.json. Generate clients in any language without us shipping an SDK per stack.

Versioned endpoints

Path-versioned endpoints (/v1/). Breaking changes go through a deprecation window with advance notice. Backwards-compatible additions ship continuously.

Browse pre-built integrationsEmail the API team

FAQ

Questions developers ask us

How do I get an API key?
Create a key in your Goodfit dashboard under Developers, then API Keys. Each key is scoped to your organization and can be revoked at any time.
Is there an OpenAPI spec?
Yes. The OpenAPI 3.1 spec is served at /api/v1/openapi.json and is generated from the same code that runs the API, so it always matches.
How are webhooks secured?
Each webhook payload is signed with HMAC-SHA256 using a per-endpoint secret. The signature is sent in the X-Webhook-Signature header. Every delivery has a unique id, so you can safely ignore repeats.
What are the rate limits?
Each API key gets 120 requests per minute by default. Past that you get a 429 response with a Retry-After header that says how many seconds to wait.
Can I use the API to build a custom careers page?
Yes. The Jobs endpoint returns the title, location, team and description for each role. If you would rather not build a page, Career Sites gives you a hosted page and a widget you can embed.
Where do I report bugs or request endpoints?
Open a ticket from your dashboard or email support@goodfit.so. Tell us the endpoint and what you need it to do.
How much does Goodfit cost?
Every account starts with 20 free assessments. After that, you pay per completed assessment (see the pricing page for your region). 1 credit = 1 assessment. An assessment is an AI voice interview, skill test, personality test, coding test, employee check-in call or practice roleplay. The minimum purchase is 200 credits. Credits you buy never expire. Cheating checks and interviews in other languages are included. There are no subscriptions, seat fees or long contracts.
Does this work with the ATS we already use?
Most teams start with the ATS built into Goodfit, or they export results. The built-in ATS has drag-and-drop hiring stages, automation rules and a change history for each job. During setup, we connect Goodfit to the ATS or HR system you already use, like Greenhouse, Workday or BambooHR.
Is candidate data safe?
Goodfit is SOC 2 Type II compliant. All data is encrypted when it is stored and when it is sent. Neither Goodfit nor our AI providers train models on your candidate data. You can ask us to delete it at any time.

Start building with Goodfit

Create a key in your Goodfit dashboard and make your first call in a few minutes. The docs list every endpoint and event.

Get an API keyRead the documentation