Connecting JobCannon to iCIMS

JobCannon has no native iCIMS adapter today. This page used to describe an OAuth app, a webhook registration and a scorecard field mapping for iCIMS, none of which shipped. Rather than leave that standing, here is what is actually available and how to use it.

What ships today

A iCIMS adapter is on the roadmap with no committed date. If you want one, email partners@jobcannon.io with your candidate volume — that is what decides the order they get built in, and a named customer moves an ATS up the list faster than anything else does.

What works with iCIMS right now

The hosted invite API. Your integration — or an automation tool sitting beside iCIMS — creates the invitation, JobCannon emails the candidate and hosts the assessment, and JobCannon calls you back when it is done. You write the result into iCIMS using iCIMS's own API.

This is not a downgrade in the result you get: it is the same standardised envelope a native adapter delivers, over a transport you control.

1. Get a key

Email partners@jobcannon.io with your organisation name and the address to send credentials to. Keys carry scopes: sending needs assessments:send, reading results needs assessments:read.

2. Send an invitation

curl -X POST https://jobcannon.io/api/v1/invites \
  -H "X-API-Key: $JOBCANNON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "test_slug": "big-five",
    "candidate_email": "candidate@example.com",
    "candidate_first_name": "Alex",
    "candidate_last_name": "Morgan",
    "external_id": "<your iCIMS record id>",
    "callback_url": "https://your-app.example.com/hooks/jobcannon",
    "sandbox": true
  }'

Answers 201 with session_id, assessment_url, test, test_name, status, locale, candidate_email, sandbox and email_delivered.

• **external_id** is echoed back untouched on the callback — put your iCIMS record id there and you will not need a lookup table.
• **callback_url** must be absolute https and a public host. Loopback and private ranges are rejected, so you cannot point the flusher at internal infrastructure.
• **sandbox: true** runs the whole cycle without emailing anyone. email_delivered comes back null rather than true/false, because no mail was attempted. Take it out when you go live. Leave it in while you are testing: the live path emails a real person.
• **assessment_url** is the candidate's link. If you would rather deliver it yourself — in your own email, or pasted into iCIMS by a recruiter — take it from here.
• **locale** is echoed back even if you did not send it, because your organisation may have a default. It tells you which language the candidate was written to, and which language test_name is in.

3. Receive the result

JobCannon POSTs to your callback_url when the candidate finishes, with header X-JobCannon-Event: assessment.completed. The payload and every field in it are documented on the score mapping page.

The callback is an unsigned notification. If you need an authenticated confirmation of it, re-read the invite — that response is scoped to your own key:

curl -H "X-API-Key: $JOBCANNON_API_KEY" \
  https://jobcannon.io/api/v1/invites/{session_id}

Polling works on its own too: omit callback_url entirely and read this endpoint. Poll no more than once a minute — assessments take minutes to hours of wall-clock time.

Writing it into iCIMS

iCIMS integrations are provisioned per customer, and the fields available to you depend on your instance. Write primary_outcome.label and the result permalink into whichever candidate field your instance exposes for third-party assessment output; iCIMS's developer portal is linked below. JobCannon does not call it on your behalf.

Common errors

**401 missing_api_key** — no X-API-Key header reached us.

**401 invalid_api_key / 401 revoked_api_key** — the key is not recognised, or it was revoked. Both are deliberate: a revoked key says so rather than pretending it never existed.

**403 insufficient_scope** — the key is valid but was issued without the scope this endpoint needs. The message names the missing scope. Email partners@jobcannon.io to widen it.

**400 test_not_sendable** — the slug is not in the hire-eligible catalogue. Slugs are dashed (big-five, not big_five). **The error response lists every allowed slug in its allowed array** — send a deliberately bad one once and you have the catalogue.

**429 rate_limited** — per-key, not per-IP. resetAt in the body tells you when to retry.

Callback never arrives — check your endpoint answers 2xx and is reachable from the public internet. A failed callback retries with backoff (10 min → 30 min → 2 h → 6 h, five attempts) then stops. The result is never lost: read it with GET /api/v1/invites/{session_id} at any point afterwards.

iCIMS docs: https://developer.icims.com/ Support: partners@jobcannon.io