> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.vouch.careers/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.vouch.careers/_mcp/server.

# 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.

```html
<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:

```json
{
  "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:

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

Or as an iframe:

```html
<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.

```html
<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.

```html
<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`.

```js
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}`:

```html
<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.