Hooks reference

Runs once on plugins_loaded, after every active module has booted: it fires after vakanssi/modules/register and vakanssi/modules/loaded, so it is too late to register a module (a module registered here is listed as active but its boot() never runs). Register modules on vakanssi/modules/register; use this hook for work that needs the booted plugin.

Both hooks fire before a theme’s functions.php loads, so add them from a plugin or a must-use plugin.

Activation finished: schema migrated, roles and capabilities installed, protected storage provisioned, default stages seeded, retention cron scheduled.

Plugin deactivated: cron events cleared, rewrite rules flushed. Non-destructive, no data removed.

Fires while an in-place version upgrade is being applied: after the schema migration completes, before the new version (VAKANSSI_VERSION) is recorded, checked on both init and admin_init. It also fires once when the plugin’s files are replaced at the same version by a copy that creates a different set of database tables, such as switching between the free and premium builds.

If a listener does not finish, a fatal error or a timeout partway through the chain, the version is left unrecorded and this hook fires again on the next request, so listeners must be idempotent.

The always-on Core module booted, before vakanssi/booted.

dbDelta() created or upgraded all tables, every table and unique index was confirmed present, and the schema-version option was stored. An incomplete migration does not fire it; the next request retries.

Register custom feature modules. Call $registry->register( $module ) with a ModuleInterface. It fires on plugins_loaded, before a theme’s functions.php is loaded, so a callback added from a theme never runs: register it from a plugin or a must-use plugin.

ModuleRegistry::register() takes a Vakanssi\Core\Modules\ModuleInterface; the first registration of an id wins. If your callback on vakanssi/modules/register, or your module’s own boot(), throws, the registry catches it, logs it, and continues: it does not take the rest of the site down. A throw on vakanssi/modules/register does end that hook early, though, so callbacks queued after yours on it never run. See Architecture: the module system.

// Register a custom module (Acme_Referrals_Module implements
// Vakanssi\Core\Modules\ModuleInterface).
add_action( 'vakanssi/modules/register', function ( $registry ) {
    $registry->register( new Acme_Referrals_Module() );
} );

Every active module has booted in dependency order.

Contribute tabs to Hiring, then Settings. Call $registry->add( $tab ).

SettingsRegistry::add() requires id and render; label, capability (defaults to the manage-settings capability), and priority (default 50, lower sorts first) are optional. The first registration of an id wins, and a tab shows only to users who hold its capability.

// Add a "Job boards" tab to Hiring > Settings.
add_action( 'vakanssi/settings/tabs', function ( $registry ) {
    $registry->add( array(
        'id'       => 'acme-job-boards',
        'label'    => 'Job boards',
        'priority' => 60,
        'render'   => function () {
            echo '<h2>Job boards</h2><p>Feed configuration for external job boards.</p>';
        },
    ) );
} );

Register REST routes alongside Vakanssi’s own, on rest_api_init.

Whether Vakanssi removes other plugins’ admin_notices and all_admin_notices callbacks on its own screens. Only callbacks declared in another plugin, a must-use plugin, or a theme are removed.

WordPress core’s own notices (updates, recovery mode, paused plugins, privacy policy), Vakanssi’s own, and anything whose file lies outside every plugin and theme folder (a drop-in, say) are always kept. A callback whose file cannot be determined, such as a built-in PHP function, is removed. Return false to let every plugin’s notices show as usual.

// Let every plugin's notices show on Vakanssi screens too.
add_filter( 'vakanssi/admin/suppress_foreign_notices', '__return_false' );

Whether a user counts as hiring-only: they can view applications but hold no edit_posts or manage_options capability. Drives both hooks below. Return false to exempt a specific user.

The URL a hiring-only user is sent to on login, in place of the generic WordPress dashboard. Only overrides the plain “go to wp-admin” default; a deep link the user or another plugin requested is always respected.

// Send hiring-only users to the applications inbox instead of Hiring HQ.
add_filter( 'vakanssi/admin/workspace_url', function ( string $url, int $user_id ): string {
    return admin_url( 'admin.php?page=vakanssi-candidates' );
}, 10, 2 );

Whether the generic core dashboard widgets (Quick Draft, WordPress news, Site Health, and similar) and the welcome panel are removed for a hiring-only user who opens the Dashboard. Third-party widgets are left in place.

The resolved visitor IP. When the request arrived from a trusted proxy, this is CF-Connecting-IP or the right-most X-Forwarded-For entry that is not itself a trusted proxy; otherwise it falls back to REMOTE_ADDR, the direct connection address.

Runs last, after the proxy mode and the trusted-proxy list, so a value returned here overrides both. Every per-IP consumer reads it: the apply-form abuse counters, the anti-spam challenge providers, and the audit log. Returning a header a visitor controls defeats all of those counters at once.

// Trust a load balancer's custom header instead of the built-in modes,
// but only on requests that actually arrived from that load balancer.
add_filter( 'vakanssi/http/client_ip', function ( string $ip, string $mode ): string {
    if ( 'off' === $mode && '10.0.0.5' === $ip && ! empty( $_SERVER['HTTP_X_REAL_IP'] ) ) {
        $candidate = sanitize_text_field( wp_unslash( $_SERVER['HTTP_X_REAL_IP'] ) );
        return filter_var( $candidate, FILTER_VALIDATE_IP ) ? $candidate : $ip;
    }
    return $ip;
}, 10, 2 );

The proxies whose forwarded client-IP headers this site believes, as IPv4/IPv6 addresses or CIDR ranges. Only consulted when Visitor IP source is cloudflare or forwarded; in cloudflare mode the list arrives pre-seeded with the published Cloudflare edge ranges, so return a narrower list to override them entirely.

The VAKANSSI_TRUSTED_PROXIES constant (array or comma-separated string, set in wp-config.php) feeds the same list and is usually the simpler way to add one address.

An entry here means “a request arriving FROM this address has a trustworthy forwarded header”: list your own infrastructure, never a client.

// A second reverse proxy sits between Cloudflare and the origin.
add_filter( 'vakanssi/http/trusted_proxies', function ( array $proxies, string $mode ): array {
    $proxies[] = '10.0.0.0/8';
    return $proxies;
}, 10, 2 );

The full register_post_type() args for vakanssi_job (labels, rewrite slug, has_archive, show_in_rest, supports, capabilities), immediately before the type is registered. To move job URLs, use the Job URL base setting or vakanssi/jobs/permalink_base below rather than editing rewrite here, since that base also drives the archive.

// Keep job pages out of the site's own search results.
add_filter( 'vakanssi/jobs/post_type_args', function ( array $args ): array {
    $args['exclude_from_search'] = true;
    return $args;
} );

The features the job type supports (title, editor, excerpt, revisions, author, custom-fields), before post_type_args.

Since v0.33.30, thumbnail is not in the default list: a job posting is a document, not an article, and a decorative photo above the role only pushed the details table and the apply button further down. Neither the listing nor the JobPosting schema ever read it.

Adding it back below only restores the editor panel. Rendering the image is then the theme’s own work, through the Site Editor on a block theme or a child-theme copy of templates/single-jobs.php on a classic one.

// Restore the featured-image panel in the job editor.
add_filter( 'vakanssi/jobs/supports', function ( array $supports ): array {
    $supports[] = 'thumbnail';
    return $supports;
} );

The URL base jobs register under (rewrite slug and archive), after the Job URL base setting has been read. Sanitized with sanitize_title() afterwards; an empty result falls back to jobs.

// Serve job pages under /careers/ instead of /jobs/.
// Visit Settings > Permalinks once afterwards to flush rewrite rules.
add_filter( 'vakanssi/jobs/permalink_base', function ( string $base ): string {
    return 'careers';
} );

