Embedded Widget

Getting Started

The Vouch embedded widget lets you drop a working apply/refer flow for a position straight into your own site — a careers page, a job board, an ad landing page, whatever you’re building. One script tag, then either an iframe or a couple of data attributes, and you have a fully functional application form without building one yourself.

This guide covers getting the values you need from the public API, embedding the widget, and (optionally) listening for what happens inside it.

Step 1: Add the script tag

Add this once per site, ideally in <head>. If you’re embedding widgets for more than one position or sharing link on the same site, you still only need this once.

<script src="https://vouch.careers/embeded.js" async></script>

Everything below is built from one value: a sharing link’s idForEmbedded. Fetch it from GET /positions/{id} — there are two arrays to look in:

{
  "data": {
    "sharingLinks": [
      {
        "id": "ref_xyz789",
        "idForEmbedded": "ref_xyz789",
        "type": "NETWORK",
        "platform": "WEBSITE",
        "name": "Careers page embed",
        "jobUrl": "https://vouch.careers/jobs/ref_xyz789",
        "applyUrl": "https://vouch.careers/jobs/ref_xyz789/forms/application",
        "vouchUrl": "https://vouch.careers/jobs/ref_xyz789/forms/vouch"
      }
    ],
    "careerPagesLinks": [
      {
        "id": "ref_careers456",
        "idForEmbedded": "ref_careers456.pos_123",
        "name": "Acme careers page",
        "forAgency": true,
        "forClient": false,
        "isDefault": true,
        "jobUrl": "https://vouch.careers/companies/ref_careers456/pos_123",
        "applyUrl": "https://vouch.careers/companies/ref_careers456/pos_123/forms/application",
        "vouchUrl": "https://vouch.careers/companies/ref_careers456/pos_123/forms/vouch"
      }
    ]
  }
}
  • sharingLinks — direct channels only (job board posts, ads, referral networks). Only active ones are returned — if a position has none yet, one needs to be created for it in the business portal first (Position → Channels). type/platform tell you what kind it is — platform: 'WEBSITE' is the one created specifically for embedding. (The Vouch marketplace shows up under careerPagesLinks, flagged isMarketplace.)
  • careerPagesLinks — entries on a company careers page. forAgency/forClient tell you whether it’s the agency’s own overarching careers page or a specific client’s; isDefault marks the default one. These use a different URL shape (/companies/<id>/<positionId>/...) than direct sharing links (/jobs/<id>/...), since a careers page isn’t scoped to one position on its own — you don’t need to worry about this, the pre-built links already account for it.

If you’re embedding from a careers page’s point of view instead, GET /career-pages/{id}/positions/{positionId} returns the same position with that page’s idForEmbedded already flattened in (and to embed a whole careers page rather than one position, use a page’s id from GET /career-pages directly).

A position can have several entries in each array — pick the one that matches your integration (e.g. filter sharingLinks by platform === 'WEBSITE', or by name if you’ve labeled it).

Each entry gives you two things, regardless of which array it’s in:

  • Three pre-built links — jobUrl (the public position page), applyUrl (goes straight to the application form), vouchUrl (goes straight to the referral form). Use these directly if you just want to link out, no embedding required.
  • idForEmbedded — the one value the embedded widget needs. Everything in the rest of this guide uses it. For a sharingLinks entry it’s the same as id; for a careerPagesLinks entry it’s different (id.<positionId>, since a careers page isn’t scoped to one position) — always use idForEmbedded here, never the bare id.

Step 3: Choose an embed method

Option A — iframe (recommended)

Simplest to set up, keeps Vouch’s styling, and every button works out of the box.

<iframe
  src="https://vouch.careers/embeded/{idForEmbedded}/widget?variant=simple"
  data-vouch-embeded="{idForEmbedded}"
  style="width: 100%; height: 100%; border: none"
></iframe>

Replace {idForEmbedded} with the value from Step 2. variant is simple or compact, depending on how much space you have.

Option B — data-attribute triggers (fully customizable)

If you want full control over styling and layout, add these attributes to your own buttons or links instead — no iframe at all.

<button data-vouch-open-apply="{idForEmbedded}" data-vouch-host-base="https://vouch.careers">
  Apply
</button>
<a href="#" data-vouch-open-refer="{idForEmbedded}" data-vouch-host-base="https://vouch.careers">
  Refer someone
</a>

Trade-off: with this method, page views aren’t tracked (the iframe method tracks impressions; a bare trigger attribute doesn’t).

Step 4 (optional): Listen for widget events

The widget posts events to the parent window via postMessage — useful for analytics, funnels, or your own custom automation. Always verify event.origin so you only process messages from Vouch.

Event types: apply.clicked, refer.clicked, apply.submitted, refer.submitted. Submitted events carry firstName, lastName, email, linkedInUrl, resumeUrl, portfolioUrl, and phone in detail.

const allowedOrigins = new Set(['https://vouch.careers', window.location.origin]);
window.addEventListener('message', (event) => {
  if (!allowedOrigins.has(event.origin)) return;
  if (
    typeof event.data !== 'object' ||
    !event.data ||
    !('type' in event.data) ||
    event.data.type !== 'vouch-event'
  ) {
    return;
  }
  const eventType = event.data.detail?.type;
  const details = event.data.detail;
  switch (eventType) {
    case 'apply.clicked':
      console.log('User opened apply form');
      break;
    case 'apply.submitted':
      console.log('User submitted apply form', {
        firstName: details?.firstName,
        lastName: details?.lastName,
        email: details?.email,
      });
      break;
    // ...refer.clicked / refer.submitted follow the same shape
  }
});

Full example

Putting it together — script tag, iframe, and an event listener, for a sharing link whose idForEmbedded you fetched from GET /positions/{id}:

<head>
  <script src="https://vouch.careers/embeded.js" async></script>
</head>
<body>
  <iframe
    src="https://vouch.careers/embeded/ref_xyz789/widget?variant=simple"
    data-vouch-embeded="ref_xyz789"
    style="width: 100%; height: 600px; border: none"
  ></iframe>
  <script>
    window.addEventListener('message', (event) => {
      if (event.origin !== 'https://vouch.careers') return;
      if (event.data?.type !== 'vouch-event') return;
      console.log('Vouch widget event:', event.data.detail);
    });
  </script>
</body>

That’s it — no separate widget configuration, no manual copy-paste from the business portal required. The sharing link data from the API is the single source of truth for every link and embed you need.