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>

Step 2: Get a sharing link’s idForEmbedded

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",
        "connectUrl": "https://vouch.careers/companies/ref_careers456/forms/connect"
      }
    ]
  }
}

• 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. Each entry also carries a connectUrl — a direct link to the company’s connect-with-company form, separate from any specific position (see below).

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:

• Pre-built links — jobUrl (the public position page), applyUrl (goes straight to the application form), vouchUrl (goes straight to the referral form). Career-page entries also carry connectUrl (goes straight to the connect-with-company form — company-level, not position-specific). 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.

The connect-with-company form

The connectUrl on each careerPagesLinks entry (and on career page objects from GET /career-pages) points to a standalone form where candidates can express interest in the company for future roles — independent of any specific position. You can link to it directly from your careers page or embed it in an iframe the same way as the apply/vouch forms:

<a href="{connectUrl}">Connect with us for future roles</a>

Or as an iframe:

<iframe
  src="{connectUrl}"
  style="width: 100%; height: 100%; border: none"
></iframe>

The connectUrl is also available at the career page level from GET /career-pages and GET /career-pages/{id}/positions/{positionId}, so you don’t need to go through a position to get it.

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.