The JobPosting JSON-LD array before output. Return [] to suppress. title and the organization name arrive as plain text, not HTML entities (an apostrophe reads as ', not ’).

Whether Vakanssi emits JobPosting for a job (coexistence with SEO plugins). Only consulted on a single job page, when the JobPosting structured data setting leaves the schema to Vakanssi and the job is eligible for it; $post is get_post() at wp_head.

Hiring-organization name used in schema. Default: the company name setting, falling back to the site title when that is empty.

HTML for the on-page apply call-to-action. The default is an “Online applications for this position open soon.” notice, and the Intake module replaces it with the form at priority 10. Not reached for a closed job or one with an external apply URL, which render their own markup.

Escaped with Svg::apply_form() wherever it is printed (the job page, [vakanssi_job_apply], the Elementor Apply widget); see the escaping note above.

Whether a job has an internal apply path. On the job page and in the structured-data check, a job with an external apply URL never asks; for any other job the answer decides whether it qualifies for JobPosting structured data. The Intake module answers true while vakanssi/intake/enabled is on. Return true if you embed your own form.

The job editor’s readiness checklist asks for every job, external apply URL or not.

Which optional detail fields (salary, employment, closing) are shown, resolved from the Job details setting (Settings, then Jobs & Careers). Drives the visible block and the schema together, so structured data never advertises a field the page hides. A key missing from the returned map counts as visible.

Fires at the end of the job editor’s Employment & application tab panel, still inside the same <form> as the rest of the Job details box. This is the supported way to add a section to that tab instead of registering a detached meta box, so your fields submit with the job’s own form.

Saving them is still your code’s job: Vakanssi’s save handler reads only its own fields, so hook save_post_vakanssi_job to store yours.

Screening Pro feature, requires a Vakanssi Pro license uses this seam for its per-job question set. Nothing listens in the free build, where it is a no-op.

// Add an internal "hiring budget code" field to the job editor.
add_action( 'vakanssi/jobs/app_tab', function ( WP_Post $post ) {
    $code = get_post_meta( $post->ID, '_acme_budget_code', true );
    wp_nonce_field( 'acme_budget_code', 'acme_budget_code_nonce' );
    printf(
        '<p><label for="acme-budget-code">Budget code</label><br /><input type="text" id="acme-budget-code" name="acme_budget_code" class="regular-text" value="%s" /></p>',
        esc_attr( $code )
    );
} );

The visible detail rows before render: add, remove, reorder, or relabel. Both cells are escaped by the renderer, so a label or value returned here must be plain text, not HTML. A row with an empty label and value is skipped.

The assembled detail block markup (values already escaped). Return your own HTML to replace it, or an empty string to remove the block. Escaped with Svg::rich() for [vakanssi_job_details] and the Elementor Job Details widget, and with Svg::apply_form() on the job page; see the escaping note above.

The “Other open roles” block on a single job page. Return your own HTML, or an empty string to remove it. Escaped with Svg::apply_form(); see the escaping note above. The hide_related setting drops the block before this filter is reached.

It is also not called when there are no other open roles to list, on a password-protected job, or on an expired job whose page shows only the closed notice, so it cannot add a block where none would render.

The careers archive heading, on both a classic theme’s templates/archive-jobs.php and, since v0.33.28, a block theme’s Site Editor template.

On a block theme the title is read when the template registers, on init at priority 10, since that is where register_block_template() itself has to run. A callback added at file scope, on plugins_loaded, or in a theme’s functions.php is in time; one added on wp or later is not. A classic theme reads the filter on every request instead, so timing does not matter there.

// Rename the careers page heading.
add_filter( 'vakanssi/jobs/archive_title', function ( string $title ): string {
    return 'Careers at Acme';
} );

Path to the careers archive template on a classic theme. A theme’s own archive-vakanssi_job.php, in the theme root or a vakanssi/ subfolder, still wins. Not called when a block theme is active (a Site Editor template resolves instead) or when the theme cannot supply get_header() and get_footer().

Jobs per page on the built-in /jobs/ archive main query. Clamped to 1 through 100.

Which command-bar controls a [vakanssi_jobs] listing renders, resolved from the filters attribute. Add or remove any of search, department, remote, sort; return [] to drop the bar entirely. Runs last, so it can restore a bar on a placement that set filters="false".

Cannot force the team picker onto a listing with only one team, since that check runs after this filter. The return value is re-sanitized against the four known names.

// Drop the sort control from every careers listing, keep the rest.
add_filter( 'vakanssi/jobs/bar_controls', function ( array $controls, array $atts ): array {
    return array_values( array_diff( $controls, array( 'sort' ) ) );
}, 10, 2 );

Path to the single-job template used in “Vakanssi layout” mode (a theme single-vakanssi_job.php, in the theme root or a vakanssi/ subfolder, still wins). Not called at all when the single_template setting is theme, when a block theme is active (a Site Editor template resolves instead), or when the theme cannot supply get_header() and get_footer().

The WP_Query args behind every [vakanssi_jobs] listing that runs its own query, after the shortcode attributes are resolved. The built-in /jobs/ archive does not: its template renders [vakanssi_jobs archive="main"], which consumes the main query, so shape that one with vakanssi/jobs/archive_per_page or pre_get_posts.

It also runs for each listing’s helper queries: an ids-only count probe (fields => 'ids', posts_per_page => 1) and the all-teams lookup behind the team picker (posts_per_page => -1). A callback that sets posts_per_page or fields unconditionally breaks the page count and the picker, so leave those keys alone when they are already set.

Since v0.33.7, a paginated listing (see Pagination) already carries paged and no_found_rows => false in $args; leave those alone, or the count line and the page nav lose the total they’re built from.

The markup for one job row, immediately before it is printed. The result goes through wp_kses() with the plugin’s rich allowlist: post markup, inline SVG, and data-* attributes survive; scripts, event handlers, <form>, <input>, and <select> do not.

The markup shown when a listing matches no roles: the empty_message attribute, or “There are no open positions right now.”, already escaped. Escaped with Svg::board(); see the escaping note above.

Fires when a job has closed because its closing date passed, found by the daily vakanssi/cron/expiry_purge sweep (see Cron events below). Since v0.33.36, the sweep calls clean_post_cache() on the job first, which every major page cache listens to, and fires this once per job. Saving the job clears that once-only marker, so a job saved again while still past its closing date fires it again at the next sweep.

Unlike an operator closing a job, this edits no post, so none of the save_post hooks a page cache listens to fire. Hook it to purge what clean_post_cache() cannot reach: a CDN, a reverse proxy, or the careers archive, which is a URL with no post behind it.

// Purge the careers archive from a CDN when a role closes on its own.
add_action( 'vakanssi/jobs/expired', function ( int $job_id ) {
    acme_cdn_purge( get_post_type_archive_link( 'vakanssi_job' ) );
} );

Expired jobs purged per sweep run, floored at 1. A full batch chains a follow-up run a minute later, up to 20 follow-ups, so one day handles at most 21 batches (2,100 jobs at the default).

A new application was captured, after the database commit and after vakanssi/cv/stored. From the public apply form, $data holds job_id, first_name, last_name, email, phone, linkedin_url, cover_letter, applicant_country, consent, consent_basis, source (native), referrer, and attach_cv_on_reapply, plus anything a vakanssi/intake/data callback attached (Screening Pro feature, requires a Vakanssi Pro license adds screening).

The admin Add application screen fires it too, with a shorter $data (no linkedin_url, consent_basis, referrer, or attach_cv_on_reapply; consent is false; source is what staff picked, or manual). A resubmission collapsed into an existing application does not fire it again.

// Post to Slack whenever a new application is captured.
add_action( 'vakanssi/application/created', function ( int $application_id, int $candidate_id, array $data ) {
    wp_remote_post( 'https://hooks.slack.com/services/T000/B000/XXXX', array(
        'headers' => array( 'Content-Type' => 'application/json' ),
        'body'    => wp_json_encode( array(
            'text' => sprintf(
                'New application #%d from %s %s for job #%d',
                $application_id,
                $data['first_name'],
                $data['last_name'],
                $data['job_id']
            ),
        ) ),
    ) );
}, 10, 3 );

The URL an applicant is redirected to after a successful submission. Still goes through wp_safe_redirect(): the filtered URL’s host is added to allowed_redirect_hosts for this one redirect only, so a same-host or cross-host URL (a hosted “thank you” page, for instance) survives.

A URL that still fails wp_safe_redirect()’s own validation (a scheme other than http or https, for instance) falls back to WordPress’s safe-redirect fallback, which is the admin URL unless something filters wp_safe_redirect_fallback. A logged-out applicant sent there lands on the login screen, so always return an absolute http or https URL.

Master switch for the native intake form per job. Returning false hides the form on the job page AND closes the write endpoint for that job: CaptureService::job_closed() applies this same filter as its authoritative gate, so a submission cannot bypass it by posting directly. A visitor sees “Online applications for this position open soon.”

It is never consulted for a job with an external apply URL, which the endpoint refuses before this check. The Intake module also answers vakanssi/jobs/has_apply_path from it, so returning false on a job without an external URL marks the job as having no way to apply, which keeps it out of JobPosting structured data.

This gate applies to the public endpoint only. The Add application button on the Applications screen, for logging a candidate who applied by email or was sourced by your own team, does not opt into it, so staff can still record someone against a job with the native form switched off.

Whether the consent checkbox is rendered and enforced. Read separately by the form and by the submit handler, so answer it the same way on both. With it off, the retention note below is not shown either.

Consent checkbox label HTML: the consent sentence plus a Privacy policy link when the site has a privacy policy page. Printed through wp_kses_post(); since v0.37.9, scripts, styles, and other unsafe elements are also stripped first, with their contents.

The short retention disclosure rendered as small print beneath the submit button, for instance “We keep your application for up to 24 months, then delete it.” $months is the with-consent window from vakanssi/retention/months (the retention_months_consent setting, shipped default 24). Return '' to hide the note.

The filter only runs when the note is enabled (Settings, then General, then Data retention, “Show on the apply form”; off by default) and the consent checkbox is required, so it customizes the wording rather than turning the note on. The note is escaped when printed, so return plain text.

Fires inside the open <form>, after the applicant fields (cover letter last) and before the consent checkbox and submit button, so extensions can inject fields. Screening Pro feature, requires a Vakanssi Pro license hooks this at priority 10 to render its question set, and the anti-spam challenge widget renders here at priority 20.

Name every field you print with vakanssi/intake/posted_fields below. A field that is not named there is not passed to the spam check and is not kept when the form is shown again after an error.

Since v0.37.9, what you echo here is part of the apply form and is escaped with it using Svg::apply_form() (see the escaping note): standard form markup survives, scripts and styles are removed with their contents.

$retained carries the applicant’s own previously submitted values when the form is re-rendered after a validation failure (see vakanssi/intake/validate below). Honor it if your field can hold a value: the intake form already tells the applicant “your answers have been kept below”, so silently blanking a field you added makes that message false.

Since v0.34.1, the sanitized submission data after the built-in checks (spam check, name and email, consent, CV present, job open) and before vakanssi/intake/validate, the CV file check, capture, and vakanssi/application/created.

This is where a module that collects its own fields on the apply form attaches them, so the rest of the pipeline reads one resolved value instead of each consumer reaching back into $_POST. Screening Pro feature, requires a Vakanssi Pro license attaches the applicant’s answers here under screening.

It runs before vakanssi/intake/validate, so a validator can read what was attached, and before the spam counters, so a rejected submission costs no quota. It therefore also runs for submissions that are about to fail: keep callbacks pure and cheap, and write nothing here.

Capture reads named keys only and never iterates the array, so a key you add is not stored by Vakanssi; it simply travels through to the vakanssi/application/created payload. The admin Add application screen calls capture directly and never passes through this filter.

// Attach a referral code your own form field collects (named on posted_fields).
add_filter( 'vakanssi/intake/data', function ( array $data, int $job_id ): array {
    // phpcs:ignore WordPress.Security.NonceVerification.Missing
    $code = isset( $_POST['acme_referral'] ) ? sanitize_text_field( wp_unslash( $_POST['acme_referral'] ) ) : '';
    $data['acme_referral'] = $code;
    return $data;
}, 10, 2 );

Extra required-field validation beyond the built-in checks. Screening Pro feature, requires a Vakanssi Pro license hooks this to enforce its required-answer rule. Runs in the same validation phase as the built-in required-field checks, before the spam rate-limit and burst counters increment, so a rejection here does not count against those limits either.

Return one or more error strings to reject the submission. The handler joins them with a space into a single notice and redirects back to the form, the same way a built-in required-field failure does. An empty array (the default) means no extra failures.

// Require a minimum cover letter length.
add_filter( 'vakanssi/intake/validate', function ( array $errors, array $data, int $job_id ): array {
    $cover_letter = isset( $data['cover_letter'] ) ? (string) $data['cover_letter'] : '';
    if ( strlen( trim( $cover_letter ) ) < 50 ) {
        $errors[] = 'Please write at least a few sentences in your cover letter.';
    }
    return $errors;
}, 10, 3 );

The request field names the apply handler reads. Only these are passed to vakanssi/intake/spam_check and kept for the retry after a validation error, or after a challenge the applicant did not complete or that could not be checked; any other posted field is left out of both. Defaults to the built-in applicant fields (first_name, last_name, email, phone, linkedin_url, cover_letter, applicant_country, consent) and the honeypot and time-trap fields.

The retry never keeps the anti-spam fields themselves: the honeypot, the time-trap token, and the active challenge’s token field, as its request_field() method names it, since a credential is not something the applicant typed.

The active anti-spam challenge adds its token field, and Screening Pro feature, requires a Vakanssi Pro license adds screening. The handler also reads job_id, its nonce, and the compatibility-test marker by name, the referer through wp_get_referer(), and the CV through $_FILES. Return the array with your names appended.

// Keep a custom apply-form field across a validation error.
add_filter( 'vakanssi/intake/posted_fields', function ( array $names, int $job_id ): array {
    $names[] = 'acme_referral';
    return $names;
}, 10, 2 );

Whether a bad or missing apply nonce hard-fails the submission. Anonymous submitters default to false, so a stale nonce (a cached job page, for example) falls through to the time-trap, honeypot, rate limit, and CAPTCHA instead. Logged-in submitters default to true. Return true to make the nonce mandatory for everyone, which rejects submissions from cached job pages whose nonce has expired.

The spam decision, after the honeypot, time-trap, and rate-limit checks have passed. Return a WP_Error to reject with its message, or false to reject with the generic spam message; a later callback returning true overturns either. The built-in anti-spam challenge runs at priority 10 and passes an earlier rejection through unchanged.

A refusal whose only error codes are vakanssi_captcha_missing (no challenge token posted) or vakanssi_captcha_unavailable (the challenge could not be checked) keeps the applicant’s typing and does not count against vakanssi/intake/attempt_limit. Any other refusal, a rejected token included, clears the form and counts.

$request holds only the sanitized fields named by vakanssi/intake/posted_fields; name any field your check reads there.

// Reject disposable email domains at submit time.
add_filter( 'vakanssi/intake/spam_check', function ( $result, array $request ) {
    if ( true !== $result ) {
        return $result; // An earlier check already rejected it.
    }
    $email  = isset( $request['email'] ) ? (string) $request['email'] : '';
    $domain = strtolower( (string) substr( strrchr( $email, '@' ), 1 ) );
    if ( in_array( $domain, array( 'mailinator.com', 'trashmail.com' ), true ) ) {
        return new WP_Error( 'acme_disposable', 'Please apply with a personal or work email address.' );
    }
    return $result;
}, 10, 2 );

The registered anti-spam challenge providers, id => SpamProvider. The free plugin registers none and turnstile; Advanced anti-spam Pro feature, requires a Vakanssi Pro license appends hcaptcha and recaptcha_v3, and your own adapter can append another. A non-array return falls back to the defaults.

A provider’s render_field() markup is printed through wp_kses(): a placeholder element with class and data-* attributes survives, a <script> does not (enqueue it instead). verify() receives only the fields named by vakanssi/intake/posted_fields, so a provider whose widget posts a token names that field with a public request_field() method or on that filter. Without either, the token never reaches verify() and a provider that rejects a missing token refuses every applicant.

Every provider method is called inside a guard. One that throws, or answers the wrong type, is logged to the PHP error log once per class and method, never with the exception message. (is_configured() is the exception: its answer is cast to a boolean, so only a throw counts as a fault there.)

When verify() fails that way, id() throws or answers an empty id, or is_configured() throws while someone applies, the application gets the vakanssi/antispam/fail_open answer below instead of an error page; a failing render_field() just leaves the widget off the job page.

Whether a challenge that could not be checked is treated as a pass, so a provider outage never blocks a real applicant. It covers a siteverify transport failure (network error, timeout, malformed response), and a fault in the active provider: verify() throwing or answering the wrong type, id() throwing or answering an empty id, or is_configured() throwing.

$error is the transport WP_Error in the first case and a generic vakanssi_captcha_unavailable error in the second; the provider’s own message is never passed on, because it can carry its secret key or the applicant’s token. A callback that throws is logged and the submission is refused. The honeypot, time-trap, and rate limit have already run either way.

That vakanssi_captcha_unavailable refusal keeps the applicant’s typed answers and costs no attempt against vakanssi/intake/attempt_limit (see vakanssi/intake/spam_check above).

Time-trap minimum submit time. Faster submissions are rejected.

Time-trap maximum token age. Also the freshness window for the cache-proof fallback that vakanssi/intake/require_apply_nonce enables: a submission older than this is rejected even with a valid time-trap signature.

How many applications one IP may submit inside the rate window before being refused.

The rate-limit window in seconds. The attempt limit, the burst limit, and the retry-storage cap below are all counted over this same window.

How many counted hits one IP may make inside the rate window before every further request is refused. Counted: a hard nonce failure, a spam refusal (honeypot, time-trap, rate limit, a rejected challenge token, a third-party refusal), and every submission that passes validation. Deliberately more generous than vakanssi/intake/rate_limit.

An ordinary validation failure, a missed or unavailable anti-spam challenge included, does not count against it, so a fumbling applicant is never locked out. 0 or less disables it.

How many successful submissions the whole site accepts inside the rate window, a backstop against distributed floods that rotate IPs. 0 or less disables it.

Max CV downloads per logged-in user before one more returns HTTP 429. Each allowed download restarts a one-minute timer, so the count resets only after a full minute without downloads, not once per clock minute. Keyed by user id, not IP; only requests that pass the nonce and permission checks count.

Whether a submission to a job past its closing date is rejected with vakanssi_job_closed. Return false to let expired jobs keep accepting applications server-side. Checked during validation (before the abuse counters increment) and again inside capture, so the answer is the same on both paths. The admin Add application screen is subject to it too.

Whether a resubmission to a job the candidate already has an ACTIVE application for (a double-click, a resubmit) is collapsed into that existing application instead of creating a second one. A prior application that already reached a terminal status (rejected, withdrawn, hired) or was anonymized by retention is not a match, a fresh application is created as usual.

Shared by the public apply form and the admin “Add application” screen. Return false to restore the old always-create-a-new-row behavior. On the public form, a CV attached to the collapsed resubmission is kept (see vakanssi/intake/max_files_per_application below) rather than discarded; the admin “Add application” screen does not opt into that, since a member of staff is present to resolve the duplicate directly.

Maximum CVs one application may accumulate from repeated public applications with a corrected file. A byte-identical resubmission is always recognized by content hash and ignored regardless of this cap; only once past the cap is a genuinely new file discarded. 0 or less means no cap.

Max retry-payload transients (the prefilled-form state shown after a rejected submission) stored per IP within the rate-limit window. A separate budget from vakanssi/intake/attempt_limit (both default to 20), so validation failures never burn that one. Once exceeded, the applicant still sees the rejection message, just without the fields pre-filled on retry.

Retention period for the stored application. The value passed in is the admin-configured Data retention setting (Settings → General; retention_months_consent/retention_months_no_consent, shipped defaults 24 with consent and 6 without), which a filter callback can still override.

Every non-Intake call site passes false (the no-consent window), except RetentionService::repair_missing_deadlines(), the one-time upgrade repair for a legacy application with no retention deadline at all, which passes that row’s own consent_given flag so a legacy row that actually recorded consent is repaired onto the longer consent window rather than the shorter one. Everywhere a deadline is stored, the value is cast to int and floored at 1.

It is also applied, with $consent set to true, when the apply form renders the optional retention note (see vakanssi/intake/retention_note). There a value below 1 hides the note instead of being floored.

Normalized email used for candidate dedup (lower-cased, +tag stripped, Gmail dots removed). Backs the unique key.

Absolute path of the protected CV storage directory: uploads/vakanssi by default, or the VAKANSSI_STORAGE_DIR constant when one is defined. On multisite this is the per-site directory (the storage root plus a site-<id> segment), so a callback returning one fixed path makes every site of the network share one CV directory: include the blog id if you override it there.

Accepted CV upload types. Default: the types enabled in the Accepted CV file types setting, a subset of pdf, doc, and docx (all three when unset). This is what the upload path enforces; the form’s accept attribute is only a hint. A type added here has no built-in file-signature check, so it relies on WordPress’s own wp_check_filetype_and_ext() alone.

The same filter is also applied to the full pdf/doc/docx map to decide which Content-Type a stored file is served with. A file whose type is not in that list still downloads, as application/octet-stream. Unticking a built-in type in the setting therefore never changes how files already received are served.

Whether an uploaded CV is accepted, checked after every built-in check (mime allowlist, size cap, magic-byte signature) already passed.

VETO-ONLY: return false or a WP_Error to reject a file the built-in checks would have accepted (virus scanning, content DLP); it can never accept a file a built-in check already rejected, because it never runs for one. A WP_Error’s message is shown to the applicant as the upload error; a plain false gets a generic rejection message.

On the public apply form it runs twice for the same file: once in the validation phase and again when the file is stored. A slow scanner should cache its verdict per $tmp_path rather than scan twice.

// Reject a CV that fails a virus scan, on top of the built-in checks.
add_filter( 'vakanssi/storage/validate_file', function ( $verdict, string $tmp_path, string $original_name, string $mime ) {
    if ( is_wp_error( $verdict ) || ! $verdict ) {
        return $verdict; // An earlier check already rejected it.
    }
    if ( ! acme_clamav_scan( $tmp_path ) ) {
        return new WP_Error( 'acme_virus', 'This file failed a security scan.' );
    }
    return true;
}, 10, 4 );

Max CV upload size in bytes. On the apply form the default is the Maximum CV file size setting (5 MB unless changed), clamped to the server’s own upload_max_filesize and post_max_size. The competitor importer applies the same filter with wp_max_upload_size() as its default when it copies CVs in.

Fires once per file, after it is durably stored AND its owning application exists. It covers an applicant’s initial CV (including one logged through Add application), a CV kept from a re-application, and a file staff attach to an existing application. CVs copied in by the competitor importer do not fire it.

The intended use is virus scanning or content DLP that needs to act on bytes already linked to a record; the veto-only vakanssi/storage/validate_file filter above runs earlier, before the bytes are written.

The resolved screening question set for a job, at the single point every consumer reads from: the apply form’s render, submission validation, answer storage, and the knockout evaluator, so a question added or removed here applies consistently across all of them.

Not applied to the wp-admin question editor, which reads the unfiltered stored set, so a filter-injected question can never be re-saved into post meta by an admin unaware it came from a filter.

Fires after a captured application’s screening answers are saved.

Fires after a submission is auto-rejected, moved to a lost-type pipeline stage, by a disqualifying screening answer. Only fires when auto-move is enabled and the move actually landed the application in a lost-type stage; a knockout that only sets the flag (auto-move is off by default) is recorded in the audit log only, with no candidate-facing consequence to report here.

The registered import sources (WP Job Openings, Simple Job Board, WP Job Manager by default). Every member must implement the undocumented SourceInterface, and anything else is dropped, as is a second source with a key already taken.

Detected but unsupported job-data sources reported to the user, each {post_type, label, jobs} in the detector’s own shape.

File extensions the importer will copy into protected CV storage. Default: pdf, doc, docx, rtf, odt, txt. This allowlist and the vakanssi/storage/max_upload_size cap are the deterministic controls; the content check behind them is best effort, and an extension WordPress cannot map to a MIME type is copied anyway and stored as application/octet-stream.

A mapped row immediately before a competitor import inserts it, applied once per row across every import source. Returning null or false skips the row: the job or application row is not inserted, and it counts in the run’s skipped tally. For applications, the candidate record has already been created or merged by the time the filter runs, and it is kept.

This runs AFTER the built-in kses/sanitize step, so a callback owns sanitizing any value it adds or changes; any other non-array return is ignored and the original row is used unchanged, rather than risking a fatal on insert.

// Skip importing jobs from a department this site does not hire for.
add_filter( 'vakanssi/import/row', function ( $row, string $source_key, string $type ) {
    if ( 'jobs' === $type && str_contains( strtolower( (string) ( $row['post_title'] ?? '' ) ), 'intern' ) ) {
        return null; // Skip internships.
    }
    return $row;
}, 10, 3 );

Fires once, on the single batch call whose summary first reports the run as finished (both the jobs and applications phases reached the end of the source data), not on every intermediate batch.

Test-only: lets an integration test force the import id-map write to report failure, so the rollback path can be exercised.

Max size of the uploaded CSV file itself (not a CV; the spreadsheet).

Data rows read from the file before it is truncated.

Rows processed (created or skipped) per auto-continuing batch while the import runs.

How long the uploaded file and column mapping are kept while idle, so how long you can leave the mapping screen before you have to upload again. Floored at one minute.

An application’s stage actually changed (after the DB update and audit). $status is the derived status: rejected for a lost-type stage, hired for a won-type stage, otherwise active, except that a withdrawn application moved between open stages stays withdrawn. Fires exactly once per real move, from the request that performed it.

It does not fire for a no-op move (a move to the stage the application is already in, when the derived status also already matches; dropping a card back on its own column is the usual case) or for a request that loses a concurrent move race to another request performing the identical change, since the one real change already fired it.

// Push new hires to the HR system the moment they reach the Hired stage.
add_action( 'vakanssi/application/stage_changed', function ( int $application_id, int $stage_id, int $from, string $status ) {
    if ( 'hired' === $status ) {
        wp_remote_post( 'https://hris.example.com/api/hires', array(
            'body' => array( 'application_id' => $application_id ),
        ) );
    }
}, 10, 4 );

Fires after the rating is set, an application is withdrawn or reopened, or its details are edited in the drawer. A rating save sent without the expected_rating precondition fires it even when the rating did not change.

It is not a catch-all for every write: a stage move fires vakanssi/application/stage_changed above instead, assignment Pro feature, requires a Vakanssi Pro license fires vakanssi/application/assigned, and changing a stage’s type rewrites its applications’ status without firing either. Never fires for creation or deletion.

A permanent cascade delete completed (CV files, meta, linked rows, audit written).

The first time an application is viewed (drawer opened). At most once per application in normal operation.

Object-level authorization decision. Return false to deny even when the capability is held (the per-application scoping seam).

Semantic-action to capability map. The map is cached per policy instance: the shared instance reads it at the first authorization check, and a few code paths build their own. Add the filter on plugins_loaded or init, before any authorization check runs; a filter added later reaches some surfaces and not others. See Capabilities.

Extra SQL WHERE fragments that scope application collections: the inbox, the person list, the CSV export, the REST list, the Hiring HQ counts and cards, the Jobs list’s Applications column, and the Hiring menu’s unviewed count, plus the Analytics Pro feature, requires a Vakanssi Pro license and Presence Pro feature, requires a Vakanssi Pro license readers. Fragments reference the a. alias.

Premium build only: the wordpress.org build ships no SQL taken from a filter, so a callback added here never runs there, and those collections stay whole-org.

The contract: every fragment must reference the applications table through the a. alias, and every placeholder (%s, %d, %i) must have a matching entry in params, in order.

// Hiring managers only see applications for jobs they authored.
add_filter( 'vakanssi/authz/application_scope', function ( array $scope, int $user ): array {
    if ( user_can( $user, 'manage_options' ) ) {
        return $scope; // Administrators keep full visibility.
    }
    global $wpdb;
    $scope['clauses'][] = "a.job_id IN ( SELECT ID FROM {$wpdb->posts} WHERE post_author = %d )";
    $scope['params'][]  = $user;
    return $scope;
}, 10, 2 );

Extra SQL WHERE fragments that scope candidate collections: the Candidates Pro feature, requires a Vakanssi Pro license list and its source and tag filters, the duplicates screen, tag suggestions, and the candidates CSV export. Bulk actions are checked per id through vakanssi/authz/can instead.

Fragments reference the candidates table through the c. alias, with the same placeholder contract as vakanssi/authz/application_scope above. Premium build only: the free build does not fire it, and only the Pro build has a candidate list to call it.

The candidate-level companion to vakanssi/authz/application_scope, which scopes application collections only. A site adding per-recruiter scoping must answer both, or the board narrows while the candidate list stays org-wide. Pro Collaboration answers it when assignment scoping is on.

Narrows a set of application ids to the ones a user may see by scope alone, independent of the view-applications capability. Used where the ids are already in hand and no SQL scope applies: the candidate profile’s application history and the Presence payload, both Pro feature, requires a Vakanssi Pro license. Order is preserved and the result is re-indexed. Premium build only, like the two scope filters above.

The third member of the scoping trio with vakanssi/authz/application_scope and vakanssi/authz/candidate_scope: a site adding custom scoping answers all three, or the profile shows applications the board hides.

The single-application drawer payload. Add keys for custom drawer panels. application.job_title, each related row’s job_title, and the Interviews module’s interviews[] title, location, notes, interviewers, and interviewer_options[].name all arrive as plain text, not HTML entities.

Since v0.33.43, the application collection payload: one page of pipeline board cards, already shaped. The plural twin of vakanssi/rest/application_payload. The whole page arrives at once, so a callback that needs a per-application lookup can batch it into one query instead of one per card. Screening Pro feature, requires a Vakanssi Pro license adds its screening_knockout flag here. Each row’s job_title arrives as plain text, not HTML entities.

Return the same list, with the same ids, in the same order. A field you add here is what vakanssi.pipeline.card_markers (under JavaScript hooks below) sees on each card.

Since v0.33.43, quiet markers appended after a candidate’s name in the Applications List view, beside the built-in Withdrawn and repeat-applicant markers. For application-level flags a recruiter must see while triaging, without opening each application; the board-card equivalent is the JavaScript filter vakanssi.pipeline.card_markers.

Return already-escaped HTML strings. Each marker is printed through wp_kses(), which keeps only span (class, title, aria-label, aria-hidden), abbr (title), and strong, em, small (class); anything else is stripped. Keep each marker to a word or two. $items is the whole page, so a per-application lookup can be primed in one query on the first row.

// Mark applications that came in through a referral.
add_filter( 'vakanssi/pipeline/list_row_markers', function ( array $markers, array $item, array $items ): array {
    if ( 'referral' === ( $item['source'] ?? '' ) ) {
        $markers[] = '<span class="acme-referral">' . esc_html__( 'Referral', 'acme' ) . '</span>';
    }
    return $markers;
}, 10, 3 );

Extra sections for the printable/PDF application sheet, between the cover letter and the CV line. Echo already-escaped HTML. Exists so a module the free build strips (Screening) can add to the sheet without this free/core file naming a class that would fatal a free install; the Screening Pro feature, requires a Vakanssi Pro license module hooks in here to print the candidate’s screening answers and knockout flag.

// Add a custom section to the printable application sheet.
add_action( 'vakanssi/sheet/sections', function ( int $application_id, array $meta ) {
    echo '<section><h2>Internal reference</h2><p>App #' . esc_html( $application_id ) . '</p></section>';
}, 10, 2 );

The cross-application “Candidate history” bridge ({related, summary}) in the drawer payload, where it arrives as related and related_summary. Only those two keys are passed on, so change their contents rather than adding new keys. Not called for an application with no candidate record. (The board card’s repeat-applicant hint is counted separately in SQL and does not read this filter.) Each related row’s job_title arrives as plain text, not HTML entities.

Fires after a candidate’s person-level fields (contact details and/or enrichment) are updated, from either the pipeline drawer or the Candidates profile Pro feature, requires a Vakanssi Pro license, the single write path both surfaces go through.

From the drawer it fires before the whole edit commits, so a later failure in the same save can roll back a change a listener has already seen. Not fired on merge (see vakanssi/candidate/merged under Collaboration & sourcing below) or on candidate creation.

Extend the Applications list’s bulk-action dropdown, after the built-in “Move to: …” and “Delete permanently” entries have been added for the capabilities the current user actually holds. Pro Collaboration adds “Assign to: …” and “Unassign” here.

A key added here needs a matching handler on vakanssi/pipeline/bulk_result; an unclaimed key does nothing and redirects back with no result. Labels are plain text: Vakanssi escapes them with esc_html() before WordPress prints them, so do not pre-escape them or pass HTML.

// Add a custom "Notify hiring lead" bulk action to the Applications list.
add_filter( 'vakanssi/pipeline/bulk_actions', function ( array $actions ): array {
    $actions['acme_notify_lead'] = 'Notify hiring lead';
    return $actions;
} );

add_filter( 'vakanssi/pipeline/bulk_result', function ( $result, string $action, array $ids, int $user ) {
    if ( null !== $result || 'acme_notify_lead' !== $action ) {
        return $result; // Not ours to handle.
    }
    wp_mail( 'lead@example.com', 'Applications need a look', sprintf( '%d application(s): %s', count( $ids ), implode( ', ', $ids ) ) );
    return array( 'acme_notified' => count( $ids ) );
}, 10, 4 );

Handle a custom bulk action registered via vakanssi/pipeline/bulk_actions. Runs after the bulk-vakanssi-applications nonce check and after the built-in move and delete branches, each of which redirects and exits, so it only sees keys core does not own. Return an array of result args to claim the action (they become query args on the redirect back to the list), or null to pass.

The handler owns its own capability and per-object scope checks: $ids has only been run through absint() and emptied of zeroes, never filtered by the authorization policy.

Fires on the Applications list screen after the built-in bulk-result notices have printed, so a handler that claimed an action via vakanssi/pipeline/bulk_result can read back its own result query arg and print its own notice. Echo already-escaped HTML.

Cross-build seam: whether entering an open stage emails the candidate by itself, so the free Applications screen can warn before a bulk move into it, the way it already warns for won and lost stages. Answered by Email Automation Pro feature, requires a Vakanssi Pro license, which the free screen cannot name.

A reviewer saved a scorecard (Scorecards module). Fires on every save, including one that changed nothing, although only a save that changed something is written to the Activity log.

Since v0.34.0, a scorecard belongs to the interview it came out of, and $interview_id says which. A callback registered for two arguments keeps working unchanged.

// Note which interview round a scorecard came from.
add_action( 'vakanssi/evaluation/saved', function ( int $application_id, int $evaluator_id, int $interview_id ) {
    error_log( sprintf( 'Scorecard by user %d on application %d, interview %d', $evaluator_id, $application_id, $interview_id ) );
}, 10, 3 );

Row ceiling for the applications CSV export. Return 0 or a negative number to export every matching row instead of stopping at the cap. When the export does stop at the cap, the file’s last row is a TRUNCATED marker rather than an ordinary record, so a partial export is never mistaken for a complete one.

Resolve raw client @mention ids to a validated id list before a note is saved. Free returns []; the Collaboration Pro module validates ids against the teammates who may view that application (the whole team, unless assignment scoping is on, in which case admins/HR and the assignee, or the whole team while the application is unassigned).

On an edit, a registered resolver is also called once with the note’s stored ids, so mentions the editor could not see are kept.

A private note was saved. Pro modules listen to notify @mentioned teammates.

A note’s text or @mentions were edited by its author. Fires once per successful save, never on a rejected edit (a stale-copy conflict, a forbidden or empty edit, a failed write). Pro Collaboration listens here to email only $added, so re-saving a note never re-notifies a teammate already on it; webhook deliveries do not forward edits.

An interview was scheduled at a fixed time (free Interviews), or proposed as a set of slots for the candidate to pick from (Scheduling Pro feature, requires a Vakanssi Pro license), after the invites or booking-link email and the audit entry. When the candidate later picks a slot, vakanssi/interview/booked fires instead.

Fires after a scheduled interview’s time is changed, after the new time is persisted and the calendar invite is re-sent.

An interview was canceled. Any interview that had a time (scheduled, or completed) sends attendees a CANCEL calendar update; a proposed one (Scheduling Pro feature, requires a Vakanssi Pro license), which has no calendar entry, emails the candidate that the proposed times are withdrawn.

A scheduled interview was marked completed. No calendar message is sent; this is an internal state change only. Fires once per real transition, after the guarded status update and the audit entry; a request that loses the race to another marking the same interview completed gets a 409 and does not fire it. $interview['status'] is already completed.

A candidate self-booked a proposed slot on the public booking page (Scheduling module), after the calendar invite went out (plus a separate booking notice to the organizer, unless the organizer is also an invited attendee). $interview['status'] is scheduled.

The slots offered for self-service interview booking, applied at the single source of truth both the booking page’s rendered picker and the booking-submission validation read, so a slot the filter removes is neither shown nor bookable via a direct POST. The intended (veto) direction is removal; a callback can also add a slot, which becomes unconditionally bookable since there is no further built-in constraint (no business-hours or capacity check) downstream.

// Hide a slot a staff calendar integration has since marked as busy.
add_filter( 'vakanssi/booking/available_slots', function ( array $slots, array $context ): array {
    $busy = acme_calendar_busy_ranges( $context['organizer_id'] );
    return array_values( array_filter( $slots, fn( $slot ) => ! acme_overlaps( $slot, $busy ) ) );
}, 10, 2 );

The muted “Powered by Vakanssi” credit under the booking card. Off by default: return true to show it. Up to and including v0.37.11 the default was true (credit shown), so a site that relied on that default now shows no credit until it returns true.

An application’s assignee actually changed, through the REST assign endpoint or a bulk assign. Fires exactly once per real assignment, from the request that performed it.

Does not fire when the requested assignee is already the application’s live assignee (a true no-op, including a client retrying its own already-applied request or a bulk assign re-run over an already-assigned batch), and a request that loses a concurrent optimistic-concurrency race to another request assigning to the identical user does not fire it either, since the one real change already did.

How often the Presence heartbeat beats, in seconds. Presence draws the live “who else is viewing this” indicators on the board and in the candidate drawer; it is gated on the collaboration license feature rather than one of its own, so a license that unlocks Collaboration unlocks it too.

The returned value is clamped to 15 to 120 seconds whatever you pass, so a filter cannot make a busy board hammer admin-ajax.php or let an indicator go stale enough to mislead. Raise it on a large team to cut admin requests.

// Beat once a minute instead of every 15 seconds.
add_filter( 'vakanssi/presence/interval', fn () => 60 );

A recruiter manually added a candidate on the Candidates screen’s Add candidate form, after the submitted tags are attached and the audit entry is written. The form refuses an email address that already belongs to a candidate (matched by normalized email identity) and hands the form back instead of merging, so this fires only for a new person. $input is the sanitized submitted fields, including tags.

A sourced candidate was attached to a job as a new application in the entry stage, after the audit entry. Does not trigger vakanssi/application/created: a sourced candidate did not apply, so no applicant confirmation is sent. Attaching is idempotent, so it fires once, from the request that really inserted the application.

Two candidate records were merged from the duplicates screen. Fires once per successful merge, after the transaction has committed and the merge lock is released, so a callback never sees data that could still roll back. $loser_id is already deleted. A merge does not fire vakanssi/candidate/updated.

Extend the Candidates list’s bulk-action dropdown, beyond the built-in Add tag, per-job Add to job entries, and (for users who hold the delete capability) Delete permanently. A registered key needs a matching handler on vakanssi/sourcing/bulk_result. Labels are plain text: Vakanssi escapes them with esc_html() before WordPress prints them, so do not pre-escape them or pass HTML.

// Add a custom "Export to CRM" bulk action to the Candidates list.
add_filter( 'vakanssi/sourcing/bulk_actions', function ( array $actions ): array {
    $actions['acme_export_crm'] = 'Export to CRM';
    return $actions;
} );

add_filter( 'vakanssi/sourcing/bulk_result', function ( $result, string $action, array $ids, int $user ) {
    if ( null !== $result || 'acme_export_crm' !== $action ) {
        return $result; // Not ours to handle.
    }
    // $ids is already filtered through the view_candidate policy.
    return array( 'acme_exported' => count( $ids ) );
}, 10, 4 );

Handle a custom bulk action registered via vakanssi/sourcing/bulk_actions. Return an array of result args, which become query args on the redirect back to the list, or null to pass to the next handler. The list only shows notices for its own keys, so a custom action that wants a notice prints it itself (for example on admin_notices, reading its own query arg).

Unlike the pipeline equivalent, $ids has already been filtered to candidates the current user may read; the handler still owns any further capability check its own action needs.

Fires after a tag is attached to a candidate, from either the application-scoped tag control or the Candidates profile’s bulk-add route. Not fired for an idempotent re-add of a tag the candidate already has (case-insensitive).

Three paths write tags without firing it: the Candidates list’s bulk Add tag action, tags entered on the Add candidate form (read them from $input['tags'] on vakanssi/candidate/sourced instead), and tags folded in during a merge.

Fires after a tag is detached from a candidate, from either surface above. Not fired when the tag was not present in the first place.

Row ceiling for the candidates (talent pool) CSV export. Same contract as vakanssi/export/applications_max_rows above: return 0 or negative for no ceiling, and a capped export ends on a TRUNCATED marker row rather than an ordinary one.

An event’s payload immediately before it is formatted, signed, and delivered. Runs once per delivery attempt to one endpoint: the first send, every automatic retry, a manual Resend, and the endpoint’s Send test (which uses a sample application.created payload).

Retries re-apply the filter to the stored, unfiltered payload, so keep the callback deterministic. It runs before signing, so a webhook endpoint’s signature always covers the exact payload sent. Never includes the endpoint’s signing secret.

The job title, stage, interview title and location, staff names, and note excerpt arrive as plain text, not HTML entities (Director's Assistant, not Director’s Assistant), so escape them yourself before putting them into HTML. The candidate’s name is the exception: it is sent as stored, since it comes from the public application form.

The set of events an endpoint can subscribe to. A key registered here becomes selectable in the endpoint subscription UI and a valid target for vakanssi/webhooks/queue below.

The public way to deliver an instance of a registered custom event: Vakanssi never fires this itself. Call it from your own code, and the Integrations module forwards it to every subscribed endpoint the same way it forwards the plugin’s own built-in domain hooks.

Only an event registered via vakanssi/webhooks/events is forwarded, and only when at least one active endpoint subscribes to it; an unregistered or mistyped key, or a non-array payload, is silently ignored. With Integrations switched off, or on the free plugin, the call still returns normally and nothing is delivered.

// Deliver a custom "candidate.referred" event to any subscribed webhook endpoint.
add_filter( 'vakanssi/webhooks/events', function ( array $events ): array {
    $events['candidate.referred'] = __( 'Candidate referred', 'acme' );
    return $events;
} );

// Later, wherever your own code records a referral:
function acme_record_referral( int $candidate_id ) {
    do_action( 'vakanssi/webhooks/queue', 'candidate.referred', array( 'candidate_id' => $candidate_id ) );
}

The CSV export header row. A column added here must be matched by a value added at the same position via vakanssi/export/row below, or the file’s columns and values drift out of alignment.

// Add a "job_url" column to the applications CSV export.
add_filter( 'vakanssi/export/columns', function ( array $header, string $kind ): array {
    if ( 'applications' === $kind ) {
        $header[] = 'job_url';
    }
    return $header;
}, 10, 2 );

add_filter( 'vakanssi/export/row', function ( array $row, array $item, string $kind ): array {
    if ( 'applications' === $kind ) {
        $row[] = (string) get_permalink( (int) $item['job_id'] );
    }
    return $row;
}, 10, 3 );

One CSV export data row, applied before the existing formula-injection escaping, so an added value is escaped exactly like a built-in one. $item is the row the export selected: for applications, id, created_at, job_title, job_id, stage (the stage name), status, source, has_cv, and rating, plus the candidate’s first_name, last_name, email, and phone.

Since v0.37.15 the applications export’s job_title cell in $row is already plain text, not HTML entities, by the time this filter runs. Since v1.0.0 so are the applications export’s first_name, last_name, stage, and source cells, and the Candidates Pro feature, requires a Vakanssi Pro license export’s first_name, last_name, location, source, and tags cells (Ann < Bo, not Ann < Bo). $item still holds the stored values. See the paired example under vakanssi/export/columns above.

Rows fetched per database round trip by the chunked CSV exports, floored at 1. Peak memory during an export depends on this value, not on how many rows are exported.

A send was attempted and logged. $ok is whether wp_mail() succeeded. $application_id is 0 when not application-bound.

Fires for every send the plugin logs, whoever composed it: templated candidate mail, ad-hoc recruiter messages, Pro automation sends, interview invitations and cancellations, booking links, the organizer’s booking notice, assignment and mention mail to the team, and (premium build) the one-time scoping-lapse alert to the site admin.

The one send it does not cover is the test email (Tools, then Status, and the setup wizard), which is a transport diagnostic and is not logged.

The wrapped HTML email markup, filtered when the branded shell is rendered rather than at send time: on a templated send, vakanssi/email/send_args runs afterwards and can still replace the body. It also runs for the unlogged test email. $context is an empty array for messages rendered without a merge context (interview and booking mail, the test email, the scoping-lapse alert).

Outgoing mail headers (Content-Type, From, Reply-To).

Company name in the email merge context and on the public booking page Pro feature, requires a Vakanssi Pro license. Default in the email merge context: the company name setting, falling back to the site title. On the booking page the default is the site title only, so set the name through this filter if the two should match.

Fired by Email, by Email Automation Pro feature, requires a Vakanssi Pro license, and by Scheduling Pro feature, requires a Vakanssi Pro license, so it keeps firing while any of them is on.

Recruiter notification recipient. Resolved from the per-job override, then the global setting, then admin_email.

// Route engineering applications to the engineering hiring inbox.
add_filter( 'vakanssi/email/notify_address', function ( string $email, int $job_id ): string {
    if ( $job_id && has_term( 'engineering', 'vakanssi_department', $job_id ) ) {
        return 'eng-hiring@example.com';
    }
    return $email;
}, 10, 2 );

Whether the applicant confirmation email is sent on capture. Return false to suppress it. The Add application button on the Applications screen wires this to false for staff-created applications, since the candidate did not apply themselves.

Whether a stage move emails the candidate at all; return false to suppress. It covers every automatic candidate email a move can send: the free reject and offer templates, and the Email Automation Pro feature, requires a Vakanssi Pro license stage rule. The REST move endpoint’s notify=false wires in here, and Screening’s knockout auto-move scopes it to one application.

An explicit suppress here wins even over notify=true. A suppressed automation send does not use up its once-per-stage marker, so a later move into the same stage still sends. Does not affect the move or the audit log.

// Never auto-send rejections; the team sends personal notes instead.
add_filter( 'vakanssi/email/stage_notification', function ( bool $send, int $application_id, string $status ): bool {
    if ( 'rejected' === $status ) {
        return false;
    }
    return $send;
}, 10, 3 );

Cross-build seam: whether to send the reject or offer email even though its template’s automatic-sending setting is off. The REST move endpoint’s notify=true wires in here for one request (the board and drawer’s “Send email & move”). It carries request-scoped operator intent, not a site setting; vakanssi/email/stage_notification is the public send or suppress gate.

Whether a non-template logged email (a label like booking_link or automation rather than a real template key) can be rebuilt and resent. The Activity tab’s Resend button is offered per row based on this, and Pro Scheduling and Email Automation claim it for the rows they can rebuild.

$subject is the only thing that tells one label-only row of an application from another, so a claimant answers for the row, not the label.

The logged subject is now plain text: HTML entities from the merged title (an apostrophe stored as ’) are decoded, and any line break or other control character is folded to a space, before the row is written. A claimant written against the raw, entity-laden subject needs its own comparison updated to match.

Supplies the rebuilt subject and body for a non-template resend claimed via vakanssi/email/resendable. Return null to decline. Runs in the site’s language, and receives the same logged subject for the same reason as vakanssi/email/resendable, decoded the same way.

The third member of the resend seam: who a logged email was addressed to. A module that logs its own label and claims it resendable also says who it addressed. staff keeps a resend going to the address on the logged row, and mixed (a label logged once per recipient) refuses the resend instead of guessing. An unrecognized return falls back to candidate, never to staff.

The recipient, subject, and body immediately before an email is logged (claimed) and sent. Returning a falsy value, or an array whose to is empty or invalid, aborts the send entirely: no claim row is written and wp_mail() is never called, and no vakanssi/email/sent action fires either.

The once-only dedupe identity stays keyed to the original recipient, computed before this filter runs, so a callback that reroutes delivery (a BCC or logging address) does not change what counts as “already sent” for this application and template.

Fires when an email send attempt fails (wp_mail() returned false), after the log row records the failure (and, for a templated send, after its once-only claim is released), so a callback reading the log sees the final state.

Since v0.33.41, how long a deferred email flush may keep sending. Deferred sends run on shutdown, after the response has gone, so a batch killed partway used to leave no trace of the messages it never reached.

The flush now stops when this budget is spent and records the shortfall on each candidate’s activity timeline instead; those messages send the next time they are triggered.

Raise it on a host with a generous request_terminate_timeout and a slow mail provider. 0 or less removes the limit.

The placeholder/merge-tag map before subject/body substitution. One filter name for every templated candidate email, free and Pro: the free Email module’s confirmation/reject/offer/recruiter_notification/custom/resend sends, and the Pro Email Automation stage-triggered custom-template send, both apply it. A custom key added here substitutes in both subject and body wherever a built-in key does.

$template_key is '' on the capture path, where one context is built once for both the applicant confirmation and the recruiter notification, so do not rely on it to tell those two apart.

application_url, candidate_email, candidate_phone, and source are always present in $context by the time this filter runs, even though only some of them carry a value yet. On the free module’s on_created() and resend() paths they arrive empty: this filter fires before recruiter_context() fills them in, so a value your callback sets for any of the four is silently overwritten by that later merge.

Downstream of this filter, EmailTemplates::body() and subject() blank application_url and source for every template except recruiter_notification, regardless of what this filter returns: those two are staff-only merge tags, and a candidate-facing template (or a one-off message) always renders them empty. candidate_email and candidate_phone carry no such restriction.

// Add a custom {careers_url} merge tag to every templated email.
add_filter( 'vakanssi/email/placeholders', function ( array $context, int $application_id, string $template_key ): array {
    $context['careers_url'] = (string) get_post_type_archive_link( 'vakanssi_job' );
    return $context;
}, 10, 3 );

The audit row before insert: entity_type, entity_id, user_id, action, changes (JSON or null), ip_address. Redact or enrich.

Whether the stored client IP is anonymized with wp_privacy_anonymize_ip(). Not consulted when no client IP could be resolved.

The client IP about to be stored, already anonymized unless vakanssi/audit/anonymize_ip returned false. Return '' to store no IP.

Applications processed per call of the WordPress “Erase Personal Data” eraser callback, floored at 1. Each delete cascades CV bytes, file rows, meta, notes, evaluations, and email logs, so a smaller batch trades more calls for never timing out on a candidate with many applications.

Whether the subject’s retained CV files are enclosed in their “Export Personal Data” archive, in addition to being named in the exported rows. Returning false leaves the export naming each CV without enclosing it, which is very likely an incomplete GDPR Article 15 response, so only turn it off on your own legal advice.

Applications the WordPress “Export Personal Data” exporter callback returns per page, floored at 1.

Fires once, on the final erase() call whose result reports done true for a right-to-erasure request. Not fired when the request’s email matched no candidate.

Whether an expired application is purged (anonymized) this run, checked after the built-in due-date check already selected the row. VETO-ONLY: return false to hold a row back (a legal hold, for instance); it can never make a not-yet-due application purge early. A vetoed row still counts as processed for this run’s batch/chain progression, but its retention_until deadline is left untouched, so it is reconsidered on the next run.

// Hold back applications listed under an active legal matter.
add_filter( 'vakanssi/retention/should_delete', function ( bool $should_delete, int $application_id ): bool {
    $held = array_map( 'intval', (array) get_option( 'acme_legal_hold_application_ids', array() ) );
    if ( in_array( $application_id, $held, true ) ) {
        return false;
    }
    return $should_delete;
}, 10, 2 );

Fires after an expired application’s retention purge (anonymization) completes. The row’s PII fields are already scrubbed by the time this fires; use $context rather than re-reading the row.

Applications anonymized per retention purge run, floored at 1. A full batch chains another run a minute later, so a backlog drains in one chain rather than one batch a day.

Ceiling on chained catch-up purge runs after the daily one. 0 stops chaining.

Daily anonymization of candidate data past its retention deadline. Scheduled on activation, self-heals on init, cleared on deactivation. While a backlog remains, each full batch schedules a single follow-up event a minute later, passing the chain count ($chain, an int) as its one argument.

Daily sweep that finds jobs whose closing date has passed, clears their caches, and fires vakanssi/jobs/expired for each, once per job until the job is saved again (saving clears the marker). Self-heals on init, cleared on deactivation. A full batch (see vakanssi/jobs/expiry_batch_size) chains a single follow-up event a minute later.

Daily trim of the webhook delivery log (Integrations module). Self-heals on init, cleared on deactivation.

Retry scan for failed webhook deliveries, every five minutes on the plugin’s own cron interval (Integrations module). Self-heals on init, cleared on deactivation.

Swap the license backend. The provider passed in is the one the build resolved: the unlock-all provider when VAKANSSI_UNLOCK_ALL is on, the Freemius provider when a Freemius SDK instance is loaded, otherwise the default provider that keeps Pro features off. A return that does not implement LicenseProvider is discarded and that default provider is used.

Override a feature-gate decision. Only the Freemius provider fires it, so it runs only while a Freemius SDK instance is loaded and VAKANSSI_UNLOCK_ALL is off; a replacement provider from vakanssi/license/provider fires it only if it calls it itself. Feature slugs: analytics, antispam, collaboration, email_automation, integrations, scheduling, scorecards, screening, sourcing.

Supply a Freemius SDK instance when no vakanssi_fs() function exists. A non-object return is ignored.

The Freemius SDK finished loading. The one underscore-form hook, named to the Freemius SDK’s own convention rather than vakanssi/{area}/{name}.

The “Performance” and “Sources & jobs” dashboard bands, answered by the Analytics module Pro feature, requires a Vakanssi Pro license.

The “Where candidates drop off” dashboard band (drop-off funnel and time in stage), answered by the Analytics module Pro feature, requires a Vakanssi Pro license.

The dashboard’s Export CSV link, shown next to the date range control to users who may export data. Answered by the Analytics module Pro feature, requires a Vakanssi Pro license; an empty value renders no button.

The ranked pages the setup wizard suggests connecting as the careers page, in the wizard’s ranking order.

The date format for Vakanssi’s human-facing dates. Default: the WordPress date_format option.

The date-and-time format for Vakanssi’s human-facing timestamps. Default: the filtered vakanssi/date_format value and the WordPress time_format option, joined with a middle dot.

The public docs URL Vakanssi links to: the Documentation item in the Hiring menu, the Learn more link on Settings and Tools cards, Site Health, the REST-blocked admin notice, and more. Default: https://docs.vakanssi.com/{$path}/, mirroring this site’s own URL structure.

The filter runs before the #$anchor fragment is appended, so a callback that rewrites $url cannot land its change inside the fragment. Since v0.31.0; before that it received ( $url, $slug ) and always built a /guide/{slug}/ URL.

Applications processed per pass when backfilling historical stage events: one chunk right after a schema migration, then one chunk per admin request until the backfill is done. A value below 1 falls back to the default of 200.

Premium build only: the backfill class lives in the Analytics Pro feature, requires a Vakanssi Pro license module’s folder, but it runs whether or not Analytics is licensed or switched on.

Test-only, premium build only (the free build strips the call): the logical names of the tables only the premium build creates. Lets a test simulate the free build’s empty list against the full source.

Test-only: whether a plugin table is considered present. Lets a test simulate a paid table being physically absent, as on a fresh free install, which the WordPress test database cannot reproduce.

Test-only: whether the InnoDB storage engine is available, so a test can simulate a host without it.

Test-only: whether a transaction is reported as genuinely backed by the storage engine, so a test can simulate an engine that gives no real rollback.

Test-only: points one table’s DELETE FROM in the Data Reset tool somewhere else, so a test can exercise the rollback path against a real database error. The value is bound as an identifier, never concatenated into the SQL.

Add panels (tabs) to the application drawer. Return the panels array with your entries appended. An entry is either a titled descriptor, { id, title, node, count } (count is optional and draws the same badge the Activity tab uses), or a bare React element, which gets a “Details” title.

Since v0.34.4, a panel that holds unsaved work must report it through helpers.setDirty( id, dirty ), or closing the drawer or stepping to the next candidate discards it without asking.

// Add a "Quick links" tab to the application drawer.
wp.hooks.addFilter(
    'vakanssi.pipeline.drawer_panels',
    'acme/quick-links',
    function ( panels, data, helpers ) {
        var el = wp.element.createElement;
        var email = ( data.application && data.application.email ) || '';
        return panels.concat( [ {
            id: 'acme-quick-links',
            title: 'Quick links',
            node: el( 'p', null,
                el( 'a', { href: 'mailto:' + email }, 'Email this candidate' )
            ),
        } ] );
    }
);

Add person-level sections to the drawer’s Details tab. The tab renders only when at least one section is present. Return the sections array with your { id, node } descriptor(s) appended.

Add controls to the drawer header row, ahead of Edit details, Print / PDF, and Delete. For compact application-state controls that should stay visible whichever tab is open, not deep content. Return the controls array with your { id, node } descriptor(s) appended; an entry without a node is dropped.

Add compact sections to the drawer’s identity rail, the always-visible candidate card on the left. For small identity metadata only: keep it short, since the rail must not grow a scrollbar. Return the sections array with your { id, node } descriptor(s) appended; an entry without a node is dropped, and returning nothing adds no section at all.

Since v0.33.43, quiet markers on a pipeline board card, beside the built-in Withdrawn one. For application-level flags a recruiter must see while scanning a column, without opening each card; Screening Pro feature, requires a Vakanssi Pro license uses it for its knockout flag. Keep markers to a word or two. An entry without a node is dropped.

app is whatever vakanssi/rest/applications_payload left on the row, so add your field there and render it here. label is optional plain text appended to the card’s accessible name, and it is not decoration: the card’s own aria-label replaces its inner text for assistive technology, so a marker without a label is silent to a screen reader.

// Flag referral applications on the board card.
wp.hooks.addFilter( 'vakanssi.pipeline.card_markers', 'acme/referral', function ( markers, app ) {
    if ( 'referral' !== app.source ) {
        return markers;
    }
    return markers.concat( [ {
        id: 'acme-referral',
        node: wp.element.createElement( 'span', { className: 'acme-referral' }, 'Referral' ),
        label: 'Referral',
    } ] );
} );

Fired whenever the reader moves: by the Board when [jobId, drawer] changes, and by the list view’s drawer host when [jobId, openItem] changes. An action, not a filter, so the return value is ignored.

screen names the surface, job is the current job filter (0 for all), and open is the application whose drawer is open (0 for none). Pro Presence subscribes to it to feed the next heartbeat, which is how the live “who’s viewing” indicators know where everyone is.

Premium build only: the free build strips both calls, so a listener there is never called. On the premium build it fires whether or not Presence is active, and Presence is the only built-in listener.

wp.hooks.addAction( 'vakanssi.pipeline.state', 'acme/track-view', function ( state ) {
    if ( state.open ) {
        console.log( 'Now reading application', state.open, 'on job', state.job );
    }
} );

Fired on every WordPress Heartbeat tick that carries a Vakanssi presence payload, which is how the board and list learn who else is looking at what. pipeline.js consumes it to patch the board in place and drive the presence chips.

Dormant on the free plugin, which does not include Presence, so the script that fires it does not exist there. On the Pro build Presence shares Collaboration’s license feature. See vakanssi/presence/interval above for the beat rate.

Relayed one for one from WordPress core’s own heartbeat.connection-lost and heartbeat.connection-restored events, under a single namespaced action, so a subscriber only has to know Vakanssi’s event names rather than core’s.

Vakanssi uses it to dim the presence chips while the connection is down, marking them stale instead of leaving a stale roster looking live.