canonical: https://jentic.com/apis/kand.io/kandio

# Kand Kandio

Jentic publishes the only available OpenAPI specification for Kandio, keeping it validated and agent-ready. Kandio is a curated skill-testing marketplace whose API lets job sites, applicant tracking systems, and in-house recruiters create candidate assessments, send invitations, retrieve scored results, and subscribe to webhook events. It is designed for two-way data flow between Kandio's catalogue of expert-built tests and external HR platforms. Tests are organised by skill area, and each assessment is tied to an organisation account.

## For AI agents

Create skill-test assessments, invite candidates, retrieve scored results, and manage webhook subscriptions inside a Kandio organisation. 18 endpoints covering the full assessment lifecycle.

## Scope

Does not handle job posting, candidate sourcing, or interview scheduling - use for skills assessment creation, scoring, and webhook events only.

## Capabilities

- Create a candidate assessment for a specific test inside an organisation via POST /{organization}/tests/{test}/assessments
- List and retrieve assessment results, including overall score and per-question breakdown, via /{organization}/assessments and /{organization}/assessments/{assessment}
- Browse the Kandio catalogue of skill areas and tests through /skillareas and /{organization}/tests
- Map vendor-specific skill areas to organisation skill areas via /{organization}/skillareas/{skillarea}
- Subscribe to assessment-completed and result-updated webhook events via the /webhooks endpoints
- Resolve a test by ID to inspect its skill area, duration, and difficulty before inviting candidates

## Use cases

### ATS Assessment Integration

Embed Kandio skills tests into an applicant tracking system so recruiters can trigger an assessment from a candidate record and pull results back into the hiring pipeline. The integration creates an assessment via the organisation-scoped endpoint, captures the candidate URL returned, and listens for webhook events when results are ready. End-to-end wiring takes roughly two days against a vendor-curated test catalogue covering hundreds of technical and language skills.

Example prompt: Create an assessment for test ID `python-mid` inside organisation `acme` via POST /{organization}/tests/{test}/assessments and return the candidate invitation URL.

### Bulk Candidate Screening

Send standardised skills assessments to every applicant for a role and rank them by score before the human screen. The API exposes test metadata (skill area, duration, difficulty) so recruiters can pick a calibrated test, batch-create assessments, and pull a sortable result list. Saves hours per role on phone screens and removes subjective gatekeeping at the top of the funnel.

Example prompt: Create assessments for a list of 25 candidate emails on test `frontend-react`, then list completed assessments via GET /{organization}/assessments sorted by score.

### Webhook-Driven Result Pipeline

Receive real-time notifications when a candidate completes a Kandio test and trigger downstream automation (Slack alert, ATS stage advance, calendar invite for a follow-up interview). Webhook subscriptions are managed through the API so an HR platform can register a single endpoint per organisation and receive structured event payloads without polling.

Example prompt: Register a webhook subscription via POST /webhooks pointing at https://hooks.example.com/kandio for the assessment-completed event.

### Agent-Driven Recruiting Workflows

AI recruiting agents discover Kandio through Jentic, pick the right skill test from the catalogue, send the invite, and surface results inside a chat or email thread without the recruiter touching the Kandio UI. Jentic handles the OAuth2 flow and scopes credentials per organisation so the agent can act on behalf of a single tenant safely.

Example prompt: Use the Jentic search 'send a skills assessment to a candidate', load the schema, and invite candidate@example.com to the Python intermediate test inside organisation `acme`.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/{organization}/tests/{test}/assessments` | Create an assessment for a candidate on a given test |
| GET | `/{organization}/assessments` | List assessments inside an organisation |
| GET | `/{organization}/assessments/{assessment}` | Retrieve a single assessment with score and details |
| GET | `/{organization}/tests` | List tests available to the organisation |
| GET | `/skillareas` | List all skill areas in the Kandio catalogue |
| GET | `/{organization}/skillareas` | List skill areas configured for the organisation |

## Key resources

- **Assessments** — Create candidate assessments, list them, and retrieve scored results.
- **Tests** — Browse the catalogue of skill tests available to an organisation.
- **Skill Areas** — List skill areas globally or scoped to an organisation, and resolve individual skill area details.
- **Webhooks** — Register and manage event subscriptions for assessment lifecycle events.

## Why Jentic

- **Setup:** Wiring Kandio by hand means running its OAuth2 flow, tracking token refresh, and threading your organization identifier into every path against v2.kand.io yourself. Through Jentic you install once, import Kandio from the API Directory, store the OAuth credential once, and your agent calls it.
- **Permission scoping:** Kandio puts the organization in the URL path (/{organization}/tests/{test}/assessments), so a rule can pin your agent to one organization: it can create and read assessments for that org and nothing else. You choose the operations it may call, so it stays on assessment creation and scoring unless you add more.
- **Credential handling:** Your Kandio OAuth2 credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. The access token and refresh token never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'send a skills test to a candidate' or 'list assessment scores', and Jentic returns the matching Kandio operation with its path and body schema so the agent calls the right endpoint without reading Kandio's docs.

## Related APIs

- **Greenhouse Harvest API** — ATS where Kandio assessment results land as candidate stage data.
- **Lever API** — ATS that consumes Kandio scores via webhook to gate interview scheduling.
- **Workable API** — Workable bundles its own assessment tooling, so it can replace Kandio for SMB hiring.
- **SmartRecruiters API** — Enterprise hiring platform that triggers external assessment partners like Kandio.

## FAQ

### Why is there no official OpenAPI spec for Kandio?

Kandio does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Kandio via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Kandio API use?

The API uses OAuth2 (passport scheme) with bearer tokens issued per organisation. Each request must include `Authorization: Bearer {token}` and the organisation slug in the path. Through Jentic, OAuth tokens are stored encrypted in the vault and injected at execution time so the agent never handles raw tokens.

### Can I create a skills assessment for a candidate via the Kandio API?

Yes. POST /{organization}/tests/{test}/assessments creates an assessment tied to a specific test inside an organisation. The response includes the candidate invitation URL that you forward to the applicant. The same assessment ID is later used with GET /{organization}/assessments/{assessment} to fetch the scored result.

### What are the rate limits for the Kandio API?

Kandio does not publish hard rate limits in the spec; in practice the platform expects integration-level traffic from ATS and job-site partners. If you exceed the platform's burst tolerance the API responds with HTTP 429. Contact info@kand.io to negotiate higher throughput for high-volume screening.

### How do I subscribe to assessment completion events through Jentic?

Run `pip install jentic` and search Jentic for 'subscribe to Kandio assessment events'. Jentic returns the schema for the /webhooks endpoint; supply your callback URL and the event types you care about, and execute the call to register the subscription.

### Can I list every test available to my Kandio organisation?

Yes. GET /{organization}/tests returns the tests configured for the organisation, including each test's skill area, duration, and difficulty. Use GET /skillareas first to discover the catalogue of skill areas before filtering tests.

### Is the Kandio API free?

No - Kandio is a paid skills-testing marketplace and API access is bundled with platform subscriptions. The free Jentic tier covers the integration plumbing, but the underlying assessments are billed by Kandio per test or per seat.

### Can I limit what my agent is allowed to do with the Kandio API?

Yes. Because you run Jentic One yourself, self-hosted, your own rules decide which Kandio operations and credentials the agent may use. Since Kandio puts the organization in the URL path, such as /{organization}/tests/{test}/assessments, you can pin the agent to a single organization so it only creates and reads assessments for that org and nothing else. You also choose exactly which operations it may call, so it stays on assessment creation and scoring unless you allow more, such as GET /{organization}/assessments or the /webhooks endpoints.