Candidates

Candidates are people linked to your organization. Auth: organization API key.

Only for partner customers. Pass the active organization with the optional x-organization-id header. Omit it to use the organization that owns the API key. A partner key may pass a direct child. An unknown organization returns 404. An organization the key cannot access returns 403. A non-empty organization_id query or body field returns 400 VALIDATION_ERROR.

Method	Path	Summary
`GET`	`/v1/candidates`	List candidates
`GET`	`/v1/candidates/:id`	Get one candidate by UUID
`POST`	`/v1/candidates`	Create or link a candidate
`PATCH`	`/v1/candidates/:id`	Update a candidate

List

curl "https://api.skillflare.co/v1/candidates?limit=20&offset=0" \
  -H "x-api-key: sk_skillflare_YOUR_KEY" \
  -H "x-organization-id: CHILD_ORG_UUID"

Returns { data, meta } as described in Errors and pagination. The envelope meta is pagination only; each item also has its own meta object for partner metadata. Each item:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-01-15T12:00:00.000Z",
  "full_name": "Alex Example",
  "email": "alex@example.com",
  "meta": { "external_id": "ats-123" }
}

id — candidate UUID (use this in path params and as candidate_id when creating sessions).
created_at — when the candidate was created (ISO 8601).
full_name — display name, or null if unknown.
email — email address, or null if unknown. Values set through this API are stored lowercased.
meta — opaque JSON object stored on the organization–candidate link (defaults to {}). Unrelated to the list pagination envelope meta.

Get by id

curl https://api.skillflare.co/v1/candidates/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "x-api-key: sk_skillflare_YOUR_KEY" \
  -H "x-organization-id: CHILD_ORG_UUID"

A candidate linked to another organization is NOT_FOUND.

Returns the candidate at the top level:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-01-15T12:00:00.000Z",
  "full_name": "Alex Example",
  "email": "alex@example.com",
  "meta": { "external_id": "ats-123" }
}

id — candidate UUID (use this in path params and as candidate_id when creating sessions).
created_at — when the candidate was created (ISO 8601).
full_name — display name, or null if unknown.
email — email address, or null if unknown. Values set through this API are stored lowercased.
meta — opaque JSON object stored on the organization–candidate link (defaults to {}).

Invalid UUIDs → VALIDATION_ERROR. Missing candidate → NOT_FOUND.

Create

curl https://api.skillflare.co/v1/candidates \
  -H "x-api-key: sk_skillflare_YOUR_KEY" \
  -H "x-organization-id: CHILD_ORG_UUID" \
  -H "content-type: application/json" \
  -d '{
    "email": "alex@example.com",
    "full_name": "Alex Example",
    "meta": { "external_id": "ats-123" }
  }'

Field	Required	Notes
`email`	Yes	Must look like an email; stored lowercased. Missing → `email is required`. Invalid → `email must be an email address`
`full_name`	Yes	Display name. Missing → `full_name is required`
`meta`	No	Opaque JSON object for partner metadata. Omitted or `null` → `{}`. Must be an object (not an array or primitive); otherwise → `meta must be an object`. Stored on the organization–candidate link and echoed as `candidate_meta` on webhooks (alongside `candidate_full_name` and `candidate_email`). A `200` re-create does not overwrite existing `meta`.

201 when the candidate is newly linked to the organization. 200 with the same body when that email is already linked (existing meta is left unchanged). The id is the candidate_id to pass when creating a session.

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-01-15T12:00:00.000Z",
  "full_name": "Alex Example",
  "email": "alex@example.com",
  "meta": { "external_id": "ats-123" }
}

id — candidate UUID (use this in path params and as candidate_id when creating sessions).
created_at — when the candidate was created (ISO 8601).
full_name — display name, or null if unknown.
email — email address, or null if unknown. Values set through this API are stored lowercased.
meta — opaque JSON object stored on the organization–candidate link (defaults to {}).

Update

curl -X PATCH https://api.skillflare.co/v1/candidates/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "x-api-key: sk_skillflare_YOUR_KEY" \
  -H "x-organization-id: CHILD_ORG_UUID" \
  -H "content-type: application/json" \
  -d '{
    "email": "updated@example.com",
    "full_name": "Updated Example",
    "meta": { "external_id": "ats-456" }
  }'

Send at least one of email, full_name, or meta. Unknown fields → VALIDATION_ERROR. Omitted fields stay as they are.

Field	Required	Notes
`email`	No	Must look like an email; stored lowercased. Empty → `email is required`. Invalid → `email must be an email address`. Updates invite identity on unlinked stubs only
`full_name`	No	Display name. Empty → `full_name is required`. Updates invite identity on unlinked stubs only
`meta`	No	Replaces the opaque JSON object on the organization–candidate link. `null` → `{}`. Must be an object (not an array or primitive); otherwise → `meta must be an object`

After the candidate has signed up, changing email or full_name returns 409 CONFLICT (email and full_name cannot be updated after the candidate has signed up). Only meta can still change. A colliding invite email also returns 409 (A candidate with that email already exists).

Invalid UUIDs → VALIDATION_ERROR. Missing candidate → NOT_FOUND. An empty body (no updatable fields) → VALIDATION_ERROR (At least one of email, full_name, meta is required).

200 with the full candidate resource:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-01-15T12:00:00.000Z",
  "full_name": "Updated Example",
  "email": "updated@example.com",
  "meta": { "external_id": "ats-456" }
}

List

Get by id

Create

Update

On this page