https://api.certo.bio/v1openapi.json

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.

FieldWhat
position_idOne 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, requirementsThe terms, as a position takes them
jobref (200 characters), title (120), hiring_company (120), url (http or https, 2048)
stateYour value for this click, at most 200 printable characters without spaces, quotes or angle brackets
custom_dataYour 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

CodeWhat happenedWhat to do
apply.session_usedAn Apply already spent it: a second popup with the same id, a double click, a link reusedMake a new session on every click; disable your button while the popup is open
apply.session_expiredAn hour passed and nobody appliedMake sessions on the click, not on page load
apply.pausedApply with certo is off for your companySwitch it on
apply.position_invalid, apply.position_closedThe position is not yours, or not openName an open position of yours
apply.not_allowedThe key lacks hiring:inviteUse a key with it
apply.rate_limitedMore than 5000 sessions in an hourMake them on the click only

A session opens only from one of your live sites, as every button does.