Recipe b: apply sessions
Your server makes a session for each click, with the terms, the job and your state bound on the server. For terms per job or per candidate, and for job boards.
4 minute read
An apply session is made by your server, through the API, at the moment a visitor presses the button. It holds the terms for that one application, the job's words, your state and your own custom_data, so nothing that matters passes through the page. Use it when the terms differ per job or per candidate, or when your jobs are not positions in certo.
A session serves one candidate, once, within an hour. Make it on the click, never when the page loads.
1. An endpoint on your server
It makes a fresh state, keeps it in the visitor's session, and asks certo for a session. The key needs hiring:invite.
app.post('/certo/session', async (req, res) => {
const state = crypto.randomUUID()
const answer = await fetch('https://api.certo.bio/v1/apply-sessions', {
method: 'POST',
headers: {
authorization: `Bearer ${process.env.CERTO_API_KEY}`,
'content-type': 'application/json',
'idempotency-key': crypto.randomUUID(),
},
body: JSON.stringify({
scope_types: ['employment', 'education'],
include_contact: true,
job: { ref: 'JOB-42', title: 'Backend engineer', hiring_company: 'Acme Robotics', url: 'https://jobs.hireline.example/job-42' },
state,
custom_data: { board_job_id: 9912 },
}),
})
if (!answer.ok) return res.status(502).json({ error: 'session' })
const { apply_session } = await answer.json()
req.session.certo = { state, audience: apply_session.id }
res.json({ id: apply_session.id })
})
The answer, 201:
{
"dry_run": false,
"apply_session": {
"id": "as_9c2e4a7b1d3f4e8a9b0c1d2e3f4a5b6c",
"url": "https://certo.bio/apply/as_9c2e4a7b1d3f4e8a9b0c1d2e3f4a5b6c",
"expires_at": "2026-11-20T11:02:00Z",
"position_id": null,
"terms": { "source": "session", "scope_types": ["education", "employment"], "include_contact": true, "include_birth_date": false, "birth_date_reason": null, "requirements": null }
}
}
terms is what the candidate will be shown and what the application will open. Keep the session's id with the state: it is the token's aud (client side).
2. Open it on the click
document.querySelector('#apply').addEventListener('click', () => {
CertoApply.open({
session: () => fetch('/certo/session', { method: 'POST' }).then((r) => r.json()).then((s) => s.id),
onApplied(result) { /* client side: send result.token to your server */ },
onSubmitted({ applicationId, state }) { /* server side only */ },
onCancel(detail) { /* detail.reason is 'session' when your endpoint failed or took too long */ },
})
})
A browser blocks a popup opened after an await, so v1.js opens the popup at once, on the click, at https://certo.bio/apply/wait, then calls session() and moves the popup to the session when the promise resolves. If it fails or takes more than ten seconds, the popup closes and onCancel({ reason: 'session' }) is called.
The button form works too, when your server renders the page per visitor: data-certo-apply="as_...", with nothing else. With a session the button's job words and state are ignored.
The fields
Every field is optional.
| Field | What |
|---|---|
position_id | One of your open positions: its terms are the defaults and the application is filed under it. The position need not be switched on for Apply with certo |
scope_types, include_contact, include_birth_date, birth_date_reason, requirements | The terms, as a position takes them |
job | ref (200 characters), title (120), hiring_company (120), url (http or https, 2048) |
state | Your value for this click, at most 200 printable characters without spaces, quotes or angle brackets |
custom_data | Your own JSON object, copied onto the application and every event about it |
How the terms are merged. Each term you leave out comes from the named position, else from your general application. If you give any term, terms.source is session; otherwise it is the source the terms came from. Without a position and without saved general terms, give at least scope_types, include_contact and include_birth_date, or the call answers apply.general_terms_missing. The date of birth needs its reason, and the merged terms are checked as a position's are (apply.terms_invalid).
Try it first
?dry_run=true runs the same checks and answers the terms the candidate would see, with id and url null. Nothing is made.
curl -X POST "https://api.certo.bio/v1/apply-sessions?dry_run=true" \
-H "Authorization: Bearer $CERTO_API_KEY" \
-H "content-type: application/json" \
-d '{"position_id": "0192f1c4-7a10-7c2e-9d41-3b8e2f0a5c11", "include_contact": true}'
Sending it twice
Send an Idempotency-Key (a new UUID per click) and retry with the same key if the call timed out: the first answer comes back and no second session is made (Errors, limits and retries).
When a session is spent or late
| Code | What happened | What to do |
|---|---|---|
apply.session_used | An Apply already spent it: a second popup with the same id, a double click, a link reused | Make a new session on every click; disable your button while the popup is open |
apply.session_expired | An hour passed and nobody applied | Make sessions on the click, not on page load |
apply.paused | Apply with certo is off for your company | Switch it on |
apply.position_invalid, apply.position_closed | The position is not yours, or not open | Name an open position of yours |
apply.not_allowed | The key lacks hiring:invite | Use a key with it |
apply.rate_limited | More than 5000 sessions in an hour | Make them on the click only |
A session opens only from one of your live sites, as every button does.