Get an API key
Developers · API v1

Connect Examopotamia to your systems

Use our dashboard, your own website, or both. Collect applications on your site, pull results into your HR system, and get notified in real time. Available on the Business plan.

OpenAPI 3.1 specBase URL https://examopotamia.com/api/v1

Authentication

Create a key in Console → Developers. Keys are secret: use them from your server, never in browser code.

curl https://examopotamia.com/api/v1/jobs \
  -H "Authorization: Bearer exk_live_your_key"

Responses are { "data": … }. Errors are { "error": { "code", "message" } } with standard HTTP status codes. Limit: 120 requests per minute per key. Breaking changes will ship as /api/v2; v1 keeps working.

Endpoints

GET/jobsList jobs
POST/jobsCreate a job (draft)
GET/jobs/{id}Get a job
PATCH/jobs/{id}Update a job
POST/jobs/{id}/openOpen a job for applications
POST/jobs/{id}/closeClose a job
POST/jobs/{id}/applicationsSubmit an application collected on your own site
GET/applicationsList applications
GET/applications/{id}Get an application
PATCH/applications/{id}Change status, rating or notes
GET/assessmentsList assessments
GET/assessments/{id}/resultsList results for an assessment
GET/blacklistList blacklisted emails
POST/blacklistBlacklist an email
DELETE/blacklist/{email}Remove an email from the blacklist

Example: send an application collected on your own careers page.

curl -X POST https://examopotamia.com/api/v1/jobs/JOB_ID/applications \
  -H "Authorization: Bearer exk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name":"Sara Ahmed","email":"sara@example.com","answers":{"cv":"https://linkedin.com/in/sara"}}'

If the job has an assessment, the response includes assessment_url: send it to the candidate and their score is added to the application automatically.

Webhooks

Add an https endpoint in Console → Developers and choose events: application.created, application.status_changed, assessment.completed. Each request carries an Examopotamia-Signature header. Always verify it:

import crypto from 'node:crypto';

// Express example: use the raw body, not the parsed JSON.
app.post('/webhooks/examopotamia', express.raw({ type: 'application/json' }), (req, res) => {
  const header = req.get('Examopotamia-Signature') || '';
  const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const expected = crypto.createHmac('sha256', process.env.EXAMOPOTAMIA_WEBHOOK_SECRET)
    .update(`${t}.${req.body}`).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
  const ok = typeof v1 === 'string' && v1.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
  if (!fresh || !ok) return res.sendStatus(400);
  const event = JSON.parse(req.body);
  // event.type: application.created | application.status_changed | assessment.completed
  res.sendStatus(200);
});

Embedding

Show a job's application form or an assessment on your own website. Results still arrive in your dashboard and API.

<iframe src="https://examopotamia.com/j/YOUR-JOB-SLUG?embed" width="100%" height="900" style="border:0"></iframe>
<iframe src="https://examopotamia.com/t/YOUR-TEST-SLUG" width="100%" height="760" style="border:0"></iframe>