Build with IT Manager Jobs (Demo)

1. Sign up

You need an employer account on IT Manager Jobs (Demo) before you can access the API. The same account that posts jobs through the website is the one your ATS integration will run against — credits, contracts, and pipeline data are all shared between the two.

2. Mint an API key

Sign in to the employer portal as an admin, then open API keys under your account.

Trusted partners (signed integrations, repeat customers) can be flagged for instant approval on every key — talk to us if your integration is shipping to multiple environments and you don't want each one to wait. Lost a key? Revoke it on the API keys page and mint a new one.

3. Authenticate

Send the key as a Bearer token (preferred) or as a dedicated X-Api-Key header. Both work; pick whichever fits your HTTP client cleanest.

Authorization: Bearer pk_live_AbCdEf...
# or
X-Api-Key: pk_live_AbCdEf...

• Keys are tenant-scoped to the employer that minted them — a key from one employer can never read another employer's data.
• Each key carries a fixed set of scopes chosen at creation time. Endpoints reject keys missing the required scope with 403 Forbidden.
• Revoked, expired, or unknown keys return 401 Unauthorized immediately, with no body content.
• The LastUsedAt timestamp is updated on every successful call, visible on the API keys management page.

4. Make your first call

The simplest verification is to list your jobs — empty, but a 200 confirms auth + scope are right:

curl -H "Authorization: Bearer pk_live_…" \
     https://demo.it-manager-jobs.com/api/v1/jobs

# {"total":0,"page":1,"pageSize":50,"items":[]}

If you got 401: the key is wrong or revoked. If you got 403: the key was minted without the JobPosting scope — mint a new one with both scopes, or with the right one for your integration.

Job Posting API Scope: JobPosting

Example — create then publish

curl -X POST https://demo.it-manager-jobs.com/api/v1/jobs \
  -H "Authorization: Bearer pk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
        "title": "Senior Platform Engineer",
        "reference": "PL-001",
        "description": "Build and run the platform...",
        "city": "London",
        "country": "United Kingdom",
        "employmentType": "FullTime",
        "remoteType": "HybridRemote",
        "applyMethod": "EmailApply",
        "applyEmailAddress": "[email protected]"
      }'

# 201 Created
# {"id":1234,"status":"Draft", ... }

curl -X POST https://demo.it-manager-jobs.com/api/v1/jobs/1234/publish \
  -H "Authorization: Bearer pk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"expiryDate":"2026-06-01T00:00:00Z"}'

# 200 OK — status now "Active"

Applications API Scope: Applications

Read the applicant pipeline for jobs you own, fetch the AI suitability assessment computed when the application landed, move candidates through stages, and write the ATS surface — tags, recruiter notes, and interviewer scorecards. Tenant-scoped to the key's employer; cross-tenant calls return 404.

Example — list, read, move stage

curl -H "Authorization: Bearer pk_live_…" \
     "https://demo.it-manager-jobs.com/api/v1/jobs/1234/applications?status=New&pageSize=20"

curl -H "Authorization: Bearer pk_live_…" \
     https://demo.it-manager-jobs.com/api/v1/applications/9876/ai-assessment
# 200 OK — { score, verdict, summary, rubricScores: [...] }

curl -X POST https://demo.it-manager-jobs.com/api/v1/applications/9876/status \
  -H "Authorization: Bearer pk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "status": "Shortlisted", "note": "Top of stack — book a screen" }'

Note attribution. Notes and scorecards record an author user id. If the API key was minted without an associated user (rare — sales-side mint), note / scorecard writes return 403 unattributable. Re-mint the key from your own account to enable those writes.

Candidate API Scope: Profile, Applications

Candidate-self surface — read & update your own profile, list your own applications. Authenticated by a candidate-issued API key (separate from the recruiter key flow), minted from your candidate API keys page. Lets you wire up AI assistants (Claude, Copilot, Cursor) or the jbme CLI to drive your job-search workflow conversationally.

Isolation. Every candidate key only ever resolves to the owning candidate's own data — there's no way for a key to see another candidate's profile or applications. Validated in a separate database table from recruiter keys; the auth schemes don't cross-pollinate.

Apply safeguards

