Help center
https://api.certo.bio/v1openapi.json
Make an apply session
POST
/v1/apply-sessionsscope hiring:inviteAn 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
| Name | Type | Description |
|---|---|---|
| dry_run | boolean | true: the same checks and the terms the candidate would be shown; nothing is made. |
Request body
| Name | Type | Required | Description |
|---|---|---|---|
| position_id | uuid or null | An open position of yours: its terms are the defaults and the application is filed under it. Null or absent: none. | |
| scope_types | array of one of employment, education, certification, role, language, right_to_work, driving_licence or null | What the candidate is asked to share: record types, or null (or every one) for all of them. | |
| include_contact | boolean | Ask for the candidate's contact details too. | |
| include_birth_date | boolean | Ask for the date of birth too (with birth_date_reason). | |
| birth_date_reason | string or null | Why the date of birth is needed, 3 to 280 characters; required with include_birth_date. The candidate reads it. | |
| requirements | object or null | What 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. | |
| job | object | The job in your words, shown to the candidate and answered back; with a session the button's words are ignored. | |
| job.ref | string or null | Your reference for the job, at most 200 characters of plain text. | |
| job.title | string or null | The job's title, at most 120 characters (a position's own title wins). | |
| job.hiring_company | string or null | The hiring company, for a job board's listing, at most 120 characters: shown as your words, never verified. | |
| job.url | string or null | The job's page, http or https, at most 2048 characters. | |
| state | string or null | Your 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_data | object or null | Your 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