# Poily Docs

> Integration docs for developers and AI agents connecting a product to Poily — people sync, forms, blog/content, and email consent. Every page has a raw Markdown twin at the same path plus .md.

<!-- https://docs.poily.com/connect · source: Apps/handoffs/admin_mkt/CONNECT_YOUR_PRODUCT.md · last synced: 2026-11-02 -->
# Connect your product to Poily

*Written for the developer — or AI agent — of a product joining a Poily portfolio. Everything here is self-serve: no Poily-side engineering is involved in connecting you.*

Poily runs your portfolio's marketing, CRM, email, and entitlements across products. Your product keeps its own stack and stays the system of record for its own data; each **connection point** below is one seam where your product and Poily exchange something. Connect only the ones you need, in any order.

**Base API:** `https://ju1sxvytc1.execute-api.us-east-1.amazonaws.com/dev`
**Console:** `https://app.poily.com` (your operator works here; API keys are issued here)

---

## 1. People — push your members (live)

Send Poily the members you choose to share. They appear in the portfolio's User Manager and CRM Contacts, with **`existing_relationship`** consent (an account is a relationship — Poily may send them transactional mail; marketing mail still requires an opt-in, see §4).

**Get a key:** your operator issues one in Console → Settings → Connections (value shown once).

> ⚠️ **The key is server-side only.** Store it as a server secret and send it only from backend code. Never put it in a client bundle or a browser-exposed env var (`VITE_*`, `NEXT_PUBLIC_*`, `REACT_APP_*`) — `/u/identify` authenticates by key alone and ignores Origin, so a key shipped to the browser is a full identity-feed credential for anyone who views source. If a key leaks, revoke it in the same Connections tab and issue a new one.

**On signup — and once as a backfill — POST your users.** Single and batch are the same call; it upserts on `external_id`, so repeats are always safe:

```
POST /u/identify
Authorization: Bearer <your key>
Content-Type: application/json

{
  "users": [
    {
      "external_id": "u_123",            // required — your stable user id
      "email": "ada@example.com",
      "name": "Ada Lovelace",
      "created_at": "2026-10-31T12:00:00Z",
      "last_active_at": "2026-11-01T09:30:00Z", // optional — when THIS USER last did something in your product
      "plan": "pro",                      // optional — whatever you call it
      "status": "active",                 // optional
      "attributes": { "role": "editor" }  // optional free-form JSON
    }
  ]
}
```

Response: `200 {"accepted": 1, "rejected": []}` · max 1000 users per call (loop for bigger backfills) · `401` means the key is wrong or revoked. Update a user (plan change, rename) by sending them again.

**`last_active_at` drives the Active / Dormant split** on the Poily dashboard (Active = within 30 days) and dormancy-based lifecycle automation. Rules:
- Send the user's **real last activity in your product** — a session, a meaningful action, whatever you consider "active". Never send "now" as a default: a backfill that stamps everyone `now` reads as a fully active user base and makes dormancy targeting meaningless.
- **Omit it when you don't know** — omitting never clears a previously sent value, and users without one show as "Unknown activity" (which is honest), not as dormant.
- Include it in your nightly re-push so it stays fresh; it's also fine to send it alone with just `external_id` as a lightweight activity ping.

**`attributes` powers segmentation.** Whatever you put there becomes targetable in Poily's campaign segments (e.g. `minutes_watched_30d ≥ 120 AND has_shared = false AND email_news = true`). Conventions:
- **Flat keys, JSON types preserved** — send booleans as booleans and numbers as numbers (`"true"` ≠ `true`; a type change silently shrinks any segment filtering on it).
- **Send computed aggregates, not raw events** — `minutes_watched_30d: 240` beats a stream of watch events; you own the computation, Poily owns the targeting.
- **Keep them fresh** — a nightly re-push plus an immediate push when something consequential flips (a preference toggle, a plan change) is the right cadence. Segments are re-evaluated at every send, so freshness of the data is the only staleness that exists.
- **Preference flags** (like `email_news`) are enforced by **targeting**: campaigns for that content segment on the flag, so flipping it off removes the member at the next send. Unsubscribe/suppression (§4) is the harder, transport-enforced layer underneath.

### Where to wire it, by stack

The call itself is identical everywhere — an HTTPS POST with a Bearer header. Only the secret's home and the trigger differ:

- **Supabase:** store the key in Edge Functions → Secrets (e.g. `POILY_API_KEY`). Trigger an Edge Function from an auth webhook or a database trigger/webhook on your users table; read the secret with `Deno.env.get("POILY_API_KEY")`. Backfill = a one-off script or scheduled function paging through your users.
- **Vercel / Netlify:** store the key as an environment variable **without** a public prefix. Call from a server route, API route, or background/scheduled function — never from component code (even server components leak into client bundles if you pass the key down).
- **AWS:** key in SSM Parameter Store or Secrets Manager; call from the Lambda (or container) that handles your signup path. A scheduled Lambda (EventBridge) works for the periodic re-sync variant.
- **Traditional backend (Rails, Django, Express, Laravel, …):** key in your usual server env/secret store; call from your signup handler or an after-create hook, plus a management command/cron for the backfill.
- **No backend at all** (static site + third-party auth): don't call from the browser. Use your auth provider's webhooks (Auth0, Clerk, Firebase Functions, Supabase as above) as the server-side trigger instead.

In every case: fire-and-forget with a short timeout and a retry or queue — your signup flow should never block or fail because Poily was briefly unreachable, and the upsert semantics make redelivery safe.

**Alternatives** (for teams that prefer not to push): hosted-store read (you hand Poily read credentials in the console) and an API contract Poily pulls from — both planned; ask your operator.

## 2. Forms — capture signups on your site (live)

Four ways, pick one:
- **Hosted page:** `https://forms.poily.com/f/<slug>` — link to it, zero code.
- **Scan-to-create (recommended):** build your own `<form>`, tag it, include the SDK — Poily creates the form from your markup and captures submissions. No endpoint wiring:
  ```html
  <form data-poily-import="newsletter">
    <input type="email" name="email" required />
    <button type="submit">Subscribe</button>
  </form>
  <script src="https://forms.poily.com/sdk.js" async></script>
  ```
  Your domain must be registered in your brand kit (`custom_domain`) — origin is how Poily knows the form is yours.
- **Embed:** `<div data-poily-form data-slug="<slug>" data-mode="inline"></div>` + the `embed/forms.js` script, or a plain iframe.
- **Direct REST:** `POST /f/<slug>/submit` (JSON → `{id}`; form-encoded → 303). Reserved keys: `_attribution`, `_placement`, `_gotcha` (honeypot — any non-empty value silently drops the submission), `_started_at` (epoch ms, first interaction → completion time).

Form submissions create leads with **`form_optin`** consent — immediately mailable for marketing.

## 3. Blog / content — two ways to serve it (live)

Pick ONE per site and tell your operator which, so nothing shadows anything:

- **3a. Proxy (zero build work):** Poily renders complete pages; you add one rewrite rule. Presentation is Poily's.
- **3b. Headless (your presentation):** your app queries Poily's public content API and renders the blog itself. This is how poily.com's own site works.

### 3a. Proxy — serve Poily-rendered pages under your domain

Poily publishes your blog to a CDN origin keyed by your registered domain. You proxy `/blog` to it — on Netlify:

```toml
[[redirects]]
  from = "/blog"
  to = "https://d1kjbg4330oa4p.cloudfront.net/<your-domain>"
  status = 200
  force = true

[[redirects]]
  from = "/blog/*"
  to = "https://d1kjbg4330oa4p.cloudfront.net/<your-domain>/:splat"
  status = 200
  force = true
```

RSS at `/blog/rss.xml`, sitemap alongside. Any host that can proxy (Vercel, nginx, Cloudflare) works the same way. The same proxy trick serves `forms.<your-domain>` if you want form links on your own hostname: proxy `/*` to `https://forms.poily.com/:splat`.

URL shapes are handled origin-side (no index rewrites needed on your end): `/blog` and `/blog/` → index; `/blog/<slug>` (extensionless, **no trailing slash**) → article; `rss.xml` / `sitemap.xml` / `tag/<tag>` served directly. Do not link articles with a trailing slash.

### 3b. Headless — Poily as your content API

Public GraphQL (JSON over POST, no auth) at `POST <base>/graphql`:

```graphql
# Listing (metadata only — no body):
query { getPublicPosts(tenantId: "<your-tenant-slug>", limit: 100) {
  slug title excerpt subtitle coverImageUrl publishedAt updatedAt
  readingTimeMin wordCount tags authorName authorBio
  metaTitle metaDescription ogTitle ogDescription ogImage canonicalUrl
} }

# One post by slug (adds the rendered body):
query { getPublicPost(tenantId: "<your-tenant-slug>", slug: "<slug>") {
  ...sameFieldsAsAbove showToc structuredData bodyHtml content
} }
```

What to know as a consumer:

- **`bodyHtml`** is the rendered article body (headings, embeds, tables, form CTAs with working URLs), wrapped in a `.poily-article` scope with a self-contained `<style>` block whose colors are CSS custom properties (`--poily-accent`, …) you can override. Prefer it over `content` (raw TipTap JSON) unless you're rendering every node type yourself.
- **Table of contents:** headings in `bodyHtml` carry slugified anchor `id`s — build your TOC by extracting `h2`/`h3` (honor the post's `showToc` flag).
- **JSON-LD:** `structuredData` is the per-post override when the author set one; otherwise build the Article JSON-LD from the returned fields (title, excerpt, dates, author, cover) — standard headless practice.
- **Tags:** derive the tag list from the posts you fetched; there is no separate taxonomy endpoint. There is no category concept — tags are the taxonomy. There is no cover-image alt-text field yet; use the post title as alt.
- **Freshness:** unpublished posts drop out of both queries immediately. Cache with ISR/revalidation (poily.com uses `revalidate: 60`).
- **RSS/sitemap:** emit your own from the same listing (you own the presentation), or proxy just `/blog/rss.xml` + `/blog/sitemap.xml` to the 3a origin — its URLs already point at your domain.
- Going headless? Remove any 3a `/blog/*` proxy rule first — a forced rewrite silently shadows your pages.

### 3c. Brand surface — your social accounts and app badges (live)

A post's `postFooter` tells you what the author intended to appear under the article —
`{"tags":true,"share":true,"social":true,"badges":true,…}`. Treat it as **advisory**: you own the
layout, so honour it, ignore it, or apply your own rules. The accounts those flags refer to live on a
separate query, because they belong to your brand rather than to any one post:

```graphql
query { getPublicBrandSurface(tenantId: "<your-tenant-slug>") {
  socialLinks { network url iconUrl }
  appBadges   { store url badgeImageUrl }
} }
```

What to know as a consumer:

- **Ask for it once, not per post.** It is per `(tenant, line)` and changes when your operator edits
  branding, not when a post is published — so cache it separately and for longer than your posts.
- **`network`** is canonical and alias-resolved (`x`, never `twitter`), so you can switch on it.
  `store` is `appStore` or `googlePlay` today. **Treat the store list as open** — it grows as we add
  vendors (the Amazon Appstore and the Roku Channel Store are next, for TV apps). Switch on the values
  you handle and render the rest from `badgeImageUrl` + `url`, rather than assuming exactly two.
  Note that a **TV app usually needs no new store**: tvOS ships in the App Store, and Android TV and
  Google TV ship through Google Play, so both are already covered by the two keys above.
- **The art is offered, not imposed.** `iconUrl` / `badgeImageUrl` are absolute, public URLs for our
  hosted PNGs. If you have your own icon set, use `network` + `url` and ignore them.
- **Pick the variant you need:** `iconStyle` is `colored` (default), `onlight` or `ondark`;
  `badgeTheme` is `onlight` (default) or `ondark` — the theme of the *background you're drawing on*.
  An unrecognised value falls back to the default rather than handing you a broken image URL.
- **Per line:** pass `productLineId` for a line that has its own accounts; omit it for your
  tenant-wide set. A line inherits the tenant's accounts and overrides individual networks.
- **Empty arrays mean nobody has entered any accounts yet** — not an error, and not something this
  query can fix. Your operator adds them under Settings → Branding → Social.
- **Only `http`/`https` URLs are returned**, so a link from this payload is safe to put in an `href`.

This is the same resolution the Poily-rendered page (3a) uses, so a post's footer shows the same
accounts in the same order whichever way you serve it.

## 4. Email & consent — what Poily handles for you (live)

- Poily sends **as your brand** (your From address, your sending domain) once your operator configures the email connection — BYO Mailgun/SES or Poily-managed.
- **Unsubscribe is Poily's job**: every marketing email carries a Poily-hosted unsubscribe link and RFC 8058 one-click headers. You build nothing.
- **Consent is enforced at send time**, not at import: suppressed or no-basis addresses are refused at the transport, whatever list they're on. Pushed members (§1) carry **existing-relationship** basis — an account is a relationship, so they are mailable until they unsubscribe (which Poily enforces at the transport, forever). Form sign-ups (§2) carry the stronger explicit opt-in basis. Lists you merely *imported* are blocked from marketing entirely until a real basis exists.
- **Give members a visible switch.** The clean pattern for ongoing content (tips, digests): a preference toggle in your product, pushed as an attribute (§1) and used as a segment criterion — default-on is acceptable for existing members precisely because unsubscribe stays one click away in every email.

## 5. Coming next

- **Entitlements exchange** — read your users' resolved plan entitlements from Poily (feature keys, limits) and get plan-change webhooks, so Poily's Plan Manager drives your feature gating.
- **Activity feed** (`/u/track`) — push engagement events to power segmentation and lifecycle automation.
- **Outbound webhooks** — Poily calls you on new lead, form submission, plan change.
- **MCP / agent surface** — operate all of the above by prompt.

---

*Questions reach your portfolio operator; this document travels with the console (Settings → Connections).*


---

<!-- https://docs.poily.com/forms · source: Apps/handoffs/admin_mkt/POILY_FORMS_EMBED_PLAYBOOK.md (client-facing cut) · last synced: 2026-11-02 -->
# Poily Forms Integration

*How to put a Poily-connected form on any website: three integration tiers, one data destination. Written for the developer or AI agent building the host site. No API keys, no CORS setup, no backend work on your side.*

## Mental model

**Poily** is the forms/CRM platform behind the product you're integrating with. The product's operator manages forms at `app.poily.com`; each product has a **forms domain** (e.g. `forms.<product>.com`) that serves the loader scripts and the hosted form renderer. Every tier below submits to the same Poily gateway, so submissions land in the same place with the same attribution regardless of how you embed.

```
your page
  └─ loader script from forms.<product>.com
        └─ form (iframe, web component, or your own markup)
              └─ POST → Poily gateway
                    └─ visible to the operator at app.poily.com → Submissions
```

Tenant identity rides on the **form slug** and, for scan-to-create, on your page's **origin** — never on the attribute names. The `poily-*` attribute names, the `window.__poilyOpenForm` global, and the event names are the same for every product. **Do not rename the `poily-` prefix** to match the product.

> **⚠️ The #1 trap: a success toast is not proof.**
> A legacy pre-Poily backend can return 200 and a success message while writing to the wrong database. Always verify in DevTools → Network that the submit POST hits the Poily gateway host (it contains `ju1sxvytc1`), then confirm the row in `app.poily.com → Submissions`. The gateway's `/dev` stage is correct and expected — don't go hunting for a "prod" URL.

## Choosing a tier

Two decisions, not one: *who renders the form* (Poily-hosted vs your own markup) and *what shape* (traditional all-at-once vs conversational one-question-at-a-time; conversational exists only on Poily-hosted forms). The data lands identically either way — optimize for ownership and design, not plumbing.

| Tier | Design control | Who edits fields | Effort | Best for |
|---|---|---|---|---|
| **1 · iframe embed** | Low (Poily's look) | Operator — no deploy | Lowest | Fastest launch; non-dev owns the form; one form on many sites |
| **2 · `<poily-form>`** | Medium (your CSS) | Operator | Low–med | Operator-owned fields with a closer visual fit |
| **3 · SDK / native form** | Full (your markup) | Code — deploy | Medium | Bespoke branded forms; custom UX; short stable field sets |

- **Branded waitlist or signup with few, stable fields** → native SDK (tier 3), traditional shape.
- **A non-technical owner edits the form, or it's reused across properties** → iframe (tier 1).
- **Operator-owned fields but a tighter visual fit** → `<poily-form>` (tier 2).
- **Long, qualifying, branching intake** → conversational shape, Poily-hosted (tier 1 or 2).
- **You already have a finished native form** → scan-to-create ([below](#scan-to-create-data-poily-import)) — Poily builds its side from your markup.

## 1 · iframe embed (fastest)

Get the canonical snippet from the operator (it comes from the form's **Distribution** tab in Poily and is copy-paste correct for the tenant). The whole integration is:

```html
<div data-poily-form data-slug="<slug>" data-mode="inline" data-placement="home_inline"></div>
<script src="https://forms.<product>.com/embed/forms.js" async></script>
```

Open a popup or slider from any button:

```html
<button onclick="window.__poilyOpenForm('<slug>', 'popup', undefined, 'dark', 'home_nav')">
  Get started
</button>
```

UTM/click-id/referrer capture, attribution, auto-resize, and theming are automatic — don't build your own lead-capture path. Multiple forms per page are supported.

### Attribute reference (`<div data-poily-form …>`)

| Attribute | Required | Default | Notes |
|---|---|---|---|
| `data-slug` | yes | — | form slug from the Distribution tab |
| `data-mode` | — | `inline` | `inline` \| `popup` \| `slider` \| `sidetab` |
| `data-placement` | — | — | per-CTA attribution tag — give each CTA its own |
| `data-label` | — | "Open Form" | button/tab text for popup, slider, sidetab |
| `data-color` | — | `#7c3aed` | trigger-button accent (hex) |
| `data-theme` | — | auto | `light` \| `dark`; auto follows the page — usually leave unset |
| `data-width` | — | `100%` | inline iframe width |
| `data-height` | — | `300px` | initial height only — the iframe auto-resizes after first paint |

### SPA / React notes

- The inline iframe injects into your `<div>` on page load — keep that div a plain, stable, empty element the framework never unmounts. (Popups attach to `document.body` and are immune.)
- Put the forms origin in an env var with no trailing slash; remember build-time env vars need a redeploy to change.
- `__poilyOpenForm` opens popup/slider only; `inline`/`sidetab` are container modes.

### Conversion tracking

```js
window.addEventListener('poily:form-submitted', (e) => {
  // e.detail = { type: 'poily-form-submitted', formTemplateId }
  // e.g. gtag('event','generate_lead') / fbq('track','Lead')
})
```

If your site runs a strict CSP, allow `forms.<product>.com` in `script-src` (loader) and `frame-src` (iframe). CORS keys off the iframe's own origin, so no allow-listing is needed on Poily's side for any host page.

## 2 · `<poily-form>` web component (your CSS)

Renders the Poily-defined form in your page's DOM — Poily owns schema, validation, submission, and attribution; you own the styling. One tag, no iframe, no React dependency:

```html
<script src="https://forms.<product>.com/poily-form.js" async></script>
<poily-form slug="<slug>" placement="home_hero"></poily-form>
```

Style from your own stylesheet — custom properties and parts pierce the shadow boundary:

```css
poily-form {
  --poily-font: 'Fraunces', serif;
  --poily-accent: #1a2b4a;
  --poily-field-radius: 8px;
  --poily-gap: 18px;
}
poily-form::part(button) { text-transform: uppercase; letter-spacing: .04em; }
poily-form::part(label)  { font-weight: 700; }
```

- **Custom properties:** `--poily-font` · `--poily-accent` · `--poily-text` · `--poily-muted` · `--poily-field-bg` · `--poily-field-border` · `--poily-field-radius` · `--poily-button-bg`/`-text`/`-radius` · `--poily-gap` · `--poily-label-color`/`-weight` · `--poily-error`
- **Parts:** `form` · `intro` · `field-grid` · `field` · `label` · `input` · `select` · `textarea` · `options` · `option` · `button` · `error` · `success` · `required`
- **Slots:** `<span slot="header">` / `<span slot="footer">` for your own microcopy.
- **Events (bubble):** `poily:ready {schema}`, `poily:submitted {id}`, `poily:error {error}`.
- On-brand by default (the form's configured styles seed it; your CSS wins). Two-column for half-width fields, collapsing on narrow screens. Attribution and honeypot are automatic.

## 3 · SDK — keep your own form (your markup)

When the site already has a pixel-perfect form, keep it: the SDK intercepts its submit, captures attribution from the real page, and sends the data to Poily. Your markup and CSS stay 100% native.

### Attach to an existing Poily form

```html
<script src="https://forms.<product>.com/sdk.js" async></script>
<form data-poily-attach="<slug>" data-poily-placement="home_hero">
  <input name="email" type="email" required>
  <input name="name">
  <input name="_gotcha" tabindex="-1" autocomplete="off"
         style="position:absolute;left:-9999px"><!-- honeypot -->
  <button>Request access</button>
</form>
```

```js
document.querySelector('form').addEventListener('poily:submitted', (e) => {
  // e.detail = { id } — fire your pixel here
})
```

Inputs map by `name` (falling back to `id`); keys starting with `_` are skipped, so the honeypot is ignored by design. Bot fills of `_gotcha` are dropped server-side.

### Programmatic

```js
// enhance an existing form (field→key mapping, callbacks)
Poily.attach(form, '<slug>', { placement: 'home', map: { your_email: 'email' }, onSuccess(r){} })

// …or fully custom UI built from the schema
const schema = await Poily.getSchema('<slug>')   // { fields: [{key,label,type,required,…}], … }
await Poily.submit('<slug>', { email, name }, { placement: 'home_hero' })
```

### No-JS fallback

A plain `<form action>` can point straight at the gateway's REST submit route (`/f/<slug>/submit`); ask the operator for the gateway URL, include the `_gotcha` honeypot, and the response 303-redirects back to your page. Prefer the SDK or component where you can.

## Scan-to-create: `data-poily-import`

*Zero form-building.* `data-poily-attach` needs a Poily form to already exist. **`data-poily-import` removes that step**: it reads your form's fields on first page load, auto-creates the matching Poily form, and then captures submissions to it. Nothing to build in Poily, no field mapping, no slug to copy — the lowest-effort path when the native form already exists.

```html
<script src="https://forms.<product>.com/sdk.js" async></script>
<form data-poily-import="alumni-signup" data-poily-placement="signup_page">
  <!-- your existing fields, unchanged — each needs a name OR an id -->
  <input name="first_name"> <input name="last_name">
  <input name="email" type="email" required>
  <select name="org_type"><option value="university">University</option>…</select>
  <button>Request access</button>
</form>
```

> **⚠️ Three preconditions — the only things that bite.**
>
> 1. **Run on the real deployed origin.** The tenant is resolved from the page's `Origin`, so `localhost` and preview URLs (e.g. `*.netlify.app`) return `403 unknown_origin`. Nothing to fix in code — test where the form actually lives (the product's registered custom domain or its `www.`/`forms.` variants).
> 2. **Validate on the live page in DevTools → Network, never by replaying requests.** A curl replay with hand-written field names can pass while the real page is unwired. The only proof: a real load showing `POST /f/import → 200`, a real submit showing `POST /f/<slug>/submit → 200`, then the row in `app.poily.com → Submissions`.
> 3. **If the submit POST never fires** (rare): the SDK captures on the capture phase, so it beats handlers that stop propagation. You only hit this when the form emits no `submit` event at all (a `type="button"` + onClick, no form submit) — then bind to the button inside the `poily:imported` event.

- **The import key is idempotent** — reloads and other pages using the same key return the same Poily form, never duplicates. Safe to leave on permanently.
- **The slug derives from your key** (stable, predictable). Need an exact one? `data-poily-slug="my-slug"`.
- **Additive sync:** a field you add to the markup later is appended to the Poily form on the next load; operator edits are preserved. A field you want gone must be deleted from the markup (builder deletions reappear on the next import).
- **JS-populated selects self-heal:** the SDK briefly waits for options and backfills on later loads; submitted values are always read live.
- On load the form fires `poily:imported` (`e.detail = {slug, created}`), then behaves exactly like `data-poily-attach`.
- The created form is published immediately and appears in Poily, where the operator can rename, restyle, or wire automations — import gives the form, Poily owns it from there.

### Make your source form import-ready

The submission key (`last_name`, `email`) is what lands in the data, so it should read like the capture you want — never a framework auto-id like `:r1:-email`. Checklist:

- An explicit, stable, snake_case `name` on every capture control (`first_name`, `email`, `company`, `role`).
- A real associated `<label>` (`for`/`htmlFor`) — it becomes the field's label, and (slugified) the fallback key.
- **Render every field at load** — collapsed or hidden is fine; conditionally-*mounted* fields aren't in the DOM at scan time and won't be captured.
- A `value=` on every `<select>` option and every checkbox/radio. Prefix throwaway fields with `_`.

**Generating the form with an AI agent?** Paste this into its prompt so the output is import-ready in one shot:

```
Make this lead form "Poily import-ready":
1. Every data field (input/select/textarea) has an explicit, stable, snake_case `name`
   describing the data (first_name, email, company, saas_url, role) — never a
   framework-generated id.
2. Every field has a real, associated <label> (htmlFor/for) with human-readable text.
3. Render all fields at initial load — no step-gated or conditionally-mounted fields.
   For multi-step UX, keep later fields in the DOM (hidden), not unmounted.
4. An explicit `value` on every <select> option and every checkbox/radio.
5. One <form> element with a real submit button, plus an off-screen honeypot
   input named `_gotcha`.
```

## Verification protocol — do not skip

1. Test in **incognito** with a hard refresh (a cached old renderer can stick for visited sessions).
2. Submit **every** entry point — each popup/slider CTA and the inline form.
3. **DevTools → Network:** the submit POST must hit the Poily gateway (host contains `ju1sxvytc1`; the iframe uses `/graphql`, the SDK and component use `/f/<slug>/submit`). Any other host is a legacy or wrong target — `/dev` in the path is correct.
4. Confirm the row in `app.poily.com → [tenant] → Submissions` (and the form's Responses view).
5. Verify `placement` and UTM/referrer populated on the row (open the page with `?utm_source=test` to check).
6. **Never trust the success toast alone.**

A live demo page showing all three tiers on one form is served at `https://forms.<product>.com/demo.html?slug=<slug>`.

## Troubleshooting

| Symptom | Likely cause | Fix |
|---|---|---|
| Nothing renders / blank iframe | Your page's CSP blocks the loader or iframe | Allow `forms.<product>.com` in `script-src` and `frame-src`; confirm `/embed/forms.js` returns 200 |
| `__poilyOpenForm is not defined` | The loader hadn't loaded when the button fired, or is CSP-blocked | Confirm the script tag is present and returns 200; don't gate the CTA on a not-yet-loaded loader |
| Submit "succeeds" but nothing in Poily | POST hit a legacy pre-Poily backend, or a change wasn't redeployed | Verify the POST host is the Poily gateway; point the loader at the Poily forms domain; redeploy |
| Inline fails but popup works (or vice versa) | Stale cached inline iframe, or the SPA unmounted the embed div | Retest in incognito; keep the embed div stable |
| `403 unknown_origin` on import | Testing from localhost or a preview URL | Test on the product's registered domain (see scan-to-create preconditions) |
| Renderer looks old or wrong | CDN cache, or the forms domain is bound to the wrong tenant | Escalate to the product's Poily operator |

**Escalate to the product's Poily operator** when the POST hits a non-Poily gateway even after a clean redeploy, or when submissions return 200 from the Poily gateway but don't appear in Submissions — both are platform-side.

---

*Poily forms reference for host-site developers and agents. The attribute names, globals, and events shown here are platform-wide and identical for every product — only the forms domain and the slug are yours. Questions beyond this page go to the product's Poily operator.*


---

<!-- https://docs.poily.com/prompts/import · source: Apps/handoffs/admin_mkt/poily-import-integration-prompt.md · last synced: 2026-11-03 -->
# Poily import integration — reusable agent prompt (scan-to-create)

A **tenant-agnostic** handoff for wiring any site's existing native `<form>` to Poily in **one pass**.
Fill the four blanks, run the operator precheck, then paste the block to that site's agent. Mechanics
live in the forms guide at https://docs.poily.com/forms — this prompt just gates the three things that actually bite.

## Operator fill-ins
- `{{FORMS_DOMAIN}}` — the tenant's Poily forms host, e.g. `forms.alumnihub.co`
- `{{PAGE_URL}}` — the **deployed** page with the form, e.g. `https://alumnihub.co/`
- `{{FORM_SELECTOR}}` — the form on that page, e.g. `#ea-form` (or "the signup form")
- `{{IMPORT_KEY}}` — a stable, lowercase key (also becomes the form's slug), e.g. `alumnihub-signup`

## Operator precheck — out of scope for the agent; confirm these first
1. The tenant's `custom_domain` is registered in its brand kit (so `Origin` resolves to the line) and `{{FORMS_DOMAIN}}` is live.
2. The SDK on that host is **current**: `curl -s https://{{FORMS_DOMAIN}}/sdk.js | grep -c fieldKey` → must be `> 0`.
3. The agent can edit the **deployed** source of `{{PAGE_URL}}` (not just a preview/staging build).

---

## Prompt (paste to the tenant's marketing-site agent)

> Wire our existing signup form to Poily's scan-to-create import. Poily auto-builds the lead form from
> our markup — no form-building, no field renaming, fields keyed by `name` **or** `id`.
>
> **1) Edit `{{FORM_SELECTOR}}` on `{{PAGE_URL}}` — add two attributes, change nothing else:**
> ```html
> <form … data-poily-import="{{IMPORT_KEY}}" data-poily-placement="signup_page">
> ```
> **2) Load the SDK once near `</body>`:**
> ```html
> <script src="https://{{FORMS_DOMAIN}}/sdk.js" async></script>
> ```
> Deploy the change to **`{{PAGE_URL}}`** — the real live origin. (A `localhost` or preview URL won't
> resolve our tenant and will 403; the import keys the tenant off the page's `Origin`.)
>
> **3) Verify on the LIVE page — do NOT replay requests.** Load `{{PAGE_URL}}` in incognito, open
> DevTools → Network:
> - On load: `POST …/dev/f/import` → `200 {"slug":"{{IMPORT_KEY}}","created":…}` (confirms your fields
>   were scanned).
> - Submit the form: `POST …/dev/f/{{IMPORT_KEY}}/submit` → `200 {"id":"…"}` (confirms capture).
> - A "success" message from our own form proves nothing — only these two real POSTs do.
>
> **4) If step 3 shows NO `…/submit` POST**, our form's own JS consumed the submit event — add this and
> retest:
> ```html
> <script>
> document.addEventListener('poily:imported', function (e) {
>   var form = e.target, slug = e.detail.slug;
>   var btn = form.querySelector('[type=submit], button');
>   if (btn) btn.addEventListener('click', function () {
>     Poily.submit(slug, Poily.readForm(form), { placement: 'signup_page' });
>   });
> });
> </script>
> ```
>
> **Report:** the slug, the import `created` flag, and the submit `id` — taken from the real Network
> trace, not a replay. The Poily operator confirms the lead landed under the tenant.

---

## What the operator verifies after
`app.poily.com → [tenant] → Forms` shows the new form (`{{IMPORT_KEY}}`); `→ Submissions / Leads`
shows the test row. Delete the test lead once confirmed. JS-populated `<select>` options self-heal on
the next page load (deferred scan + backfill) — no action needed.


---

<!-- https://docs.poily.com/prompts/high-fidelity · source: Apps/handoffs/admin_mkt/poily-form-highfidelity-prompt.md · last synced: 2026-11-03 -->
# Poily high-fidelity integration — reusable agent prompt (`<poily-form>`)

For when a site wants **Poily to render the form** (schema, validation, submission, attribution all
owned by Poily) but styled to look **native/on-brand** — no iframe, one custom element. This is the
middle tier of the forms guide (https://docs.poily.com/forms), the counterpart to scan-to-create
import. Use it for the "we want a Poily-managed form that looks like ours" case.

## Operator fill-ins
- `{{FORMS_DOMAIN}}` — tenant forms host, e.g. `forms.doerfy.com`
- `{{SLUG}}` — a **published** Poily form's slug (from `app.poily.com → Forms → [form] → Distribution`)
- `{{PAGE_URL}}` — the **deployed** page to place it on
- `{{PLACEMENT}}` — per-CTA attribution tag, e.g. `home_hero`
- `{{BRAND}}` — the site's font / accent color / radius (for the CSS below)

## Operator precheck — confirm first
1. A **published** Poily form exists and you have its `{{SLUG}}` (unlike import, this tier does **not**
   create the form — it renders an existing one). If you don't have one, use the scan-to-create import
   prompt first, or build it in the Forms module.
2. `{{FORMS_DOMAIN}}/poily-form.js` is live and current: `curl -sI https://{{FORMS_DOMAIN}}/poily-form.js` → 200.
3. The agent can edit the **deployed** source of `{{PAGE_URL}}` (not just a preview).

---

## Prompt (paste to the tenant's marketing-site agent)

> Render our Poily form on the page with Poily's `<poily-form>` web component, styled to match our
> brand. Poily owns the schema/validation/submission/attribution; we own the CSS.
>
> **1) Add the component where the form should appear on `{{PAGE_URL}}`:**
> ```html
> <script src="https://{{FORMS_DOMAIN}}/poily-form.js" async></script>
> <poily-form slug="{{SLUG}}" placement="{{PLACEMENT}}"></poily-form>
> ```
> **2) Style it from our stylesheet** (these pierce the component's shadow DOM — no iframe limits):
> ```css
> poily-form {
>   --poily-font: {{BRAND font}};
>   --poily-accent: {{BRAND accent}};
>   --poily-field-radius: {{BRAND radius}};
>   --poily-gap: 18px;
>   /* also available: --poily-text --poily-muted --poily-field-bg --poily-field-border
>      --poily-button-bg --poily-button-text --poily-button-radius --poily-label-color
>      --poily-label-weight --poily-error */
> }
> poily-form::part(button) { text-transform: uppercase; letter-spacing: .04em; }
> poily-form::part(label)  { font-weight: 700; }
> /* parts: form intro field-grid field label input select textarea options option button error success required */
> ```
> Optional microcopy via slots: `<span slot="header">…</span>`, `<span slot="footer">No credit card. No spam.</span>`.
> Half-width fields auto-flow into a 2-column grid; it collapses to one column on narrow screens.
>
> **3) Deploy to `{{PAGE_URL}}` — the real live origin** (the component fetches the schema + submits to
> the Poily gateway, and CORS keys off your origin; a preview/localhost may be blocked).
>
> **4) Verify on the LIVE page — not a replay.** DevTools → Network + Console:
> - `poily:ready` fires (the schema loaded) and the form renders styled.
> - Submit → `POST …/dev/f/{{SLUG}}/submit` → `200 {"id":"…"}` and a `poily:submitted` event.
> - Then the row in `app.poily.com → [tenant] → Submissions` (with `{{PLACEMENT}}` + any UTMs).
>
> **Report:** the submit `id` from the real Network trace, and a screenshot of the styled form.

---

## import vs high-fidelity — pick the tier
- **`data-poily-import` (scan-to-create):** you already have a native `<form>`; Poily builds its form from your
  markup and captures. Your HTML renders. Zero form-building.
- **`<poily-form>` (this prompt):** you want **Poily** to render a managed form that *looks* native.
  Needs an existing slug. Best when there's no good native form to reuse, or you want Poily to own
  validation/layout while matching your brand.