The apply endpoint is the highest-risk surface in the candidate API because AI fan-out can spam-apply on the candidate's behalf. The platform enforces several guardrails server-side:

• Explicit per-call confirmation. Every request body must carry "confirm": true. The MCP tool description spells out "you are applying on behalf of the candidate — confirm with them first"; missing the flag means a clean 400 rather than a silent submission.
• 10 successful applies per UTC day per candidate. Enforced across every key the candidate holds — revoking and re-minting doesn't reset the counter, and an AI client running on two devices can't split traffic to exceed the cap. Hitting it returns 429 with a Retry-After header pointing at the next free slot.
• One jobId per call. No array; no bulk-apply. Each application requires its own deliberate tool invocation.
• Same consent gate as the portal. Candidates whose data-processing consent has lapsed are blocked here too — the v1 surface MUST NOT be a way around the platform's GDPR posture.
• Recruiter visibility. Successful submissions carry an IsAiAssisted flag and surface as a small "AI-assisted" badge in the recruiter's applications list + detail page. Recruiters can weight the application accordingly; the lifecycle is otherwise identical to a portal apply.

Example — read, update, list applications

curl -H "Authorization: Bearer pk_live_…" \
     https://demo.it-manager-jobs.com/api/v1/me/profile
# 200 OK — full profile bundle

curl -X PUT https://demo.it-manager-jobs.com/api/v1/me/profile \
  -H "Authorization: Bearer pk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
        "headline": "Senior Platform Engineer",
        "expectedSalaryMin": 95000,
        "expectedSalaryMax": 120000,
        "expectedSalaryCurrency": "GBP",
        "careerStatus": "OpenToOffers"
      }'
# 200 OK — returns the patched profile

curl -H "Authorization: Bearer pk_live_…" \
     "https://demo.it-manager-jobs.com/api/v1/me/applications?status=Interviewing&pageSize=10"

curl -X POST https://demo.it-manager-jobs.com/api/v1/me/applications \
  -H "Authorization: Bearer pk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
        "jobId": 1234,
        "confirm": true,
        "coverLetter": "Quick note from the candidate — strong on Kubernetes."
      }'
# 201 Created — body includes { isAiAssisted: true, aiAppliesUsedToday, aiAppliesLimitPerDay }
# 400 if confirm is missing; 409 if you've already applied to this job;
# 429 if you've hit 10 AI applies in the last 24 hours.

CV Search API Scope: CvSearch

Boolean query syntax matches Elasticsearch's query_string: phrase quoting, AND/OR/NOT, parentheses, wildcards. Examples:

• "Process Engineer" AND "HVAC"
• (("High" OR "Low") AND "voltage") AND "Engineers" AND "Dubai"
• kubernetes AND (aws OR gcp) AND NOT junior

Example

curl -X POST https://demo.it-manager-jobs.com/api/v1/candidates/search \
  -H "Authorization: Bearer pk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
        "query": "\"Process Engineer\" AND \"HVAC\"",
        "preferredCountryIds": [44],
        "activeWithinDays": 90,
        "pageNumber": 1,
        "pageSize": 20
      }'

# 200 OK — items are masked (e.g. "fullName": "P*** E***")
# Each item carries an "isUnlocked" flag.

curl -H "Authorization: Bearer pk_live_…" \
     https://demo.it-manager-jobs.com/api/v1/candidates/12345

# 200 OK — full profile + email
# Subsequent calls within 30 days are free (uses the existing unlock).

Webhooks

Register an HTTPS endpoint and receive signed event POSTs whenever something happens to your jobs or applications. You don't need to poll the API.

Available events

Subscribe

Subscriptions are managed at /employer/webhooks. Each subscription gets a fresh HMAC-SHA256 signing secret, returned exactly once on creation.

Verifying signatures

Every delivery includes an X-Webhook-Signature header of the form t={unix-ts},v1={hex-hmac}. Recompute the HMAC on your side and compare in constant time:

// Node.js
const [tPart, v1Part] = req.headers['x-webhook-signature'].split(',');
const t = tPart.split('=')[1];
const v1 = v1Part.split('=')[1];

const signed = `${'$'}{t}.${'$'}{rawBody}`;
const expected = crypto.createHmac('sha256', secret)
                       .update(signed)
                       .digest('hex');

