Developers

Apply Handoff API

Prefill your own application form from an AvPosts candidate profile. Version 1.

What it does

When a signed-in AvPosts candidate clicks Apply on one of your postings, AvPosts hands their profile to your apply page so the form is already filled in when they land. The candidate opts in on every click, the handoff is a single-use token that lives ten minutes, and your page redeems it with one GET. You keep your own form, your own ATS and your own domain; AvPosts only shortens the typing.

How it works

1. A signed-in candidate with a profile sees Send my AvPosts profile with this application next to Apply, checked by default. Unchecking it makes Apply a plain link.
2. On click, AvPosts mints a random 32-byte token, stores only its SHA-256 plus a frozen JSON snapshot of the profile, and redirects to your apply URL with ?avposts_handoff=<token> appended, alongside the usual utm_* parameters.
3. Your page — via the drop-in script or your own code — calls GET https://avposts.io/api/v1/handoff/<token>. The first call returns the snapshot; every later call returns 410.
4. You fill your form from the response and drop the token from the URL. The candidate reviews, edits, attaches their résumé and submits to you as usual.

Option A — drop-in script

One tag, anywhere on the apply page. It reads the token, redeems it, fills any input, select or textarea whose name is one of the canonical keys — firstName, lastName, email, phone, city, province, linkedinUrl, workAuth, yearsExperience, totalHours, picHours, multiHours, turbopropHours, medical — dispatches input and change events so React and Vue controlled fields pick the values up, then strips the token from the address bar. No dependencies, plain ES2017, about 4 KB.

<script src="https://avposts.io/apply.js"></script>

Fields with other names take a data-avposts attribute naming a dotted path into the payload:

<!-- Matched by name: nothing to add -->
<input name="firstName">
<input name="lastName">
<input name="email">
<input name="phone">
<input name="linkedinUrl">

<!-- Any other field: point it at a path in the payload -->
<input name="tt"   data-avposts="applicant.hours.total">
<input name="pic"  data-avposts="applicant.hours.pic">
<select name="med" data-avposts="applicant.medical">…</select>

Forms that hold their state in JavaScript can ignore the DOM filling and listen for the avposts:handoff event instead — the full payload is in event.detail. The same payload is available as window.AvPosts.handoff, a promise that resolves to the payload or null.

useEffect(() => {
  function onHandoff(e) {
    const a = e.detail.applicant;
    setForm((f) => ({
      ...f,
      firstName: a.firstName ?? f.firstName,
      lastName: a.lastName ?? f.lastName,
      email: a.email,
      phone: a.phone ?? f.phone,
      totalHours: a.hours.total ?? f.totalHours,
      licences: a.licences.join(", "),
    }));
  }
  window.addEventListener("avposts:handoff", onHandoff);
  return () => window.removeEventListener("avposts:handoff", onHandoff);
}, []);

// Or await it directly:
// const payload = await window.AvPosts.handoff; // null when there is no handoff

Option B — call the API yourself

Read avposts_handoff from the query string and GET the endpoint from the browser or your server. No API key: the token is the credential. CORS is open (Access-Control-Allow-Origin: *) and every response is Cache-Control: no-store.

curl -s https://avposts.io/api/v1/handoff/${token} \
  -H "Origin: https://greatnorthairlines.com"

{
  "schema": "avposts.handoff/1",
  "jobId": 1042,
  "applicant": {
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane.doe@example.com",
    "phone": "+1 403 555 0100",
    "city": "Calgary",
    "province": "AB",
    "linkedinUrl": "https://linkedin.com/in/janedoe",
    "workAuth": "Canadian citizen",
    "languages": ["en", "fr"],
    "yearsExperience": 9,
    "willRelocate": true,
    "licences": ["ATPL"],
    "medical": "Cat 1",
    "hours": { "total": 3200, "pic": 1200, "multi": 900, "turboprop": 400 },
    "types": [{ "family": "CRJ", "kind": "rating" }],
    "roles": ["pilot"]
  },
  "issuedAt": "2026-08-31T14:02:11.412Z",
  "expiresAt": "2026-08-31T14:12:11.412Z"
}

Field reference

Every key is always present. A fact the candidate has not entered is null (or an empty array for lists) — never missing, never undefined.

Errors

Treat every non-200 as “no handoff” and show the empty form. The drop-in script does exactly that, silently.

Privacy & security

• The candidate opts in per click. Nothing is sent unless the checkbox next to Apply is on, and the choice is theirs every time.
• Ten minutes, single use. A token is valid for ten minutes from the click and is dead after its first redemption. AvPosts stores only its hash.
• A snapshot, not a live link. The payload is frozen at click time. It gives no access to the AvPosts account and cannot be used to fetch anything else.
• Do not store the token. Redeem it, use the payload, and drop it from your URL and your logs. Keep the applicant data under your own privacy policy, exactly as if they had typed it.
• No résumé in v1. The handoff carries structured profile fields only. Files stay with your own upload.
• No user ids. The payload contains what an application form asks for and nothing internal to AvPosts.

Attribution

The handoff rides alongside the existing attribution parameters, which are unchanged: utm_source=avposts, utm_medium=job_board and utm_campaign=<jobId> are appended to every off-site apply URL that does not already carry a utm_source. A visit with a token is always also a visit with utm parameters; the reverse is not true.

Changelog

• 2026-08-31 — v1. Schema avposts.handoff/1, drop-in apply.js, single-use ten-minute tokens.

Looking for the careers-page widget instead? Embed your live openings →