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

Make an apply session

POST/v1/apply-sessionsscope hiring:invite

An apply session for one click on your site (workflow b): the terms (each optional: left out, a term falls back to the named position's, then to your general application's), the job in your words, your state and your own data, bound on your server, never on the page. Open it with the button (data-certo-apply) or the url it answers. One Apply spends it; unused, it expires after an hour. Apply with certo must be switched on (apply.paused). Try it with ?dry_run=true: the resolved terms, nothing made.

Query parameters

NameTypeDescription
dry_runbooleantrue: the same checks and the terms the candidate would be shown; nothing is made.

Request body

NameTypeRequiredDescription
position_iduuid or nullAn open position of yours: its terms are the defaults and the application is filed under it. Null or absent: none.
scope_typesarray of one of employment, education, certification, role, language, right_to_work, driving_licence or nullWhat the candidate is asked to share: record types, or null (or every one) for all of them.
include_contactbooleanAsk for the candidate's contact details too.
include_birth_datebooleanAsk for the date of birth too (with birth_date_reason).
birth_date_reasonstring or nullWhy the date of birth is needed, 3 to 280 characters; required with include_birth_date. The candidate reads it.
requirementsobject or nullWhat the candidate must have ready, docs/request-requirements.md: {"v": 1, "work_years", "education_min_level", "certifications", "right_to_work", "driving_licence" (null, or the categories a verified licence must carry, [] any), "contact"}; null for the defaults.
jobobjectThe job in your words, shown to the candidate and answered back; with a session the button's words are ignored.
job.refstring or nullYour reference for the job, at most 200 characters of plain text.
job.titlestring or nullThe job's title, at most 120 characters (a position's own title wins).
job.hiring_companystring or nullThe hiring company, for a job board's listing, at most 120 characters: shown as your words, never verified.
job.urlstring or nullThe job's page, http or https, at most 2048 characters.
statestring or nullYour nonce for this click, at most 200 printable characters without spaces, quotes or angle brackets: answered back on the application, the token and the webhook.
custom_dataobject or nullYour own data on the application: any JSON object (an id from your ATS or HR system, a requisition number), at most 4096 bytes. certo stores it and answers it back on the reads and in your webhook events; it never reads it, and the candidate never sees it. Copied onto the application the session makes.

Response fields

dry_run
boolean. Whether this was a dry run.
apply_session
object. The session (would be made, in a dry run).
apply_session.id
string or null. as_...: what the button opens (data-certo-apply="as_..." or CertoApply.open). Null in a dry run.
apply_session.url
string or null. The plain link, https://certo.bio/apply/<id>, to open in a popup; null in a dry run.
apply_session.expires_at
string. An hour from now: unused by then, it answers apply.session_expired.
apply_session.position_id
uuid or null. The position the application will be filed under, or null.
apply_session.terms
object. The terms the candidate applied on: what you may read. A snapshot, kept as it was at Apply whatever changes later.
apply_session.terms.source
one of general, position, session. Where the terms came from: general (your general application), position (the position's), session (an apply session your server made).
apply_session.terms.scope_types
array of string or null. The record types the candidate shares; null for every one.
apply_session.terms.include_contact
boolean. The candidate's contact details are shared.
apply_session.terms.include_birth_date
boolean. The date of birth is shared.
apply_session.terms.birth_date_reason
string or null. Why the date of birth is asked, as the candidate read it; null without it.
apply_session.terms.requirements
object or null. What the candidate should have ready (docs/request-requirements.md); null for the defaults.

Errors

  • 409 apply.paused
  • 400 apply.position_invalid
  • 409 apply.position_closed
  • 409 apply.general_terms_missing
  • 400 apply.terms_invalid
  • 400 apply.field_invalid
  • 403 apply.not_allowed
  • 429 apply.rate_limited
  • 400 custom_data.invalid
  • 400 request.unknown_field
  • 409 api.idempotency_mismatch
  • 409 api.idempotency_in_progress
  • 400 api.credential_in_url
  • 401 api.key_invalid
  • 401 api.key_expired
  • 401 api.key_revoked
  • 401 api.key_suspended
  • 403 api.scope_missing
  • 429 api.rate_limited