if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1))) {
  return res.status(403).end();
}
if (Math.abs(Date.now()/1000 - Number(t)) > 300) {
  return res.status(400).end(); // older than 5 minutes — replay
}

Headers on every delivery

• X-Webhook-Signature — t={ts},v1={hmac} as above.
• X-Webhook-Event — application.submitted etc.
• X-Webhook-Delivery-Id — stable id for this delivery attempt; useful for de-duplication on retries.

Retries and dead-lettering

Respond with any 2xx within 10 seconds to mark a delivery successful. Anything else (including timeouts) is retried with exponential backoff: 1m → 5m → 15m → 1h → 6h → 24h → 24h → 24h. After eight failed attempts the delivery is dead-lettered. After ten consecutive failures across any deliveries, the subscription is auto-disabled and the employer admin is emailed.

Idempotency is your responsibility — retries can deliver the same event twice. Key off X-Webhook-Delivery-Id or the entity id in the payload.

Rate limits

Rate-limited requests return 429 Too Many Requests. Back off and retry — credits are not consumed by rate-limited requests.

Errors

Every 4xx response from /api/v1/... follows the same envelope:

{
  "code": "no_credits",
  "message": "Insufficient job posting credits."
}

code is the machine-readable identifier you switch on. message is the human-readable summary, suitable for surfacing in your own UI.

Versioning

The public surface is versioned in the URL. v1 is a frozen contract: field renames, removals, status-code changes, or error-envelope tweaks are breaking changes and ship under /api/v2/..., not in v1.

• New additive changes (extra optional fields on responses, new endpoints) ship within v1 and are non-breaking.
• v1 stays available for an announced deprecation window when v2 ships — minimum 12 months, more if partner adoption justifies it.
• Snapshot tests in our CI guard the v1 contract; an accidental shape change breaks the build long before it can ship.

Install the CLI

Drive the platform from your terminal with the jbjobs tool — job posting, applicant pipeline, AI assessments, candidate workflows. Self-contained binary, no .NET runtime install required.

Windows (PowerShell)

iwr -useb https://it-manager-jobs.com/install/jbjobs.ps1 | iex

macOS / Linux

curl -fsSL https://it-manager-jobs.com/install/jbjobs.sh | sh

The installer downloads the latest signed binary from our GitHub releases, verifies its SHA-256 against the published checksums, and drops it on your PATH. Per-user install — no admin / sudo required. Re-running the same command upgrades in place.

After install, point the tool at your tenant:

# Windows (PowerShell)
$env:JOBBOARD_API_BASE = "https://your-tenant.example.com"
$env:JOBBOARD_API_KEY  = "pk_live_…"

# macOS / Linux
export JOBBOARD_API_BASE="https://your-tenant.example.com"
export JOBBOARD_API_KEY="pk_live_…"

jbjobs --help
jbjobs jobs list --status Active

Already have the .NET SDK? You can also install via NuGet: dotnet tool install --global JobBoardCli. The one-line installer above doesn't require .NET — the binary it downloads is self-contained.

OpenAPI & Postman

Two stable, machine-readable definitions for the public surface — pick whichever your toolchain prefers:

• Download the OpenAPI 3.0 spec (YAML) — hand-curated, contract-locked. Import into openapi-generator, Kiota, NSwag, Stoplight, Insomnia, etc. to generate clients in any language.
• Download the Postman collection (v2.1) — every endpoint pre-populated with example payloads. Set the base_url and api_key collection variables and start sending requests.
• Live, auto-generated reflection of the running service: https://demo.it-manager-jobs.com/swagger/v1/swagger.json — useful for cross-checking against the running build, but the hand-curated YAML above is the contract.

We don't yet ship language-specific SDKs; the OpenAPI document is the canonical source. If demand for a packaged client emerges, the most-requested language will land first — let us know via the contact form.

Support

Stuck? Have a partnership question? Need a higher rate limit, an unlimited contract, or a custom event we haven't built yet? Contact us — we read every message and we're happy to walk you through how the API would fit your team's workflow.

Production incidents that affect API availability are tracked at /healthz/ready (returns 200 when the platform is healthy). For ongoing partnerships we'll hand you a dedicated technical contact.