DocsAPI Reference

API Reference

The WonderFunnel REST API lets you integrate recruitment intelligence directly into your ATS, HRMS, or custom tooling.

https://api.wonderfunnel.io/v1All responses are JSON · TLS required

Authentication: Include Authorization: Bearer <token> on every request. Get your API key from Dashboard → Settings → API.

Authentication

All API requests must include your API key in the Authorization header as a Bearer token. API keys are scoped to your organisation. Rotate keys from Settings → API.

POST/auth/token

Exchange API key for a short-lived JWT

Returns a signed JWT valid for 1 hour. Use this token in subsequent requests. The JWT carries your org_id and role scopes.

Parameters

Param	In	Type	Required	Description
api_key	body	string	Yes	Your WonderFunnel API key

Example response

{
  "token": "eyJhbGc…",
  "expires_in": 3600,
  "token_type": "Bearer"
}

ICPs

Create and manage Ideal Candidate Profiles (ICPs). Each ICP runs a 6W analysis and produces a scored profile with factor library and messaging recommendations.

GET/icps

List all ICPs

Returns a paginated list of ICPs for your organisation, ordered by updated_at descending.

Parameters

Param	In	Type	Required	Description
page	query	integer	No	Page number (default: 1)
per_page	query	integer	No	Results per page, max 100 (default: 20)
status	query	string	No	Filter by status: draft \| generating \| ready

Example response

{
  "data": [
    {
      "id": "icp_01HXYZ",
      "role": "Senior Data Engineer",
      "seniority": "senior",
      "status": "ready",
      "score": 91,
      "created_at": "2026-04-05T08:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 3
  }
}

POST/icps

Create a new ICP

Triggers a 6W analysis. Generation typically completes within 90 seconds. Poll the ICP status or subscribe to the icp.ready webhook event.

Parameters

Param	In	Type	Required	Description
role	body	string	Yes	Job title or role identifier
seniority	body	string	Yes	One of: junior \| mid \| senior \| staff \| manager \| director
location	body	string	No	Primary location, e.g. Amsterdam, Netherlands
industry	body	string	No	Target industry context

Example response

{
  "id": "icp_02HABC",
  "role": "Frontend Engineer",
  "status": "generating",
  "created_at": "2026-04-07T10:00:00Z"
}

GET/icps/:id

Get an ICP

Returns the full ICP object including 6W dimensions, factor library, messaging recommendations, and scoring weights.

Parameters

Param	In	Type	Required	Description
id	path	string	Yes	ICP identifier

Example response

{
  "id": "icp_01HXYZ",
  "role": "Senior Data Engineer",
  "seniority": "senior",
  "status": "ready",
  "score": 91,
  "dimensions": {
    "WHO": "Mid-senior engineers, 8–12 years experience…",
    "HOW": "Hands-on builders who prefer IC track…",
    "WHY": "Escaping legacy systems…",
    "WHAT": "Python/SQL core, cloud-native…",
    "WHERE": "Scale-ups 200–1500 employees…",
    "WHEN": "2–3 years in current role…"
  }
}

Candidates

Score individual candidates against an ICP. Returns a match score and per-dimension breakdown with messaging recommendations.

POST/icps/:id/score

Score a candidate against an ICP

Accepts a candidate object and returns a 0–100 match score with a per-dimension breakdown and recommended outreach angles.

Parameters

Param	In	Type	Required	Description
id	path	string	Yes	ICP identifier
candidate	body	object	Yes	Candidate data: name, current_title, years_experience, skills[], location

Example response

{
  "candidate_id": "cand_tmp_01",
  "icp_id": "icp_01HXYZ",
  "score": 87,
  "dimensions": {
    "WHO": {
      "score": 90,
      "match": "strong"
    },
    "WHY": {
      "score": 85,
      "match": "strong"
    },
    "WHAT": {
      "score": 88,
      "match": "strong"
    },
    "WHERE": {
      "score": 70,
      "match": "moderate"
    },
    "HOW": {
      "score": 92,
      "match": "strong"
    },
    "WHEN": {
      "score": 82,
      "match": "strong"
    }
  },
  "top_angles": [
    "Legacy Escape",
    "Ownership Culture",
    "Remote-First"
  ]
}

POST/icps/:id/score/batch

Batch-score up to 100 candidates

Accepts an array of candidate objects. Returns scores in the same order. Useful for scoring an entire ATS pipeline in one call.

Parameters

Param	In	Type	Required	Description
id	path	string	Yes	ICP identifier
candidates	body	array	Yes	Array of candidate objects (max 100)

Example response

{
  "results": [
    {
      "score": 87,
      "candidate_index": 0
    },
    {
      "score": 62,
      "candidate_index": 1
    }
  ]
}

Webhooks

Subscribe to real-time events. WonderFunnel sends signed POST requests to your endpoint URL. Verify the X-WF-Signature header using HMAC-SHA256 with your webhook secret.

GET/webhooks

List webhook subscriptions

Returns all active webhook endpoints for your organisation.

Example response

{
  "data": [
    {
      "id": "wh_01HABC",
      "url": "https://your-app.com/wf/events",
      "events": [
        "icp.ready",
        "score.complete"
      ],
      "active": true
    }
  ]
}

POST/webhooks

Create a webhook

Parameters

Param	In	Type	Required	Description
url	body	string	Yes	HTTPS endpoint URL
events	body	array	Yes	Events to subscribe: icp.ready \| score.complete \| campaign.launched

Example response

{
  "id": "wh_02HXYZ",
  "secret": "whsec_…",
  "active": true
}