# Claiming your account

Source: https://docs.ospry.ai/guides/getting-started/claiming-your-account

**Who this is for:** New customers (direct and agency), the first person to set up the account  ·  **Where:** Welcome page at `/welcome`

## What this does
After you pay on the OSPRY website, you land on a Welcome page that turns your purchase into a working account and makes you its Owner. Claiming links your sign-in to the account so you can enter the portal.

## Steps
1. Complete checkout on the OSPRY website. You are redirected to the Welcome page automatically.
2. Watch which state the Welcome page shows:
   - **Finalizing your account**: your payment is still confirming with Stripe. This usually takes a few seconds. Click **Refresh** (or reload the page) in a moment.
   - **Sign in to claim your account**: your account is ready and you need to sign in. Sign in with the email you want to own the account (Google, GitHub, or an email magic link).
   - **You are all set**: you are signed in and the account is ready to enter.
3. On the "You are all set" screen, click **Enter OSPRY**. You are taken to your Dashboard as the account Owner.

## Tips & FAQs
- **The first person to claim becomes the Owner.** Invite the rest of your team afterward (see Managing users).
- **Use the right email.** Sign in with the email address that should own the account. You can add teammates later.
- **The claim link expires.** Your one-time signup link is valid for a limited window (about 30 days). If you see "This signup link has expired", contact support to get back in.
- **Stuck on "Finalizing" for more than a minute?** Refresh once more. If it persists, your payment may still be settling; wait a moment and try again, or contact support.
- **Agency accounts:** the person who claims becomes the agency Owner and can then add client sub-accounts from the Agency area.

## Related
- [Signing in](https://docs.ospry.ai/guides/getting-started/signing-in)
- [A tour of the portal](https://docs.ospry.ai/guides/getting-started/portal-tour)
- [Roles and what each one can see](https://docs.ospry.ai/guides/getting-started/roles-and-visibility)
- [Install the OSPRY pixel](https://docs.ospry.ai/guides/installing-the-script/install-the-sight-pixel)

---

# Signing in

Source: https://docs.ospry.ai/guides/getting-started/signing-in

**Who this is for:** Everyone on the account (all roles, both account types)  ·  **Where:** Sign-in page at `/sign-in`

## What this does
Signs you in to the OSPRY portal. OSPRY uses a hosted sign-in, so you do not manage a separate OSPRY password; you sign in with Google, GitHub, or an email magic link.

## Steps
1. Go to the sign-in page (`/sign-in`) or click the sign-in link from an invite or the website.
2. Choose how to sign in:
   - **Continue with Google** or **Continue with GitHub**, or
   - Enter your email address to receive a one-time magic link, then open the link from your inbox.
3. Once authenticated, you are taken into the portal. If you already claimed the account, you land on your Dashboard.

## Tips & FAQs
- **No password to remember.** Sign-in is passwordless or social by design. If a magic-link email does not arrive, check spam and confirm you typed the right address.
- **Use the email you were invited with.** If a teammate added you, sign in with that exact email so your membership matches.
- **New here?** If you have not bought yet, you will not have an account to sign in to. Purchase first, then follow [Claiming your account](https://docs.ospry.ai/guides/getting-started/claiming-your-account).
- **Signing out:** open the account menu in the top bar and choose **Log out**.
- **Light and dark:** the sign-in card matches your theme automatically.

## Related
- [Claiming your account](https://docs.ospry.ai/guides/getting-started/claiming-your-account)
- [A tour of the portal](https://docs.ospry.ai/guides/getting-started/portal-tour)
- [Roles and what each one can see](https://docs.ospry.ai/guides/getting-started/roles-and-visibility)
- [Managing users](https://docs.ospry.ai/guides/account-and-team/managing-users)

---

# A tour of the portal

Source: https://docs.ospry.ai/guides/getting-started/portal-tour

**Who this is for:** Everyone on the account (all roles, both account types)  ·  **Where:** Anywhere in the portal after you sign in

## What this does
Gives you the lay of the land: the left sidebar groups, the account menu, and what each area is for, so you know where to go next.

## The sidebar groups
The left sidebar is organized into groups. You see the groups that apply to your role and account type.

- **Observe**: what is happening on your site right now.
  - **Dashboard**: your identification volume, top pages, and campaign attribution.
  - **Analytics**: traffic and behavior over time.
  - **Top Pages**: high-intent URLs you want to track.
  - **Heatmaps**: where visitors click and scroll.
  - **Intent**: score visitors on behavioral signals (scrolls, video, downloads, form submits).
  - **Script**: your install snippet, domains, and capture settings.
- **Score**: qualifying and ranking what you observed.
  - **Top Leads**: rules that tag and route your best-fit visitors.
  - **Automations**: trigger on how often a visitor returns (velocity rules).
- **Profile**: who your visitors are.
  - **People**: the feed of identified people.
  - **Companies**: the feed of identified companies.
  - **Contacts**: your own contact roster. Owners, admins and agency admins only.
  - **Businesses**: your own business roster. Owners, admins and agency admins only.
  - **Enrichment**: deep enrichment and AI insights.
  - **Form Mapping**: send your own site's form fields into a contact record.
- **Reach**: getting the data and the message back out.
  - **Pop-ups**: ask a known visitor one question on your own site.
  - **Outbound Integrations**: connect your CRM, Slack, sequencers, webhooks, and more.
  - **Exports**: download your identified profiles as CSV.
  - **Inbound Integrations**: bring contacts in. Owners, admins and agency admins only.
  - **HighLevel**: a shortcut that appears once a HighLevel connection exists.
  - **Company Profile**, **Professional Profile**, **Products & Services**, **Templates**, **Documents**, **Prompts**: the material the AI writes from.
- **Yield**: the answers you get back out.
  - **HarleyQ Chat** and **HarleyQ Roll-up Insights**.
- **Help and support**
  - **Support**: reach the support team.

Agency accounts get their own rail instead, reached from the product switcher on the far-left dock: **Dashboard**, **Sub Accounts** (Sub Account Dashboard, Plans, Rebilling) and **White-label** (Branding, Domains, Email).

## The account menu
The account menu sits at the bottom of the far-left dock and holds account-wide settings:

- **My Profile** (your own name, phone, address and LinkedIn).
- **Settings** (company name, timezone, ICP, enrichment). Its tabs also hold **Notifications** (daily CSV opt-in and recipient emails) and **Geo restrictions** (the US-only vs global consent control).
- **Users** (your team and their roles).
- **Security**.
- **Compliance** (setup checklist, consent banner, geo and scope).
- **Billing** (subscription, usage, invoices) and **Wallet**. Available to owners, admins and agency admins only.
- **Log out**.

## Tips & FAQs
- **"Coming soon" items.** Some sidebar entries may appear dimmed with a "coming soon" tag. Those features are not available on your account yet; they become active as they ship.
- **Badges.** Some entries (people, companies, top leads) can show a count badge so you can see new activity at a glance.
- **What you see depends on your role and plan.** If a teammate sees something you do not, it is usually a role or plan difference. See [Roles and what each one can see](https://docs.ospry.ai/guides/getting-started/roles-and-visibility).
- **Agency vs direct.** Only agency accounts see the Agency rail and the sub-account console.

## Related
- [Roles and what each one can see](https://docs.ospry.ai/guides/getting-started/roles-and-visibility)
- [The dashboard at a glance](https://docs.ospry.ai/guides/visitors/dashboard-overview)
- [Person-level visitors](https://docs.ospry.ai/guides/visitors/person-level-visitors)
- [Integrations overview](https://docs.ospry.ai/guides/automation/integrations-overview)

---

# Roles and what each one can see

Source: https://docs.ospry.ai/guides/getting-started/roles-and-visibility

**Who this is for:** Owners and admins planning who does what (useful for everyone)  ·  **Where:** Account menu -> Users (`/account?tab=users`)

## What this does
Explains the roles in OSPRY and what each one can do, so you can give teammates the right level of access.

## The roles
OSPRY uses these roles:

- **Owner**: full control of the account, including billing and account deletion.
- **Admin**: full control of day-to-day settings and configuration, including billing.
- **Member**: can use and view the product, but cannot change most settings.
- **Agency admin**: on agency accounts, manages the agency and its client sub-accounts (including billing).

Owners, admins, and agency admins are the **privileged** roles. They can change settings that members cannot.

## What members can and cannot do
Members can browse the visitor feeds, open profiles, and view most pages. Members generally **cannot** create or change configuration. In practice:

- **Top leads / Top pages / Automations / Intent**: members can view existing rules, but the create and edit controls (for example "Add page") are hidden. Editing is limited to owners and admins.
- **Integrations and ABM advertising**: members have read-only access. Connecting, setting up, or changing a destination is limited to owners, admins, and agency admins.
- **Consent banner**: members can view it, but editing is limited to owners, admins, and agency admins.
- **Geo restrictions and Compliance**: only owners and admins can change these (they are compliance controls). Agency admins cannot change them.
- **Billing**: only owners, admins, and agency admins can open the Billing page; members do not see it at all.
- **Account settings, Users, Notifications**: editing is limited to owners, admins, and agency admins. Members can view.
- **Daily CSV export opt-in**: members can view exports, but only owners, admins, and agency admins can toggle the daily email.

## Tips & FAQs
- **Who is the Owner?** The person who first claimed the account. See [Claiming your account](https://docs.ospry.ai/guides/getting-started/claiming-your-account).
- **Changing a teammate's role.** Role changes and invitations are handled through OSPRY user management; the Users tab shows current memberships in real time. See [Managing users](https://docs.ospry.ai/guides/account-and-team/managing-users).
- **Agency visibility.** Only agency accounts show the Agency group and the sub-account console, and that console is available to agency admins.
- **If you cannot see a setting,** it is almost always because your role does not have access. Ask an owner or admin.

## Related
- [Managing users](https://docs.ospry.ai/guides/account-and-team/managing-users)
- [Account settings](https://docs.ospry.ai/guides/account-and-team/account-settings)
- [A tour of the portal](https://docs.ospry.ai/guides/getting-started/portal-tour)
- [Subscription and billing](https://docs.ospry.ai/guides/billing-and-plans/subscription-and-billing)

---

# Install the tag

Source: https://docs.ospry.ai/guides/installing-the-script/install-the-sight-pixel

**Who this is for:** Owners and admins (the snippet and domains are editable by privileged roles)  ·  **Where:** Portal -> Observe -> Script (`/script`)

## What this does
Adds one tag to your website that turns on visitor tracking and, if you have set one up, your consent banner. One tag covers both: OSPRY loads your consent banner first (when it is enabled), then the tracking pixel, so the pixel always waits behind the banner. You install it once per site, then verify it is firing.

## Steps
1. Open **Observe -> Script** in the sidebar.
2. In the **Your snippet** panel, click **Copy** to copy your tag. It looks like this (your account id is filled in for you):

```html
<!-- OSPRY by Legion -->
<script async src="https://px.lspxl.com/c/your-account-id"></script>
```

3. Paste this into the `<head>` of every page, as early as possible, before your other scripts, or add it through Google Tag Manager.
4. Add your domain in the **Domains** panel if it is not already listed, then install the tag on that domain.
5. Publish your site, then verify the script (see [Verify the script is working](https://docs.ospry.ai/guides/installing-the-script/verify-the-script-is-working)).

## Content-Security-Policy
If your site runs a Content-Security-Policy, allow these hosts:

- **script-src**: `px.lspxl.com`, `cdn.lgncmp.com`
- **style-src**: `cdn.lgncmp.com`
- **connect-src**: `lgncmp.com`, `i.lspxl.com`, `popup.lspxl.com`, `sec.lspxl.com`, `t.lspxl.com`

## Where it loads
The tag loads on your apex domain plus its `www.` and `app.` subdomains. It is identical across platforms; only where you paste it differs. Per-platform guidance is available behind the **Per-platform install guides** note on the Script page (WordPress, Google Tag Manager, Webflow, Framer, Shopify, Squarespace, Wix, HubSpot CMS, Kajabi, and code-level installs for Next.js, React, TypeScript, and Angular).

## Installed the older two-tag version?
If you installed the pixel snippet and the consent banner loader as two separate tags, both keep working exactly as they do today. Nothing breaks and nothing requires action. When you are ready, remove both old tags and paste the single tag from this guide in their place, so you have one line to maintain instead of two.

## Capture settings (optional)
Below the snippet, the **Domains** and **Visitor capture settings** panels let you control what is captured per domain:

- **URL restrictions**: limit capture to, or exclude, specific pages.
- **Repeat visitor collection**: off by default. Repeat visitors are not re-recorded and are always free. Turn it on to capture return visits (a strong buying signal); repeats stay free either way.
- **Exclusion list**: domains (for example, free email providers or your own internal traffic) to exclude.

After changing capture settings, click **Save settings**.

## Tips & FAQs
- **Owners and admins only.** Members can view the Script page but cannot add domains or change capture settings.
- **Capture paused?** If capture is paused, a banner appears: settings still save, but no new visitors are captured until capture is resumed from the top bar. Adding or verifying a domain does not resume capture.
- **Domains are a plan inclusion.** Your plan includes a set number of domains (and seats); you are not billed per active domain. If you need more domains than your plan includes, move up a tier. See [Subscription and billing](https://docs.ospry.ai/guides/billing-and-plans/subscription-and-billing).
- **View the raw script.** The **View** button opens the served snippet in a new tab so you can confirm it loads.
- **No consent banner set up yet?** The tag still installs your tracking pixel on its own. Add a banner any time from [Set up your consent banner](https://docs.ospry.ai/guides/installing-the-script/consent-banner-setup); once it is enabled, the same tag starts loading it too, with no snippet change needed.

## Related
- [Verify the script is working](https://docs.ospry.ai/guides/installing-the-script/verify-the-script-is-working)
- [Set up your consent banner](https://docs.ospry.ai/guides/installing-the-script/consent-banner-setup)
- [Subscription and billing](https://docs.ospry.ai/guides/billing-and-plans/subscription-and-billing)
- [The dashboard at a glance](https://docs.ospry.ai/guides/visitors/dashboard-overview)

---

# Verify the script is working

Source: https://docs.ospry.ai/guides/installing-the-script/verify-the-script-is-working

**Who this is for:** Owners and admins  ·  **Where:** Portal -> Observe -> Script (`/script`)

## What this does
Checks that your installed snippet is actually firing on your site, and helps you fix it if it is not. Each domain row shows a verification status you can re-check on demand.

## Steps
1. Open **Observe -> Script**.
2. Find your domain in the **Active domains** list.
3. Click **Test script** on that domain row. OSPRY runs a live check against the page.
4. Read the result:
   - **Verified**: the snippet is firing correctly. You are done.
   - **Failed**: open the **Installation Debugger** to see which checks did not pass, fix the snippet on your site, and re-test.
5. Re-test after any change until the row shows verified.

## Tips & FAQs
- **Publish first.** Verification checks your live site, so deploy or publish the page with the snippet before testing.
- **Give it a moment.** If you just added the snippet, wait for your site's cache or CDN to refresh, then re-test.
- **Failed last time?** When you open the debugger for a domain whose last check failed, it tells you the last verification failed and to re-check after confirming the snippet is installed.
- **Capture paused.** Verifying a domain does not resume capture. If capture is paused, resume it from the top bar to start collecting visitors again.
- **Still failing?** Confirm the snippet is on the right domain (apex, `www.`, or `app.`), not blocked by a tag manager, and not stripped by a security or privacy tool. If you are stuck, contact support.

## Related
- [Install the OSPRY pixel](https://docs.ospry.ai/guides/installing-the-script/install-the-sight-pixel)
- [Set up your consent banner](https://docs.ospry.ai/guides/installing-the-script/consent-banner-setup)
- [Person-level visitors](https://docs.ospry.ai/guides/visitors/person-level-visitors)
- [Contacting support](https://docs.ospry.ai/guides/help/contacting-support)

---

# Set up your consent banner

Source: https://docs.ospry.ai/guides/installing-the-script/consent-banner-setup

**Who this is for:** Owners and admins (the banner is editable by privileged roles; availability depends on your plan)  ·  **Where:** Account menu -> Compliance -> Consent Banner (`/cmp`)

## What this does
Configures a cookie consent banner (a CMP) that you can install on your site. Every option is a guided choice (dropdowns, toggles, a category checklist, a bounded color picker, a logo URL, and translations). There is no raw CSS to write. A live preview shows your changes as you make them.

## Steps
1. Open **Account menu -> Compliance -> Consent Banner**.
2. Your banner installs through the same tag as your tracking pixel, so there is no separate banner snippet. The **Install & status** panel shows that one tag with a **Copy** button (the same tag as the Script page) and the public config URL for reference. If the tag is already on your site, enabling the banner below is all you need to do; otherwise see [Install the tag](https://docs.ospry.ai/guides/installing-the-script/install-the-sight-pixel).
3. In the **Configuration** panel, set your options:
   - **Consent categories**: choose which categories visitors can consent to. **Necessary** is always on and cannot be turned off.
   - **Pixel-unlock category**: pick the category that, once accepted, unlocks the OSPRY pixel (or leave it as "none" to keep the pixel gated).
   - **Default language** and **Language auto-detect**.
   - **Theme** (for example, light or dark).
   - **Consent modal layout** and **Preferences modal layout**: layout, position, and the flip/equal-weight button options.
   - Display options: block the page until a choice is made, disable transitions, and show or hide "Powered by OSPRY".
   - **Logo URL** and **Brand colors** (each color is a bounded picker; you can leave any token on the theme default).
   - **Translations**: edit the banner text per language.
4. Watch the **Live preview** to confirm the look and copy.
5. Click **Save banner config** (or **Create banner config** the first time).
6. When you are ready to show it to visitors, use **Enable banner** in the Install & status panel. To stop showing it, use **Disable banner**.

## Tips & FAQs
- **Enabling and disabling take effect quickly.** When you enable or disable the banner, it can take up to about 5 minutes to reach your installed site. You will be asked to confirm before the change applies.
- **Why it matters.** If you identify visitors outside the US, you must run a consent tool that gates the OSPRY script until the visitor accepts. This banner is one way to meet that requirement. See [Geo restrictions and consent](https://docs.ospry.ai/guides/billing-and-plans/geo-restrictions).
- **No raw CSS by design.** Colors are bounded tokens and every control is a constrained choice, so you cannot break the banner with custom styling. The server validates your config when you save.
- **Not on your plan?** If the consent banner is not included in your plan, the page says so and tells you to contact us to enable it.
- **Members** can view the banner but cannot change it.

## Related
- [Install the OSPRY pixel](https://docs.ospry.ai/guides/installing-the-script/install-the-sight-pixel)
- [Geo restrictions and consent](https://docs.ospry.ai/guides/billing-and-plans/geo-restrictions)
- [Verify the script is working](https://docs.ospry.ai/guides/installing-the-script/verify-the-script-is-working)
- [Account settings](https://docs.ospry.ai/guides/account-and-team/account-settings)

---

# The dashboard at a glance

Source: https://docs.ospry.ai/guides/visitors/dashboard-overview

**Who this is for:** Everyone on the account  ·  **Where:** Portal -> Observe -> Dashboard (`/dashboard`)

## What this does
The Dashboard is your home screen. It summarizes how many people and companies OSPRY identified, your top pages, and which campaigns drove identified visitors, for the date range you pick.

## Steps
1. Open **Observe -> Dashboard**. It greets you with "Welcome back, [your company]".
2. Pick a date range using the selector in the top right: **Today**, **Past Week**, **Past Month**, or **Past Quarter**. The range is saved in the page address, so you can bookmark or share a view.
3. Read the four stat tiles:
   - **People identified**: distinct people identified in the range.
   - **Companies**: distinct companies identified in the range.
   - **Top leads**: identified visitors that matched your ICP tags.
   - **Lead spend**: charged resolutions in the range (the dollar total is on the billing page).
4. Review the charts below the tiles:
   - **Identification types per day**: new profiles, repeat profiles, and companies, day by day.
   - **Top URLs**: your five most-visited captured pages in the range.
   - **Campaign attribution (UTM)**: identified profiles grouped by campaign.

## Tips & FAQs
- **Numbers look low or empty?** If you just installed the script, give it time to collect and resolve traffic. Confirm the script is verified on the Script page.
- **Repeat profiles only show when enabled.** The repeat line appears once repeat-visitor collection has recorded return visits. See the Script page capture settings.
- **The range is shareable.** Because the range lives in the page address, sending a teammate the link shows them the same window.
- **Want the underlying records?** Drill into [Person-level visitors](https://docs.ospry.ai/guides/visitors/person-level-visitors) and [Company-level visitors](https://docs.ospry.ai/guides/visitors/company-level-visitors).

## Related
- [Person-level visitors](https://docs.ospry.ai/guides/visitors/person-level-visitors)
- [Company-level visitors](https://docs.ospry.ai/guides/visitors/company-level-visitors)
- [Understanding usage and metering](https://docs.ospry.ai/guides/billing-and-plans/understanding-usage-and-metering)
- [Top leads](https://docs.ospry.ai/guides/tagging/top-leads)

---

# Person-level visitors

Source: https://docs.ospry.ai/guides/visitors/person-level-visitors

**Who this is for:** Everyone on the account  ·  **Where:** Portal -> Profile -> People (`/people`)

## What this does
Shows the feed of identified people who visited your site. Each card carries the person's identity, fit, intent, and a contact handle so you can act on them.

## What is on each card
- Name and (when available) a LinkedIn link.
- Title and company.
- Business email (with a copy button).
- Location.
- How many pages they viewed and the most recent pages.
- Last seen (relative time) and the referrer.
- ICP fit score, when enrichment has run.
- **View** opens the full person profile. (A Share action is marked "coming soon".)

## Filtering the feed
Use the filter rail on the right:

1. **Page views**: limit to visitors with 2+, 5+, 10+, or 20+ views.
2. **Search by email**: find a specific person by email.
3. **Seen since**: show only visitors seen on or after a date.
4. **Sort**: by **Last seen** or **ICP-fit** (ICP-fit ranking activates once enrichment runs).
5. Click **Apply filters**. Page-view, since, and sort changes apply as you choose them; the email search applies on Apply.

The rail also has an **Export options** button that jumps to the Exports page.

## Steps
1. Open **Profile -> People**.
2. Narrow the list with the filters on the right.
3. Click **View** on a card to open the full profile.

## Tips & FAQs
- **No people yet?** Once your tracking script resolves visitors, identified people appear here. Try widening your filters, or confirm the script is installed and verified.
- **Email copy.** Click the email to copy it to your clipboard for quick outreach.
- **ICP fit.** The ICP-fit score and ICP sort depend on enrichment running for your account.
- **Top lead tagging is not on this feed yet.** The Top Leads filter on the rail is marked "soon", and a card carries no top-lead tag today. Manage your rules on the Top Leads page in the meantime. See [Top leads](https://docs.ospry.ai/guides/tagging/top-leads).

## Related
- [Reading a person profile](https://docs.ospry.ai/guides/visitors/person-detail)
- [Company-level visitors](https://docs.ospry.ai/guides/visitors/company-level-visitors)
- [Exporting your visitor data](https://docs.ospry.ai/guides/exports-and-data/exporting-visitor-data)
- [Top leads](https://docs.ospry.ai/guides/tagging/top-leads)

---

# Reading a person profile

Source: https://docs.ospry.ai/guides/visitors/person-detail

**Who this is for:** Everyone on the account  ·  **Where:** Portal -> Profile -> People -> View (`/people/[id]`)

## What this does
Shows everything OSPRY knows about one identified person: their profile fields, their journey across your site, and an AI insight panel.

## What is on the page
- **Header**: name, a person tier badge, and (when available) title and company. A **LinkedIn** button opens their profile in a new tab. (A "Share profile" button is marked coming soon.)
- **Profile** panel (the fields that are present for that person):
  - Title, Seniority, Company, Industry, Company size, Est. revenue, Location.
  - **Business email** (with a copy button).
  - **Match**: "Deterministic" or "Probabilistic", indicating how the identity was matched.
  - **First seen** and **Last seen**.
- **Visitor journey** panel: a grouped, expandable timeline of everything this person did on your site. It replaced the old flat visit table, so it reads as a story rather than a list.
  - An overview strip across the top: **Intent score** with its band and window, **Engagement** (visits and events), **Lifecycle** (first seen, and how long ago they were last seen), **Activity** (a sparkline of events per visit), and **Sources / Campaigns** when any are known.
  - Below it, one entry per visit, newest first. Each carries when it happened, the source domain, the first page of the visit, and a tag for what kind of visit it was. Expand a visit to see the pages in it, and expand a page to see the individual actions with their details and times.
- **AI insight** panel: an AI-generated insight about the person (depends on enrichment for your account).

## Steps
1. From **Person-level visitors**, click **View** on a card.
2. Review the Profile fields and the Visitor journey.
3. Use **LinkedIn** to open the person's profile, or copy the business email for outreach.
4. Click **Back to people** to return to the feed.

## Tips & FAQs
- **Fields vary by person.** Only fields OSPRY resolved are shown; sparse profiles show fewer rows.
- **Deterministic vs probabilistic.** "Deterministic" means a high-confidence match; "probabilistic" is an inferred match.
- **AI insight depends on enrichment.** If insights are not enabled for your plan, the panel reflects that. Enrichment mode is set on Account settings.
- **The journey is per profile.** It groups this person's activity by visit, with the source domain and campaign shown where known. A person with no recorded activity yet shows an empty journey rather than a blank panel.

## Related
- [Person-level visitors](https://docs.ospry.ai/guides/visitors/person-level-visitors)
- [Reading a company profile](https://docs.ospry.ai/guides/visitors/company-detail)
- [Account settings](https://docs.ospry.ai/guides/account-and-team/account-settings)
- [Exporting your visitor data](https://docs.ospry.ai/guides/exports-and-data/exporting-visitor-data)

---

# Company-level visitors

Source: https://docs.ospry.ai/guides/visitors/company-level-visitors

**Who this is for:** Everyone on the account  ·  **Where:** Portal -> Profile -> Companies (`/companies`)

## What this does
Shows the feed of identified companies. When OSPRY resolves the organization but not the individual, the visit lands here. You still get the company name, website, industry, size, and estimated revenue, which is enough to prioritize an account for ABM.

## What is on each card
- Company name and (when available) a LinkedIn link.
- Industry.
- Website.
- Size (employee count and estimated revenue).
- Location.
- Page views.
- Last visit (relative time).
- ICP fit score, when enrichment has run.
- **View details** opens the full company profile. (A Share action is marked "coming soon".)

## Filtering the feed
The filter rail mirrors the people feed, without the email search:

1. **Page views**: 2+, 5+, 10+, or 20+ views.
2. **Seen since**: a start date.
3. **Sort**: **Last seen** or **ICP-fit**.
4. Click **Apply filters**.

There is also an **Export options** button to jump to the Exports page.

## Steps
1. Open **Profile -> Companies**.
2. Filter to the accounts you care about.
3. Click **View details** to open the company profile.

## Tips & FAQs
- **No companies yet?** Company-level resolutions appear once OSPRY can name the organization behind a visit.
- **Company vs person.** A visit shows here when OSPRY identified the company but not a specific individual. Person-level identifications are in the [people feed](https://docs.ospry.ai/guides/visitors/person-level-visitors).
- **Great for ABM.** Even without a named person, company-level visits tell you which accounts are showing interest. Pair this with [ABM advertising](https://docs.ospry.ai/guides/automation/abm-advertising).

## Related
- [Reading a company profile](https://docs.ospry.ai/guides/visitors/company-detail)
- [Person-level visitors](https://docs.ospry.ai/guides/visitors/person-level-visitors)
- [ABM advertising](https://docs.ospry.ai/guides/automation/abm-advertising)
- [Exporting your visitor data](https://docs.ospry.ai/guides/exports-and-data/exporting-visitor-data)

---

# Reading a company profile

Source: https://docs.ospry.ai/guides/visitors/company-detail

**Who this is for:** Everyone on the account  ·  **Where:** Portal -> Profile -> Companies -> View details (`/companies/[id]`)

## What this does
Shows everything OSPRY knows about one identified company: its firmographics, its journey across your site, and an AI insight panel.

## What is on the page
- **Header**: company name, a company tier badge, and the industry. A **LinkedIn** button opens the company page in a new tab. (A "Share profile" button is marked coming soon.)
- **Firmographics** panel (the fields that are present):
  - Industry, Website, Company size, Est. revenue, Location.
  - **First seen** and **Last visit**.
- **Account journey** panel: a grouped, expandable timeline of everything anyone at this company did on your site. It replaced the old flat visit table, so it reads as a story rather than a list.
  - An overview strip across the top: **Engagement** (visits and events), **Lifecycle** (first seen, and how long ago the account was last seen), **Activity** (a sparkline of events per visit), and **Sources / Campaigns** when any are known.
  - Below it, one entry per visit, newest first, labelled with the identified person where OSPRY resolved one and "Anonymous visitor" where it did not. Expand a visit to see the pages in it, and expand a page to see the individual actions with their details and times.
- **AI insight** panel: an AI-generated insight about the account (depends on enrichment for your account).

## Steps
1. From **Company-level visitors**, click **View details** on a card.
2. Review the firmographics and the Account journey.
3. Use the **Website** or **LinkedIn** links to research the account.
4. Click **Back to companies** to return to the feed.

## Tips & FAQs
- **Fields vary by company.** Only resolved fields are shown.
- **The Account journey** groups the activity of everyone at this company by visit, naming the identified person on a visit where OSPRY resolved one, with the source domain and campaign shown where known.
- **Turn interest into action.** Use a company's repeated visits as a signal for outreach or to build an ABM audience. See [ABM advertising](https://docs.ospry.ai/guides/automation/abm-advertising).

## Related
- [Company-level visitors](https://docs.ospry.ai/guides/visitors/company-level-visitors)
- [Reading a person profile](https://docs.ospry.ai/guides/visitors/person-detail)
- [ABM advertising](https://docs.ospry.ai/guides/automation/abm-advertising)
- [Top pages](https://docs.ospry.ai/guides/tagging/top-pages)

---

# Top leads

Source: https://docs.ospry.ai/guides/tagging/top-leads

**Who this is for:** Owners and admins set them up; everyone can view  ·  **Where:** Portal -> Score -> Top Leads (`/top-leads`)

## What this does
Top leads lets you tell OSPRY who your best-fit visitors are. Anyone who matches a filter is tagged automatically (you see a "top lead" tag in the feeds) and routed to the tools you connect.

## Steps
1. Open **Score -> Top Leads**.
2. Click **Set up** (first time) or **New rule**.
3. In the dialog:
   - **Filter name**: a label, shown as the tag on every matching visitor (for example, "Enterprise ICP").
   - **Criteria**: define your best-fit characteristics. Available dimensions include company revenue, company size, seniority, department, category, and geography (countries).
   - **Destinations** (optional): pick connected integrations to route matching visitors to.
4. Click **Create filter** (or **Save changes** when editing).
5. Matching visitors are tagged and pushed to the connected destinations automatically.

## Tips & FAQs
- **Owners and admins only for editing.** Members can view existing filters; they see a prompt to ask an owner or admin to set one up.
- **The name becomes the tag.** Choose a clear filter name; it appears on every matching visitor card and profile.
- **Destinations are optional.** A filter can simply tag visitors, or it can also route them. Connect tools first on the Integrations page if you want routing. See [Connecting an integration](https://docs.ospry.ai/guides/automation/connecting-an-integration).
- **Deliver scope.** On an integration, you can choose to deliver "Top leads only" so a destination only receives visitors matched by a Top Leads filter.
- **Edit any time.** Use the edit control on a rule row to change its criteria or destinations.

## Related
- [Top pages](https://docs.ospry.ai/guides/tagging/top-pages)
- [Connecting an integration](https://docs.ospry.ai/guides/automation/connecting-an-integration)
- [Integrations overview](https://docs.ospry.ai/guides/automation/integrations-overview)
- [Person-level visitors](https://docs.ospry.ai/guides/visitors/person-level-visitors)

---

# Top pages

Source: https://docs.ospry.ai/guides/tagging/top-pages

**Who this is for:** Owners and admins set them up; everyone can view  ·  **Where:** Portal -> Observe -> Top Pages (`/top-pages`)

## What this does
Top pages lets you mark the URLs on your site that carry the best intent (your pricing page, a demo, a case study). Once a page is marked, you can see how many visitors and top leads reached it.

## Steps
1. Open **Observe -> Top Pages**.
2. Click **Add page**.
3. In the dialog:
   - **Page URL or path**: the page (or pattern) you want to track. The host, query string, and trailing slash are ignored, so `/pricing` and `/pricing/?utm=x` match the same page.
   - **Match type**: how the pattern should match. There are two options:
     - **Exact**: the path equals this exactly.
     - **Prefix**: the path starts with this. (A prefix of "/" matches every page on your site.)
4. Click **Add page** to save. The page appears in the table.
5. Review the table columns for each page:
   - **Page**.
   - **Visitors (30d)**: visitors who reached it in the last 30 days.
   - **Top leads**: how many of those were top leads.

## Tips & FAQs
- **Owners and admins only for editing.** Members can view; they are prompted to ask an owner or admin to add a page.
- **Pick high-intent URLs.** Pages like pricing, demo requests, and case studies are the strongest signals.
- **Edit any time.** Use the edit control on a row to change a page's pattern or match type (Exact or Prefix).

## Related
- [Top leads](https://docs.ospry.ai/guides/tagging/top-leads)
- [Automations (velocity rules)](https://docs.ospry.ai/guides/automation/automations)
- [Intent signals](https://docs.ospry.ai/guides/automation/intent-signals)
- [Company-level visitors](https://docs.ospry.ai/guides/visitors/company-level-visitors)

---

# Automations (velocity rules)

Source: https://docs.ospry.ai/guides/automation/automations

**Who this is for:** Owners and admins set them up; everyone can view  ·  **Where:** Portal -> Score -> Automations (`/automations`)

## What this does
Automations trigger on visitor behavior frequency. When a visitor hits your pages enough times in a rolling window, OSPRY classifies them and routes them to the tools you connect. The page also shows your top pages and top visitors over a recent window.

## Steps
1. Open **Score -> Automations**.
2. Click **New rule**.
3. In the rule dialog, define the velocity rule:
   - A **threshold** (how many page hits).
   - A **window** (the rolling time window, for example 7 days).
   - A **scope** and an optional **path pattern** with a match type, to focus the rule on specific pages.
   - A **classification** to apply when the threshold is crossed.
   - **Destinations**: the connected integrations to route the visitor to.
4. Save the rule. Visitors crossing the threshold are classified and pushed to the connected destinations.

A common example: "3 pricing-page hits in 7 days" classifies the visitor and dispatches them to your CRM.

## Top surfaces
Below the rules, the **Top surfaces** section shows all first-party traffic over a recent window (including single-page-app route changes and known-but-anonymous visitors; bot traffic is excluded):

- **Top pages**: Path, Hits, Visitors.
- **Top visitors**: Visitor (resolved label or an anonymous id), Hits.

## Tips & FAQs
- **Owners and admins only for editing.** Members can view rules and the top surfaces.
- **Velocity vs intent.** Automations count page hits. To trigger on richer behavior (deep scrolls, video completes, downloads, form submits), use [Intent signals](https://docs.ospry.ai/guides/automation/intent-signals).
- **Bots do not count.** Bot traffic is excluded from the top surfaces.
- **Connect destinations first.** A rule can route to integrations you have connected on the Integrations page.

## Related
- [Intent signals](https://docs.ospry.ai/guides/automation/intent-signals)
- [Integrations overview](https://docs.ospry.ai/guides/automation/integrations-overview)
- [Top pages](https://docs.ospry.ai/guides/tagging/top-pages)
- [Top leads](https://docs.ospry.ai/guides/tagging/top-leads)

---

# Intent signals

Source: https://docs.ospry.ai/guides/automation/intent-signals

**Who this is for:** Owners and admins set them up; everyone can view  ·  **Where:** Portal -> Observe -> Intent (`/intent`)

## What this does
Intent turns first-party behavioral signals (deep scrolls, video completes, file downloads, form submits) into value. You build scoring rules that count specific intent events for a visitor over a rolling window, classify them when a threshold is crossed, and dispatch them to your connected tools.

## Steps
1. Open **Observe -> Intent**.
2. Click **New rule**.
3. In the rule dialog, define the intent scoring rule:
   - A **threshold** and a **window** (for example, 2 pricing-page deep scrolls and 1 demo-video complete in 7 days).
   - A **scope** and optional **path pattern** with a match type.
   - The **intent types** to count (scrolls, video completes, downloads, form submits).
   - A **classification** (for example, "hot") to apply when the threshold is crossed.
   - **Destinations**: the connected integrations to route the visitor to.
4. Save the rule. When a visitor crosses the threshold, they are classified and routed.

## Privacy and billing posture
The Intent page also shows how the behavioral layer is gated and metered for your account:

- **Privacy**: behavioral collection runs only after consent is granted. It captures metadata only (no form values, no copied content, no keystrokes). It shows whether your consent-management tool is confirmed, whether the consent banner is installed, and whether your opt-out link is published. A data-subject erase clears a person's intent events and sessions along with their other data. A link takes you to **Manage consent & geo settings**.
- **Billing & metering**: your intent volume this period and all time, with a link to view your subscription and usage.

## Tips & FAQs
- **Owners and admins only for editing.** Members can view rules and the posture panels.
- **Consent first.** Behavioral collection is gated on consent. If you identify visitors outside the US, confirm a consent tool first. See [Geo restrictions and consent](https://docs.ospry.ai/guides/billing-and-plans/geo-restrictions).
- **Pageviews vs behavior.** Pageview counts come from Automations; behavioral depth (scrolls, video, downloads, form submits) is counted here.
- **Bots never count** toward a rule's threshold.
- **It is metered.** Intent volume is metered to your account; see [Understanding usage and metering](https://docs.ospry.ai/guides/billing-and-plans/understanding-usage-and-metering).

## Related
- [Automations (velocity rules)](https://docs.ospry.ai/guides/automation/automations)
- [Geo restrictions and consent](https://docs.ospry.ai/guides/billing-and-plans/geo-restrictions)
- [Understanding usage and metering](https://docs.ospry.ai/guides/billing-and-plans/understanding-usage-and-metering)
- [Integrations overview](https://docs.ospry.ai/guides/automation/integrations-overview)

---

# Integrations overview

Source: https://docs.ospry.ai/guides/automation/integrations-overview

**Who this is for:** Owners and admins can connect; everyone can browse  ·  **Where:** Portal -> Reach -> Outbound Integrations (`/integrations`)

## What this does
Integrations connect your go-to-market stack so OSPRY can send identified profiles where the work happens: a Slack ping, a CRM contact, an email sequence, or any HTTPS endpoint (webhook).

## The directory
The Integrations page is a searchable directory with tabs:

- **All integrations**
- **Active** (shows a count of what you have connected)
- **Sales Automation**
- **Marketing Automation**
- **ABM Advertising** (appears only when ABM is enabled for your account)
- **Other**

Use the search box to filter connectors by name. Each connector is a card; open one to connect or manage it.

## Steps
1. Open **Reach -> Outbound Integrations**.
2. Use the tabs or search to find the tool you want.
3. Click a connector card to open its page, then connect it (see [Connecting an integration](https://docs.ospry.ai/guides/automation/connecting-an-integration)).

## When webhooks are sent
A webhook (or connector) delivery fires for three things:

1. **A visitor is identified.** As soon as OSPRY resolves a new visitor, you get a delivery with what was resolved at that moment.
2. **A visitor's profile is enriched.** When deeper enrichment finishes for that same visitor (phone numbers and personal email, when available and not on a do-not-call list), you get a second delivery with the fuller profile. This only happens for visitors who triggered a delivery in step 1.
3. **An automation rule fires.** When one of your velocity rules crosses its threshold, you get a delivery to that rule's destinations, carrying the visitor's saved profile.

A repeat visit from someone already identified is still recorded in your dashboard for analytics, but it does not trigger another delivery. Each delivery carries an `X-Sight-Event` header naming which of the above triggered it, so your receiving system can tell a first identification apart from an enrichment update or an automation trigger.

## Tips & FAQs
- **Owners and admins only for changes.** Members have read-only access; the page tells them to ask an owner or admin to connect or change a destination.
- **Free vs Pro connectors.** Some connectors are free; others are Pro. A Pro connector you cannot use yet shows an upgrade prompt.
- **No native connector?** Use the **Webhook** connector or a bridge like Zapier, Make, or n8n to deliver profiles to almost anything.
- **ABM Advertising tab.** If your plan includes ABM, an ABM Advertising tab appears. Otherwise you may see an upgrade banner pointing to Pro+. See [ABM advertising](https://docs.ospry.ai/guides/automation/abm-advertising).

## Related
- [Connecting an integration](https://docs.ospry.ai/guides/automation/connecting-an-integration)
- [ABM advertising](https://docs.ospry.ai/guides/automation/abm-advertising)
- [Top leads](https://docs.ospry.ai/guides/tagging/top-leads)
- [Subscription and billing](https://docs.ospry.ai/guides/billing-and-plans/subscription-and-billing)

---

# Connecting an integration

Source: https://docs.ospry.ai/guides/automation/connecting-an-integration

**Who this is for:** Owners and admins  ·  **Where:** Portal -> Reach -> Outbound Integrations -> (a connector) (`/integrations/[kind]`)

## What this does
Walks through connecting a single integration so OSPRY starts delivering identified profiles to it, and shows how to manage delivery scope, health, and the connection afterward.

## Steps
1. Open **Reach -> Outbound Integrations** and click the connector you want.
2. On the connector page, review the badges: its category, direction, and whether it is **Free** or **Pro**. If it is a Pro connector your plan does not include, you will see an upgrade prompt instead of a connect form.
3. In the connect form:
   - **Label** (optional): a name for this connection, for example "Sales team Slack".
   - Fill in the connector's fields (for example an API key, URL, or token). Required fields are shown per connector.
   - **Delivery scope**: choose **All profiles** (every identified visitor) or **Top leads only** (only visitors routed by a Top Leads filter).
4. Click **Connect** (or **Add connection** if you already have one).
5. The connection appears with its status and a delivery health summary.

## Managing a connection
Once connected, each connection card shows:

- **Status**: Enabled or Disabled, plus the delivery scope.
- **Delivery health**: counts for Delivered, Failed, Dead, Pending, and Total, and a recent-failures table when there are problems.
- Actions: **Edit configuration**, **Enable/Disable**, **Disconnect**, and a quick scope switch.

## Webhooks specifically
The **Webhook** connector delivers to any HTTPS endpoint. After you create one, OSPRY shows a **signing secret** once (copy it then; it is not shown in full again). Each delivery is signed; verify the `X-Sight-Signature`, `X-Sight-Idempotency-Key`, and `X-Sight-Event` headers on your endpoint. You can **Rotate secret** later (update your endpoint before the old secret stops being accepted).

## Tips & FAQs
- **Owners and admins only.** Members have read-only access.
- **Top leads only** is a great way to keep a CRM or ad audience focused on your best-fit visitors. Set up Top Leads filters first.
- **Watch the health stats.** Repeated failures or "dead" deliveries usually mean a bad credential or an endpoint that is rejecting requests; open the recent failures table for the response code and error.
- **Disconnecting** stops delivery and removes that connection's history; you will be asked to confirm.

## Related
- [Integrations overview](https://docs.ospry.ai/guides/automation/integrations-overview)
- [Top leads](https://docs.ospry.ai/guides/tagging/top-leads)
- [ABM advertising](https://docs.ospry.ai/guides/automation/abm-advertising)
- [Automations (velocity rules)](https://docs.ospry.ai/guides/automation/automations)

---

# Import, enrich, and sync contacts with HighLevel

Source: https://docs.ospry.ai/guides/automation/highlevel-import-enrich-sync

**Who this is for:** Owners and admins  ·  **Where:** Portal -> Reach -> HighLevel (`/integrations/inbound/highlevel`), Profile -> Contacts (`/contacts`), Profile -> Enrichment (`/enrichment`)

## What this does

Walks through the full recommended loop for a HighLevel account: connect HighLevel, get new contacts in, let enrichment run, and get the enriched data written back to HighLevel automatically. This is the "most effective way" path; the FAQ below covers the CSV and push-API alternatives and when to use them instead.

## The recommended loop

### 1. Connect HighLevel

Open **Reach -> HighLevel** (`/integrations/inbound/highlevel`) and click **Connect a sub-account**. Authorize the HighLevel location OpenID flow. You can connect more than one sub-account.

### 2. Choose what syncs in

On the connected sub-account's **1 - What to sync** panel, pick **All contacts** or **Only selected tags**. Tag scope keeps the roster to a specific segment (for example, only leads tagged `mql`).

### 3. Bring in your contacts

This is the step that decides whether a contact can later be written back to HighLevel, so pick the path that matches where the contact lives today:

- **New contacts already in HighLevel (recommended):** once connected, every contact HighLevel creates matching your scope flows in automatically through the registered webhook - no manual action needed. For contacts that existed in HighLevel *before* you connected, run **3 - Backfill -> Run backfill now** on the same page to pull them in as a one-time pass. Both paths tag the contact `source = highlevel`, which is what makes write-back possible later.
- **New contacts NOT yet in HighLevel:** use **Import contacts (CSV)** on `/contacts` (an `email` column is required; `external_id`, `first_name`, `last_name`, `company`, and `title` are optional), or the contacts push API for a programmatic integration (Zapier, Make, n8n - see the webhook/push recipes on `/integrations/inbound`). These contacts are tagged `source = csv` or `source = api`. They get enriched exactly like HighLevel contacts, but **enriched data on them is never written back to HighLevel**, even if they later get a matching email in HighLevel - write-back only fires for `source = highlevel` contacts (see the FAQ).

### 4. Map custom fields

Back on `/integrations/inbound/highlevel`, the **2 - Map fields** panel lists your HighLevel custom fields. Standard fields (email, first name, last name, company) map automatically. For each custom field, either map it to an existing OSPRY field or create a new one, then set its **Direction**:

- **Inbound** - HighLevel's value flows into OSPRY only.
- **Outbound** - OSPRY's value (including AI-enriched values) flows out to HighLevel.
- **Two-way** - both directions.

Only fields mapped **Outbound** or **Two-way** are eligible for write-back in step 6.

### 5. Enrichment runs automatically

Open **Profile -> Enrichment** (`/enrichment`) once to set your **Ideal Customer Profile** and any custom fields you want the AI to populate - this shapes every enrichment run.

From there, enrichment fires without further action, on two triggers:

- **On arrival** (HighLevel contacts only): a new HighLevel contact with an email address is enriched shortly after it lands, as long as enrichment-on-arrival is enabled for your account, you have budget/wallet balance, and the contact was not just written by OSPRY itself (an echo) or part of a large bulk import (bulk imports are enriched via the ordinary queue instead, to control cost).
- **On any contact ingestion** (CSV, push API, or HighLevel): every newly ingested contact is queued for enrichment when your plan includes the enrichment feature and `enrichment_mode` is `auto` (the default). Setting it to `manual` on the Enrichment Settings tab suppresses auto-enqueue; enrichment then only runs when you trigger it by hand from a contact or person page.
- A contact that was enriched recently is skipped (a freshness window prevents re-enriching the same contact repeatedly).

You do not need to click anything for a HighLevel contact to be enriched under the default settings; the enrichment queue on `/enrichment` shows progress while jobs are in flight.

### 6. Enriched data lands back in HighLevel

Once a HighLevel contact's enrichment finishes, OSPRY automatically pushes the mapped **Outbound**/**Two-way** custom fields back into the matching HighLevel contact - no manual "sync" step required for this path. A few things to know about how the write-back behaves:

- **It is fill-empty, not overwrite.** The arrival write-back only fills a HighLevel custom field that is currently blank; a field you already populated in HighLevel is left untouched. Your contact's email, phone, first name, and last name are never touched by this path either.
- **It is debounced.** Field changes on a contact are coalesced into one HighLevel update roughly once every 60 seconds, so rapid enrichment updates do not spam the HighLevel API.
- **It will not loop.** Every outbound write is marked before it is sent, so the resulting HighLevel webhook for that same change is recognized as an echo and ignored - it will not re-trigger ingestion or another enrichment run.
- You can also push a contact's mapped fields on demand: open a HighLevel-sourced contact's detail page (`/contacts/[id]`) and click **Sync to HighLevel**.

### 7. Verify in HighLevel

Open the contact in HighLevel and check the custom fields you mapped **Outbound**/**Two-way**. A freshly-enriched field that was previously blank should now show the enriched value. If it looks unchanged, confirm the field's Direction on `/integrations/inbound/highlevel` is Outbound or Two-way and that it was blank in HighLevel before enrichment ran.

## Bonus: tracking links for email sends

If you also want to attribute email clicks back to a known contact, build a **tracking link** for the contact (`/contacts/links`, or the per-contact **Create tracking link** action) and use it in your HighLevel email sends. See the recipe card on `/integrations/inbound` under **HighLevel webhook** for the exact merge-field setup.

## Tips & FAQs

- **"Which import path should I use for new contacts?"** If you want the loop to close (enrichment written back into HighLevel), the contact must come from the HighLevel connection itself - either the live webhook (once connected) or a backfill of existing HighLevel contacts. CSV and the push API are for contacts you are bringing into OSPRY that do not need to be synced back to HighLevel.
- **"When does enrichment run?"** Automatically, shortly after a contact arrives, as long as enrichment-on-arrival (HighLevel) or auto-mode (all sources) is enabled on your account and you have not just enriched that contact recently. You can also trigger it manually any time from a contact or person page.
- **"When does enriched data land back in HighLevel?"** Automatically, within about a minute of enrichment finishing, for any field you mapped Outbound or Two-way - and only for contacts whose source is HighLevel. It only fills fields that are currently blank in HighLevel.
- **Owners and admins only for connecting and mapping.** Everyone with contact access can view the roster and enrichment status.
- **Multiple HighLevel connections?** A contact routes its write-back to the sub-account it was ingested from, so multi-location accounts stay correctly scoped.

## Related

- [Connecting an integration](https://docs.ospry.ai/guides/automation/connecting-an-integration)
- [Integrations overview](https://docs.ospry.ai/guides/automation/integrations-overview)

---

# ABM advertising

Source: https://docs.ospry.ai/guides/automation/abm-advertising

**Who this is for:** Owners and admins can set up; everyone can view. Requires the Pro+ plan  ·  **Where:** Portal -> Reach -> Outbound Integrations -> ABM Advertising (`/integrations/abm-advertising`)

## What this does
ABM advertising turns your identified visitors into ad audiences. You pick a saved Top Leads filter, attest to the ad platform's data-rights terms, and OSPRY keeps a hashed, consented audience in sync with your ad account. The five destinations are **LinkedIn Audience**, **Meta Custom Audience**, **Google Customer Match**, **Microsoft Bing Audience**, and **Criteo Audience**. Four are live today; **Google Customer Match** shows as "coming soon" until its data-platform access clears, so the other four ship first.

## Steps
1. Open **Reach -> Outbound Integrations** and select the **ABM Advertising** tab (or go to the ABM Advertising page directly).
2. If your plan is Pro+, you will see your audience-destination entitlement (how many are enabled and your plan limit). If not, you will see an upgrade banner (see below).
3. On a destination card, click **Set up** to open the setup wizard.
4. In the wizard:
   - Pick a saved **Top Leads** filter to define the audience.
   - Attest to the platform's data-rights terms.
   - Confirm to create the audience.
5. OSPRY keeps the hashed, consented audience in sync with your ad account. Configured destinations show their sync status, audience size, and recent activity in the **Configured audiences** section.

## If you are not on Pro+
The page is a visible upsell. You will see a banner explaining that Pro+ adds ad-audience destinations on top of identification, Top Leads, and every CRM and sequencer connector, with an **Upgrade to Pro+** button to the Subscription page.

## Tips & FAQs
- **Pro+ required.** ABM advertising is a Pro+ capability. Lower plans see the upgrade path.
- **Owners and admins only for setup.** Members have read-only access.
- **Built on Top Leads.** Create your Top Leads filter first; the wizard uses it to define who is in the audience.
- **Hashed and consented.** Audiences are pushed as hashed match audiences and only include consented visitors.

## Related
- [Integrations overview](https://docs.ospry.ai/guides/automation/integrations-overview)
- [Top leads](https://docs.ospry.ai/guides/tagging/top-leads)
- [Subscription and billing](https://docs.ospry.ai/guides/billing-and-plans/subscription-and-billing)
- [Company-level visitors](https://docs.ospry.ai/guides/visitors/company-level-visitors)

---

# Documents & prompts: what they are for

Source: https://docs.ospry.ai/guides/automation/persona-documents-and-prompts

# Documents & prompts: what they are for

**Who this is for:** Everyone can view; generating requires the `persona` plan entitlement  ·  **Where:** Portal -> Reach -> Documents (`/documents`) and Portal -> Reach -> Prompts (`/prompts`)

## What this does

Documents turn a resolved person or company into a saved, reusable brief, in seconds, without writing anything yourself. Pick who the document is about, pick a template, and OSPRY generates a markdown document and saves it. Two concrete ways teams use this:

- **Account research brief**: generate a summary of a company before a discovery call, so the whole team walks in prepared.
- **Outreach angle**: generate a person-level brief before a cold email or LinkedIn message, so the message references something real instead of a generic template.

Every generated document is indexed and made retrievable for its subject, so it also grounds other AI features (like HarleyQ) when they answer questions about that person or company later.

**Templates** and **prompts** are the two pieces that shape what a generated document looks like:

- A template's **body** is the markdown shape of the document (its sections and structure).
- A template's **prompt** is the instructions sent to the AI that fills the body in.

Your operator ships a default body and prompt for every template. The Prompts page lets you override either piece, either for your whole organization (owners and admins) or just for yourself, without touching the operator's shared default.

## Steps: generating a document

1. Open **Reach -> Documents**.
2. Click **Generate**.
3. Choose a **subject type** (person or company), then search and select the specific person or company.
4. Choose a **template** that fits what you need.
5. Click **Generate document**. The finished markdown document is saved and appears in your Documents list.


## Steps: overriding a template's body or prompt

1. Open **Reach -> Prompts**.
2. Find the template you want to change and click **Customize**.
3. Under **Your override**, check "Override the template body" and/or "Override the prompt" and edit the field. Leaving a box unchecked keeps that field inherited (it will fall through to the organization override, then the operator default).
4. Click **Save my override**. Owners and admins can also set an organization-wide override in the section below, which applies to every member who has not set their own personal override.
5. The **Templates** table shows, per field, which tier is currently in effect for you: your override, the org override, or the operator default.


## Tips & FAQs

- **Not sure which template to use?** Templates are named for their use case (for example, an account-research template vs. an outreach template). Check with your operator or an admin if you are unsure which one fits.
- **My override is not showing up.** Confirm the "Override" checkbox for that field is checked; an unchecked box always inherits, even if you already typed text into the field.
- **Why can't I edit the organization override?** Only owners, admins, and agency admins can set the organization-wide tier. Everyone can set their own personal override.
- **Where do generated documents go?** They stay on the Documents page and are retrievable for that person or company by other AI features, like HarleyQ.

## Related

- [Contacting support](https://docs.ospry.ai/guides/help/contacting-support)

---

# Exporting your visitor data

Source: https://docs.ospry.ai/guides/exports-and-data/exporting-visitor-data

**Who this is for:** Everyone can open the page; daily export opt-in is owner/admin/agency-admin. Exporting requires a trial or paid plan  ·  **Where:** Portal -> Reach -> Exports (`/exports`)

## What this does
Exports your identified profiles to CSV over a date range. The export runs in the background; when it is ready, OSPRY emails a download link to your notification recipients and lists the file on this page. You can also turn on a daily export of the previous day's new profiles.

## Steps
1. Open **Reach -> Exports** (or click **Export options** from a visitor feed).
2. In **New export**, pick a **Date range** (for example Today, or the past 3, 7, 30, 90, 120, or 365 days).
3. Click **Export profiles**. The export is queued.
4. Watch the **Past exports** table. Each row shows the **File**, **Record count**, **Created at**, and **Status**, with a **Download** button when it is ready.

## Daily CSV export
Turn on **Daily CSV export** to automatically email yesterday's newly identified profiles each day. The panel shows how many recipients are set and links to **Manage recipients** (Account -> Notifications). The daily export stays off until your plan is export-eligible.

## Reading the table
- **Record count** is the number of distinct identified profiles in the file. It excludes per-visit new and repeat visitor events.
- **Status** can be Queued, Building, Ready, Failed, or Expired.
- **Files are retained for one month.** After that they show as Expired and can no longer be downloaded; just run a new export.

## Tips & FAQs
- **Export is a paid capability.** It is available during your trial and on paid plans. On the free tier you will see an upgrade prompt with a **View plans** link instead of the export form.
- **Where the link goes.** The download link is emailed to your notification recipients, set on [Notifications](https://docs.ospry.ai/guides/account-and-team/notifications).
- **Daily opt-in is privileged.** Only owners, admins, and agency admins can toggle the daily export.
- **Background job.** Large exports take a little time; the file appears in the table and the link arrives by email when it is built.

## Related
- [Notifications](https://docs.ospry.ai/guides/account-and-team/notifications)
- [Person-level visitors](https://docs.ospry.ai/guides/visitors/person-level-visitors)
- [Subscription and billing](https://docs.ospry.ai/guides/billing-and-plans/subscription-and-billing)
- [Understanding usage and metering](https://docs.ospry.ai/guides/billing-and-plans/understanding-usage-and-metering)

---

# Contact field reference

Source: https://docs.ospry.ai/guides/exports-and-data/contact-field-reference

**Who this is for:** Anyone who wants to know exactly which fields OSPRY holds about a contact and what each one means  ·  **Where:** Portal -> Profile -> People, Companies and Contacts

**Category:** Exports and data · **Version:** 1.0 · **Date:** 2026-09-04 · **Status:** Active

> GENERATED FILE. DO NOT EDIT BY HAND.
>
> Regenerate with `pnpm --filter @legion/field-registry exec tsx src/generate.ts`.

## What this does

This is the plain-language list of every field OSPRY can show you about a person, a company or a contact. Use it to decide what to map into your CRM, what to expect in an export, and what a webhook body will contain.

## How to read the table

- **key** is the stable name of the field. It never changes once published.
- **label** is what the portal calls it on screen.
- **description** is what the value means.
- **type** is the base type of the value. A field with a fixed list of values is shown simply as `enum`.
- **example** is one representative value.
- **where_it_appears** lists the places the field can show up for you.

Every value is optional unless your plan and settings say otherwise. When OSPRY does not have a value for a field, the field is still named in the payload, with a short reason, so you always know whether a blank means "we looked and there is nothing" or "this was not requested".

## Fields

61 fields.

| key | label | description | type | example | where_it_appears |
|---|---|---|---|---|---|
| company.city | City | The visitor location shown on the company-tier card. | text | Columbus | Profile page, List page, CSV export, Webhook, API |
| company.domain | Company domain | The registrable domain. Half of the row unique key, so the upsert never overwrites it. | text | northwindlogistics.com | Profile page, List page, Search, CSV export, Webhook, API |
| company.employee_count | Company size | The employee-count band as delivered by the resolving provider. | text | 201-500 | Profile page, List page, CSV export, Webhook, API |
| company.est_revenue | Estimated revenue | The revenue band as delivered by the resolving provider. | text | $50M-$100M | Profile page, List page, CSV export, Webhook, API |
| company.first_seen_at | First seen | When this company was first resolved for the tenant. | timestamp | 2026-08-14T13:02:44Z | Profile page, Webhook, API |
| company.id | Company id | The tenant-scoped identifier of the resolved company record. | uuid | 2b7f4c11-9a10-4f2e-8c31-77c4b9d1e004 | Search, Webhook, API |
| company.industry | Industry | The industry band the resolving provider reports for the organization. | text | Transportation and Logistics | Profile page, List page, Search, CSV export, Webhook, API |
| company.last_seen_at | Last seen | When this company was last re-resolved. Refreshed on every upsert conflict. | timestamp | 2026-09-04T18:59:02Z | Profile page, List page, Webhook, API |
| company.linkedin_url | LinkedIn URL | The organization's LinkedIn page. Emitted in the export for a company record. | url | https://www.linkedin.com/company/northwind-logistics | Profile page, List page, CSV export, Webhook, API |
| company.name | Company name | The resolved organization name. The only non-nullable business column on the table. | text | Northwind Logistics | Profile page, List page, Search, CSV export, Webhook, API |
| company.resolved_by_provider | Resolved by | Which vendor resolved this company. A per-ROW insert-only stamp, masked to a tier label on every customer surface. | text | primary | Profile page, Webhook, API |
| company.state | State | The visitor region shown on the company-tier card. | text | OH | Profile page, List page, CSV export, Webhook, API |
| company.website | Website | The company's website URL as delivered, kept alongside the normalized domain. | url | https://northwindlogistics.com | Profile page, List page, Search, Webhook, API |
| contact.company | Company name | The employer name on the roster row. `company` is the canonical inbound key; the HighLevel portal lane still emits `companyName`, which is the recorded three-lane defect this pull request carries forward. | text | Northwind Logistics | Profile page, List page, Webhook, API |
| contact.email | Email | The contact email as ingested, stored case-insensitively. NULL when only the hash is known. | email | dana.whitfield@northwindlogistics.com | Profile page, List page, Search, Webhook, API |
| contact.first_name | First name | The contact's given name as the upstream source supplied it. | text | Dana | Profile page, List page, Search, Webhook, API |
| contact.id | Contact id | The tenant-scoped identifier of the CRM roster contact. | uuid | 4b7c2d19-33a8-42ce-9f01-6d5a8e7b0c34 | Search, Webhook, API |
| contact.last_name | Last name | The contact's family name as the upstream source supplied it. | text | Whitfield | Profile page, List page, Search, Webhook, API |
| contact.phone | Phone | The contact phone number, which is what gives the inbound catalog key `phone` a writable landing instead of a reference-only one. Added by this pull request and carrying no production writer until the inbound landing ships, so it holds no production data today. Never emitted without its DNC state, which travels inside the phone wire shape. | phone | +1 614 555 0142 | Profile page, Webhook, API |
| contact.title | Job title | The contact's job title as the upstream source supplied it. | text | VP of Demand Generation | Profile page, List page, Webhook, API |
| person.business_email | Business email | The person's work email address, stored case-insensitively. | email | dana.whitfield@northwindlogistics.com | Profile page, List page, Search, CSV export, Webhook, API |
| person.city | City | The coarse business location the resolving provider reports. It is not the home address, which is a tier-3 trait. | text | Columbus | Profile page, List page, CSV export, Webhook, API |
| person.company_domain | Company domain | The registrable domain of the person's employer. | text | northwindlogistics.com | Profile page, List page, CSV export, Webhook, API |
| person.company_name | Company name | The denormalized name of the person's employer. | text | Northwind Logistics | Profile page, List page, Search, CSV export, Webhook, API |
| person.employee_count | Company size | The employee-count band of the person's employer, as delivered by the provider. | text | 201-500 | Profile page, List page, CSV export, Webhook, API |
| person.est_revenue | Estimated revenue | The revenue band of the person's employer, as delivered by the provider. | text | $50M-$100M | Profile page, List page, CSV export, Webhook, API |
| person.first_name | First name | The person's given name. | text | Dana | Profile page, List page, Search, Webhook, API |
| person.first_seen_at | First seen | When this person was first resolved for the tenant. | timestamp | 2026-08-14T13:02:44Z | Profile page, Webhook, API |
| person.full_name | Full name | The person's full name, joined from the first and last name at ingest. | text | Dana Whitfield | Profile page, List page, Search, CSV export, Webhook, API |
| person.id | Person id | The tenant-scoped identifier of the resolved person record. | uuid | 9f2c1e4a-7b30-4a51-9d8e-2f6b1c0d5e77 | Search, Webhook, API |
| person.industry | Industry | The industry of the person's employer, as the resolving provider bands it. | text | Transportation and Logistics | Profile page, List page, CSV export, Webhook, API |
| person.last_name | Last name | The person's family name. | text | Whitfield | Profile page, List page, Search, Webhook, API |
| person.last_seen_at | Last seen | When this person was last re-resolved. Refreshed on every provider upsert. | timestamp | 2026-09-04T18:59:02Z | Profile page, List page, Webhook, API |
| person.linkedin_url | LinkedIn URL | The person's LinkedIn profile URL. Half of the row's unique key, so the provider upsert never overwrites it. | url | https://www.linkedin.com/in/danawhitfield | Profile page, List page, CSV export, Webhook, API |
| person.name_source | Name source | Which class of writer last set the name columns. The ADR-031 ladder ranks form above manual above enrichment above provider, and NULL ranks as provider. | enum | provider | Profile page, Webhook, API |
| person.page_hit.path | Path | The normalized path of the page the visitor loaded. | text | /pricing | List page |
| person.page_hit.referrer | Referrer | The referring URL for the page hit. | url | https://www.google.com/ | List page |
| person.page_hit.seen_at | Seen at | When the page hit happened. | timestamp | 2026-09-04T18:59:02Z | List page |
| person.page_hit.utm_campaign | UTM campaign | The campaign name parsed from the page URL. This is the live UTM value the profile export column reads once the export joins the page-hit stream. | text | q3-logistics | List page, CSV export |
| person.page_hit.utm_source | UTM source | The campaign source parsed from the page URL. Part of the only populated UTM set in the product. | text | google | List page |
| person.phone | Phone | A phone number captured from a submitted first-party form. Never emitted without its DNC state, which travels in the phone wire shape. | phone | +1 614 555 0142 | Profile page, Webhook, API |
| person.postal_code | Postal code | The coarse postal code the resolving provider reports for the business location. | text | 43215 | Profile page, Webhook, API |
| person.provider_traits.attributes | Provider traits | The demographic, household and financial trait list the secondary resolver returns, each entry carrying a key, a label, a value and a group. Tier 3: delivered only when the customer enables the sensitive_traits tier on a connector, and shown on the profile page as present or missing. | json | age_range = 45-54 (demographics) | Profile page, Webhook |
| person.provider_traits.emails | Personal emails | The multi-valued personal email list the secondary resolver returns, each entry carrying whether the vendor verified it. The verified set is preferred and both sets are surfaced, deduplicated. | email | d.whitfield@example.com (verified) | Profile page, Webhook, API |
| person.provider_traits.phones | Phones | The multi-valued, DNC-aligned phone list the secondary resolver returns. Each entry carries its number, its kind, its do-not-call flag, whether that flag was actually supplied, and the derived callable value; an entry whose callability is unknown is never asserted callable. | phone | +1 614 555 0142 (mobile, callable) | Profile page, Webhook, API |
| person.resolved_by_provider | Resolved by | Which vendor resolved this person. A per-ROW insert-only stamp, never per-field provenance, and masked to a tier label on every customer surface. | text | secondary | Profile page, Webhook, API |
| person.seniority | Seniority | The seniority band both providers return. Elected by the resolver today and landed by the winner writer this pull request ships. | text | VP | Profile page, CSV export, Webhook, API |
| person.state | State | The coarse business region the resolving provider reports. | text | OH | Profile page, List page, CSV export, Webhook, API |
| person.title | Job title | The person's job title at the resolved company. | text | VP of Demand Generation | Profile page, List page, Search, CSV export, Webhook, API |
| person.trait.age_range | Age range | The demographic age band the secondary resolver returns, written into the attribute list under the demographics group. | text | 45-54 | Profile page, Webhook |
| person.trait.gender | Gender | The demographic gender signal the secondary resolver returns, written into the attribute list under the demographics group. | text | F | Profile page, Webhook |
| person.trait.homeowner | Homeowner | The household home-ownership signal the secondary resolver returns, written into the attribute list under the household group. | text | Yes | Profile page, Webhook |
| person.trait.income_range | Income range | The financial income band the secondary resolver returns, written into the attribute list under the financial group. | text | $150k-$200k | Profile page, Webhook |
| person.trait.married | Married | The household marital-status signal the secondary resolver returns, written into the attribute list under the household group. | text | Married | Profile page, Webhook |
| person.trait.net_worth | Net worth | The financial net-worth band the secondary resolver returns, written into the attribute list under the financial group. | text | $500k-$1M | Profile page, Webhook |
| person.trait.personal_address | Personal address | The home street address the secondary resolver can return. The vendor accepts it as an input identifier but the input record type declares no property for it, so this repository cannot send it, and the trait builder writes no attribute for it either. | text | 118 Maple Court | Profile page, Webhook |
| person.trait.personal_city | Personal city | The home city the secondary resolver can return. Vendor-accepted as an input identifier, unreachable from this repository, and written into no attribute list. | text | Dublin | Profile page, Webhook |
| person.trait.personal_state | Personal state | The home state the secondary resolver can return. Vendor-accepted as an input identifier, unreachable from this repository, and written into no attribute list. | text | OH | Profile page, Webhook |
| person.trait.personal_zip | Personal ZIP | The home postal code the secondary resolver can return. Vendor-accepted as an input identifier, unreachable from this repository, and written into no attribute list. | text | 43017 | Profile page, Webhook |
| person.visit.referrer | Referrer | The referring URL for the visit. The profile export emits the most recent non-null value per profile. | url | https://www.google.com/ | CSV export |
| person.visit.seen_at | Seen at | When the visit happened, as delivered by the provider. The profile export aggregates it into the last-seen and page-count columns. | timestamp | 2026-09-04T18:59:02Z | CSV export |

## Your own custom fields

Fields you define yourself are not in the table above, because their names, labels and types are yours rather than ours. They travel alongside the standard fields in a `custom_fields` list, and each entry carries a `key`, a `label`, a `type`, the `value`, where the value came from, and when it was last filled in.

## Phone numbers and email addresses

Phone numbers and extra email addresses travel as lists rather than single values, because a contact can have more than one of each. A phone entry carries the number, what kind of number it is, whether it is on a do-not-call list, whether that status is known at all, and a single `callable` flag that is true only when the status is known and the number is not on a list. A number whose `callable` is false is never sent.

## Tips and FAQs

- **A blank is never silent.** A field with no value is still named, with one of five short reasons, so two contacts always produce the same shape.
- **The list only grows.** Adding a field advances the dated contract version. Removing or renaming one takes a new version with a 90-day overlap.
- **Machine-readable versions.** The same contract is published as a JSON Schema document you can generate a client from, and as an OpenAPI document.

---

# Subscription and billing

Source: https://docs.ospry.ai/guides/billing-and-plans/subscription-and-billing

**Who this is for:** Owners and admins only (and agency admins)  ·  **Where:** Account menu -> Billing (`/subscription`)

## What this does
The Subscription page shows your plan, your prepaid wallet balance and usage, your invoices, and your payment method. You can change plans, top up your wallet, and update your card without leaving OSPRY.

## What is on the page
- **Plan card**: your current plan and status, the flat monthly access fee, and your tier's per-identified-person and per-enrichment rates.
- **Wallet**: your prepaid balance, recent usage drawn from it, and your auto-top-up setting.
- **Invoices**: your real Stripe invoices (linked as Stripe-hosted PDFs).
- **Plan change**: change your plan (owners and admins).
- **Subscription & payment**: a **Subscribe / start plan** action, a **Top up wallet** action, and an **Update payment method** action. Your card is handled by Stripe through an in-app payment form and never touches OSPRY's servers.
- **How billing works**: a plain-language summary of the model.

## How billing works
OSPRY bills two things, and only two:

1. **A flat monthly access fee for your plan's feature set.** This is the "what you can do" charge. It is decoupled from the number of domains: your plan includes a set number of domains and seats, it is not billed per domain.
2. **Pay-per-use from a prepaid wallet.** You load dollars into a wallet and draw it down as OSPRY identifies and enriches people, at your tier's per-unit rate. This is the "how much you used" charge. Revenue is recognized as the wallet is spent, not when you load it.

The firm, published rates by plan:

| Plan | Flat fee | Per identified person | Per enrichment |
|---|---|---|---|
| Free | $0 forever | n/a | n/a |
| Starter | $100/mo | 36¢ | not included |
| Pro | $150/mo | 33¢ | not included |
| Pro+ | $250/mo | 30¢ | 18¢ |
| Agency | $500/mo | 27¢ | 15¢ |

The per-unit rate drops as the tier rises. There is also a **$1 trial**: 30 days of the full Pro+ feature set with $10 of wallet credit at reduced rates, which rolls into a paid plan unless you cancel (stated at checkout). Repeat visitors and excluded domains are always free. Wallet funds do not expire. No contracts, cancel anytime. Every paid plan includes the consent platform and public API access.

## Steps
1. Open the account menu and choose **Billing**.
2. Review your plan, your tier rates, and your wallet balance.
3. To change plans, use the **Plan change** card (upgrades apply immediately and are prorated; downgrades take effect at the end of the period).
4. To add funds, use **Top up wallet** (minimum top-up $25), or set **auto-top-up** so usage never stalls on a drained wallet.
5. To start a plan or update your card, use **Subscribe / start plan** or **Update payment method**; a secure Stripe payment form opens inline.
6. After paying, you may see a "Payment processing" banner. Your plan activates automatically once the payment settles; the page updates when it does.

## Tips & FAQs
- **Owners and admins only.** The Billing entry in the account menu appears only for privileged roles.
- **Card security.** Your card is tokenized by Stripe; OSPRY never stores card numbers, and there is no redirect to a hosted checkout page.
- **No surprise bills.** Your wallet balance and per-unit rate are always visible. If the wallet runs low, in-flight work completes and is recorded, then new metered work pauses until you top up; nothing is lost.
- **Auto-top-up.** Set "when my balance reaches or falls below X, recharge to Y" so usage does not remain stalled. Setting X to $0 means refill when the wallet is depleted. Concurrent activity converges on one refill attempt; if later usage depletes the new funds, another refill can occur in the same billing period.
- **Promotions.** Operator-issued grants and redeemable coupons post wallet credit that draws down the same way as purchased funds; they are tracked separately so they are never confused with cash.

> **Operator note:** plan names, flat fees, and per-unit rates are defined in the operator catalog (the database is the source of truth and Stripe is a synced mirror), read live onto the Plan card. Always trust the figures shown on your own Subscription page over any number quoted here.

## Related
- [Understanding usage and metering](https://docs.ospry.ai/guides/billing-and-plans/understanding-usage-and-metering)
- [Geo restrictions and consent](https://docs.ospry.ai/guides/billing-and-plans/geo-restrictions)
- [Install the OSPRY pixel](https://docs.ospry.ai/guides/installing-the-script/install-the-sight-pixel)
- [ABM advertising](https://docs.ospry.ai/guides/automation/abm-advertising)

---

# Pending hold vs. charge

Source: https://docs.ospry.ai/guides/billing-and-plans/pending-hold-vs-charge

**Who this is for:** Anyone who sees a pending line on their card after starting pixel install  ·  **Where:** Install page (`/script`)

## What this does

Explains the one billing moment that generates the most support questions: the pending authorization you see on your card after you start pixel install. It is a hold, not a charge. This article is also the published support macro for that question (prd-152f AC-6).

## How the hold works

1. When you start pixel install, we place a hold (a manual-capture authorization) on your card for your commit pack amount. Your card shows a pending line. No money has moved.
2. The hold is captured only when your pixel sends its first visitor from a domain registered on your account. At that moment, and not before, you are charged, and the full amount lands in your wallet as prepaid credit.
3. If your pixel is not live within 7 days, the hold is released automatically. You are charged nothing and your wallet is unchanged. Your bank may keep showing the pending line for a few days after release; that timing belongs to your bank, not to OSPRY.
4. If you re-authorize within 30 days of the release, you keep your locked per-lead rate and the same pack amount in one click. After 30 days, the pack is re-quoted at current pricing.

## Support macro (paste-ready)

> Hi {first_name},
>
> The {amount} you see on your card is a pending authorization, not a charge. We place a hold when you start pixel install, and we only capture it when your pixel sends its first visitor from a domain registered on your account. Until that happens, no money has moved.
>
> If your pixel is not live within 7 days, the hold is released automatically and you are charged nothing. Your bank may display the pending line for a few days after the release; that display window is set by your bank.
>
> If the hold was released and you still want to go live, re-authorize within 30 days from your Install page ({app_origin}/script) and you keep your locked rate and the same pack amount. After 30 days we re-quote at current pricing.
>
> Happy to help if anything on your statement does not match this.

## Tips & FAQs

- **"You charged me!"** Not yet. A pending authorization reserves funds; a capture moves them. We capture only on the first visitor from a registered domain.
- **"The hold disappeared, did I lose my rate?"** No. A released hold keeps your locked rate reserved for 30 days. Re-authorize from the Install page to pick up where you left off.
- **"Can you release the hold early?"** The hold releases itself at day 7 with no install. If you want it gone sooner, contact support and we can cancel the authorization.
- **No cash refunds after capture.** Once the hold is captured into wallet credit, the balance is spendable and does not expire, but it is not refunded as cash.

> **Operator note:** the customer-facing sentence this macro must never contradict lives in code, exactly once: `PACK_HOLD_CHECKOUT_COPY` in `apps/portal/src/lib/server/pricing-v4/pack-hold.ts` ("We place a hold now. You are only charged when your pixel goes live."). The day 0 / day 2 / day 5 / day 7 emails in `pack-hold-comms.ts` use the same story. If the product behavior changes, update those constants first, then this macro.

## Related

- [Subscription and billing](https://docs.ospry.ai/guides/billing-and-plans/subscription-and-billing)
- [Understanding usage and metering](https://docs.ospry.ai/guides/billing-and-plans/understanding-usage-and-metering)
- [Install the OSPRY pixel](https://docs.ospry.ai/guides/installing-the-script/install-the-sight-pixel)
- [Verify the script is working](https://docs.ospry.ai/guides/installing-the-script/verify-the-script-is-working)

---

# Understanding usage and metering

Source: https://docs.ospry.ai/guides/billing-and-plans/understanding-usage-and-metering

**Who this is for:** Everyone (billing details are owner/admin only)  ·  **Where:** Account menu -> Billing (`/subscription`); usage also surfaces on the Dashboard and Intent pages

## What this does
Explains how OSPRY counts what you pay for, so your wallet usage and invoices make sense.

## What counts
- **New person identifications draw from your wallet.** Each new person OSPRY identifies draws your prepaid wallet down at your plan's per-identified-person rate.
- **Enrichments draw from your wallet.** On Pro+ and Agency, each AI enrichment draws the wallet down at your plan's per-enrichment rate.
- **Repeat visitors are free.** Someone you have already identified is not charged again. Repeat visits are not re-recorded unless you turn on repeat-visitor collection on the Script page, and even then they remain free.
- **Excluded domains never count.** Domains on your exclusion list (for example, free email providers or your own internal traffic) are never charged.
- **Loading contacts is free.** Bringing your own contacts in (CSV, the contacts API, or a HighLevel sync) is free and unmetered at any volume; the wallet is only drawn down when a new person is identified or enriched.
- **Domains and seats are plan inclusions, not a per-domain charge.** Your plan includes a set number of domains and seats; you are not billed per active domain.
- **Intent volume is metered for cost attribution.** The behavioral layer's volume is recorded per account so its upstream cost is attributed correctly; it does not draw your wallet down. You can see intent volume this period and all time on the Intent page.

## Where to see your usage
- **Dashboard**: the **identification** tiles show resolved people and companies for the selected range.
- **Subscription page**: your wallet balance, recent draw-downs, and your per-unit rates.
- **Intent page**: intent volume this period and all time.

## Steps
1. Open the account menu and choose **Billing** to see your wallet balance and recent usage.
2. Compare resolved people against your Dashboard tiles for the same period.
3. Turn on **auto-top-up** so identification never pauses when the balance runs low (optionally with a recharge threshold and target).

## Tips & FAQs
- **Why was I charged for a visitor?** Charges are for new person identifications and enrichments. Repeat visits, excluded domains, and loaded contacts are never charged.
- **Keep noise out.** Add internal and free-email domains to the exclusion list on the Script page so they never draw from your wallet.
- **Turning on repeat collection.** This is a strong buying signal, and repeats stay free; it is off by default so your feed stays clean.
- **Plan a ceiling.** Set the auto-top-up threshold and target to keep spend predictable. New metered work normally pauses before an insufficient balance is debited; a bounded negative balance can still appear from chargebacks or an already in-flight grace case, and it remains visible in the wallet ledger.

## Related
- [Subscription and billing](https://docs.ospry.ai/guides/billing-and-plans/subscription-and-billing)
- [Install the OSPRY pixel](https://docs.ospry.ai/guides/installing-the-script/install-the-sight-pixel)
- [Intent signals](https://docs.ospry.ai/guides/automation/intent-signals)
- [The dashboard at a glance](https://docs.ospry.ai/guides/visitors/dashboard-overview)

---

# Geo restrictions and consent

Source: https://docs.ospry.ai/guides/billing-and-plans/geo-restrictions

**Who this is for:** Owners and admins only (it is a compliance control)  ·  **Where:** Account menu -> Geo restrictions (`/account?tab=geo`)

## What this does
Controls where OSPRY is allowed to identify visitors. By default, OSPRY identifies US data subjects only. This page lets you enable company-level identification outside the United States, but only after you confirm you run a consent-management tool.

## Steps
1. Open the account menu and choose **Geo restrictions** (or go to Account settings and open the **Geo restrictions** tab).
2. Read the explanation: US-only is the default and the foundation of the product's legal posture.
3. To allow identification outside the US:
   - First turn on **I run a consent-management tool** (the attestation). You can optionally name the tool (for example, CookieYes).
   - Then turn on **Enable company-level identification outside the United States**.
4. Click **Save restrictions**. The status pill shows **US only** or **Global tier on**.

## The gate
You cannot enable out-of-US identification without confirming the consent tool. If you try, the page tells you to confirm a consent-management tool first. If you later remove the attestation while out-of-US identification is on, OSPRY turns it back off automatically and tells you why.

## Tips & FAQs
- **Owners and admins only.** Members can see the page but cannot change it; the page says only an owner or admin can change geographical restrictions.
- **Why the requirement?** Identifying visitors outside the US is only lawful if your site runs a consent tool that gates the OSPRY script until the visitor accepts. The built-in [consent banner](https://docs.ospry.ai/guides/installing-the-script/consent-banner-setup) is one way to meet this.
- **Compliance checklist.** The Account settings **Compliance** tab tracks related confirmations (consent banner installed, cookie notice added, opt-out link published) and shows recommended notice language and data-subject-request links.
- **It is audited.** Changing this control is recorded for compliance.

## Related
- [Set up your consent banner](https://docs.ospry.ai/guides/installing-the-script/consent-banner-setup)
- [Account settings](https://docs.ospry.ai/guides/account-and-team/account-settings)
- [Intent signals](https://docs.ospry.ai/guides/automation/intent-signals)
- [Subscription and billing](https://docs.ospry.ai/guides/billing-and-plans/subscription-and-billing)

---

# Account settings

Source: https://docs.ospry.ai/guides/account-and-team/account-settings

**Who this is for:** Everyone can view; editing is owner/admin/agency-admin  ·  **Where:** Account menu -> Account settings (`/account`)

## What this does
The Account settings hub is where you manage your company details, team, notifications, geo restrictions, and compliance. It is organized into tabs.

## The tabs
- **General**: company name and timezone, your ICP description, lead enrichment mode, and a guarded Delete account action.
- **Users**: your team members and their roles (see [Managing users](https://docs.ospry.ai/guides/account-and-team/managing-users)).
- **Notifications**: daily CSV opt-in and recipient emails (see [Notifications](https://docs.ospry.ai/guides/account-and-team/notifications)).
- **Geo restrictions**: the US-only vs out-of-US consent control (see [Geo restrictions and consent](https://docs.ospry.ai/guides/billing-and-plans/geo-restrictions)).
- **Compliance**: a setup checklist (consent banner installed, cookie notice added, opt-out link published), with recommended notice language and data-subject-request links.

## General tab in detail
1. Open the account menu and choose **Account settings**.
2. On **General**:
   - Edit **Company name** and **Timezone** (timezone drives dashboard date bucketing and your billing period), then **Save changes**.
   - Add an **ICP description** to describe your ideal customer; this helps fit scoring and insights.
   - Set **Lead enrichment**: "Automatically, on every new lead" or "Manually only". Enrichment must be included in your plan; if not, the panel says so.
   - **Delete account** (privileged, guarded): starts permanent deletion. You must type your company name to confirm. This cannot be undone.

## Tips & FAQs
- **Editing is privileged.** Owners, admins, and agency admins can edit General, Users, and Notifications. Members can view.
- **Geo and Compliance are owner/admin only** to change (they are compliance levers).
- **Deep links.** The account menu links straight to Users, Notifications, and Geo restrictions. The General and Compliance tabs are reachable from the tab bar.
- **Deleting is serious.** The Delete account action only starts the process and requires typing your exact company name; the team then processes it.

## Related
- [Managing users](https://docs.ospry.ai/guides/account-and-team/managing-users)
- [Notifications](https://docs.ospry.ai/guides/account-and-team/notifications)
- [Geo restrictions and consent](https://docs.ospry.ai/guides/billing-and-plans/geo-restrictions)
- [Roles and what each one can see](https://docs.ospry.ai/guides/getting-started/roles-and-visibility)

---

# Managing users

Source: https://docs.ospry.ai/guides/account-and-team/managing-users

**Who this is for:** Owners and admins (and agency admins); members can view  ·  **Where:** Account menu -> Users (`/account?tab=users`)

## What this does
Shows your team and each member's role. The list reflects current memberships in real time.

## What is on the page
A **Team members** table with columns:

- **Member**: the team member (your own row is marked "You").
- **Role**: a colored pill reading Owner, Admin, Member, Agency admin, or Operator.
- **Joined**: when they were added.
- **Actions**: a per-row **Manage** control.

In the panel header there is an **Invite user** button. Today both the **Invite user** button and the per-row **Manage** control are present but **disabled**: inviting members and changing roles are handled through OSPRY user management (the underlying identity provider), not inline on this page. The list itself reflects current memberships in real time.

## Steps
1. Open the account menu and choose **Users** (or open Account settings and select the **Users** tab).
2. Review who is on the account and their roles.
3. Note your own row (marked "You").

## Tips & FAQs
- **Inviting and changing roles is handled by OSPRY user management.** The **Invite user** and per-row **Manage** controls on this page are disabled placeholders; invitations, role changes, and removals are performed through OSPRY user management rather than inline. This list reflects current memberships in real time.
- **Roles explained.** See [Roles and what each one can see](https://docs.ospry.ai/guides/getting-started/roles-and-visibility) for what each role can do.
- **Members** can view this list but cannot change it.

## Related
- [Roles and what each one can see](https://docs.ospry.ai/guides/getting-started/roles-and-visibility)
- [Account settings](https://docs.ospry.ai/guides/account-and-team/account-settings)
- [Notifications](https://docs.ospry.ai/guides/account-and-team/notifications)
- [Signing in](https://docs.ospry.ai/guides/getting-started/signing-in)

---

# Notifications

Source: https://docs.ospry.ai/guides/account-and-team/notifications

**Who this is for:** Owners and admins (and agency admins); members can view  ·  **Where:** Account menu -> Notifications (`/account?tab=notifications`)

## What this does
Controls who gets emailed when OSPRY sends a daily export, and turns the daily export on or off. The recipient list here is the same list that receives export download links.

## Steps
1. Open the account menu and choose **Notifications** (or open Account settings and select the **Notifications** tab).
2. Toggle **Daily CSV export** on to email a daily export of newly identified people to the recipients below.
3. Add recipients: type an email and click **Add** (or press Enter). Remove one with the x on its chip.
4. Click **Save notifications**.

## Tips & FAQs
- **Editing is privileged.** Owners, admins, and agency admins can change notifications. Members can view.
- **One list, two uses.** These recipients receive both the daily export and the download links for manual exports.
- **Valid emails only.** Each address is format-checked; duplicates are removed. There is a cap on the number of recipients.
- **Daily export also lives on the Exports page.** You can toggle the daily export there too; the recipient list is managed here. See [Exporting your visitor data](https://docs.ospry.ai/guides/exports-and-data/exporting-visitor-data).

## Related
- [Exporting your visitor data](https://docs.ospry.ai/guides/exports-and-data/exporting-visitor-data)
- [Account settings](https://docs.ospry.ai/guides/account-and-team/account-settings)
- [Managing users](https://docs.ospry.ai/guides/account-and-team/managing-users)
- [The dashboard at a glance](https://docs.ospry.ai/guides/visitors/dashboard-overview)

---

# The sub-account dashboard

Source: https://docs.ospry.ai/guides/agency/sub-account-dashboard

**Who this is for:** Agency accounts only, agency admins  ·  **Where:** Agency rail -> Sub Accounts -> Sub Account Dashboard (`/subaccounts`)

## What this does
If you run an agency account, this console manages every client account under your agency from one place: pooled usage, billing status, agency economics, and per-client controls. Direct accounts do not have this surface.

## What is on the page
- **Parent header** stat tiles:
  - **Client accounts**: how many client accounts you manage, and your billing cycle.
  - **Pooled wallet**: the agency's prepaid wallet usage drawn across all client sub-accounts this cycle.
  - **Pooled revenue**: retail revenue this cycle.
  - **Next billing**: the next billing date for the period.
- **Add a client account**: create a new sub-account under your agency.
- **Agency economics**: your agency discount and accrued affiliate commission for the period.
- **Per-client table**: one row per client with Client (name and domain), Cycle usage, Plan, Next billing, Subscription status, Script status, and Actions.

## Steps
### Add a client account
1. In **Add a client account**, type the **Client company name**.
2. Click **Add account**. The new sub-account starts on the free plan and trial; you can then install its script and manage it.

### Act as a client
1. In the client's row, click **Act as**. OSPRY opens that client's portal so you can manage it directly.
2. Work in the client's portal as needed, then return to your agency view.

### Disconnect a client
1. In the client's row, click **Disconnect**.
2. Confirm. The client becomes a standalone account; their data is kept.

## Tips & FAQs
- **Agency admins.** This console is for agency accounts and is available to agency admins.
- **Pooled usage and revenue.** The header rolls up usage and retail revenue across all your client accounts for the cycle.
- **Agency economics.** Your discount and affiliate commission accrue from your sub-tree's retail revenue and are recorded as auditable ledger entries; payouts are reported here.
- **Status at a glance.** The Subscription and Script columns tell you which clients are active, trialing, or past due, and whether each client's script is enabled, paused, or not yet installed.

## Related
- [Subscription and billing](https://docs.ospry.ai/guides/billing-and-plans/subscription-and-billing)
- [Install the OSPRY pixel](https://docs.ospry.ai/guides/installing-the-script/install-the-sight-pixel)
- [Roles and what each one can see](https://docs.ospry.ai/guides/getting-started/roles-and-visibility)
- [Contacting support](https://docs.ospry.ai/guides/help/contacting-support)

---

# Set up client rebilling with Stripe Connect

Source: https://docs.ospry.ai/guides/agency/rebilling-stripe-connect-setup

**Who this is for:** Agency accounts only, agency owners and admins  ·  **Where:** Agency rail -> Sub Accounts -> Rebilling (`/subaccounts/rebilling`), linked from a client's `/account/rebilling` page

## What this does

Rebilling lets your agency resell OSPRY to your clients on your own Stripe account instead of putting a card on file for each client. Once you connect your Stripe account, your clients are billed at **retail** on your Stripe, and Legion charges your agency **floor** separately - the difference is your margin.

## What changed from card-on-file

Before rebilling, an agency kept a card on file for each client and Legion billed that card directly. With rebilling:

- **Your Stripe account** is the merchant of record for every connected client. Legion never touches your clients' funds.
- **Legion charges your agency** the floor rate (your wholesale cost) from your agency wallet, plus your monthly plan fee.
- **You charge your clients** the retail rate on your connected Stripe. Retail minus floor is your margin, and you set the markup yourself (between 1.05x and 10.00x).
- A client that visits its own `/account/rebilling` page always sees your agency named as its merchant of record, with the note to contact your agency for billing questions - the client itself never sees your floor rate, your markup, or your Stripe connection.

## Steps

### Connect your Stripe account

1. Open **Sub Accounts -> Rebilling** in the Agency rail (or the "Manage your Stripe connection" / "Connect your Stripe" link on a client's `/account/rebilling` page).
2. Under **Your Stripe connection**, click **Connect with Stripe (recommended)** and complete Stripe's onboarding.
3. Once connected, the connection status shows **active**. Every eligible client sub-account under your agency starts billing through this connection automatically - there is nothing to configure per client.

### Or connect a restricted key

1. If you already manage a Stripe account outside of Stripe Connect, open the **Or paste a restricted key (rk_...)** section instead.
2. Paste a Stripe restricted key with the required charge/customer permissions and click **Connect key**.
3. Your key is encrypted at rest and never shown again. Use **Rotate key** to replace it later, or **Disconnect** to remove the connection.

### Set your markup

1. On the same Rebilling page, find **Your markup (per meter)**.
2. For each metered feature (resolution, enrichment, first-party resolution), enter a markup multiplier and click **Save**. Retail and your margin update immediately.

### Fund your agency wallet

1. Legion draws your agency's **floor** cost from your Legion wallet, separate from what you charge clients.
2. Under **Your Legion wallet (floor funding)**, check your balance and turn on auto-top-up so client usage never stalls on a drained wallet.

## Tips & FAQs

- **Nothing to do per client.** Once your Stripe connection is active, every current and future client sub-account bills through it automatically at your set markup.
- **Not connected yet?** A client's `/account/rebilling` page still names your agency as the eventual merchant of record and links back here so you can finish the connection at any time.
- **Clients never see your economics.** Your floor rate, markup, and margin are visible only to your agency; a client's own billing page only ever shows what it was charged and that your agency is its merchant of record.
- **Restricted key vs. Stripe Connect.** Stripe Connect is the recommended path for most agencies. A restricted key is useful if you already have an established Stripe account you want to keep using as-is.

## Related

- [The sub-account dashboard](https://docs.ospry.ai/guides/agency/sub-account-dashboard)
- [Subscription and billing](https://docs.ospry.ai/guides/billing-and-plans/subscription-and-billing)
- [Contacting support](https://docs.ospry.ai/guides/help/contacting-support)

---

# Contacting support

Source: https://docs.ospry.ai/guides/help/contacting-support

**Who this is for:** Everyone on the account  ·  **Where:** Portal -> Help and support -> Support

## What this does
Points you to the fastest way to get help with OSPRY.

## How to get help
1. **Live chat.** When chat is enabled for your portal, a chat widget (powered by Tawk.to) appears in the corner of the screen. Open it to message the team; your name and account are passed through automatically so we have context. This help center is hosted on the same Tawk.to knowledge base.
2. **Self-serve.** Browse this help center for step-by-step answers.
3. A dedicated in-app **Support** page is on the way; until it ships, use the chat widget or the self-serve guides.

## Tips & FAQs
- **Before you reach out,** it helps to note: your company name, the page or feature involved, what you expected, and what happened. Screenshots speed things up.
- **Script not identifying anyone?** First confirm the snippet is installed and verified on the right domain. See [Verify the script is working](https://docs.ospry.ai/guides/installing-the-script/verify-the-script-is-working).
- **Billing question?** Owners and admins can review the plan, usage, and invoices on the Billing page. See [Subscription and billing](https://docs.ospry.ai/guides/billing-and-plans/subscription-and-billing).
- **Account access issue?** If you cannot claim or sign in, see [Claiming your account](https://docs.ospry.ai/guides/getting-started/claiming-your-account) and [Signing in](https://docs.ospry.ai/guides/getting-started/signing-in).

> **Operator note:** the live channel is the Tawk.to chat widget, which an operator injects into the portal through the script-injection settings; it only appears for viewers whose role and plan match the script's audience. The in-app **Support** sidebar entry is marked "coming soon" and is not yet a live route, and there is no dedicated support email in the product. Confirm the widget is configured (and add a support email here if one is later published).

## Related
- [Verify the script is working](https://docs.ospry.ai/guides/installing-the-script/verify-the-script-is-working)
- [Subscription and billing](https://docs.ospry.ai/guides/billing-and-plans/subscription-and-billing)
- [A tour of the portal](https://docs.ospry.ai/guides/getting-started/portal-tour)

---

# Overview

Source: https://docs.ospry.ai/api/v1

Version 2026-09-04. OpenAPI 3.1.0.

**Servers**
- `https://{customerPublicId}.lgnapi.com`: Canonical edge host. Serves the bearer push (POST /v1/contacts), the generic inbound webhook (POST /v1/contacts/{sourceId}) and the HighLevel webhook (POST /v1/contacts/highlevel). Not used for GET /api/v1/schema or POST /api/contacts/links, which the origin serves directly.
- `https://app.ospry.ai`: The portal origin. Canonical for GET /api/v1/schema and POST /api/contacts/links. Deprecated dual-serve fallback for the push and webhook paths (prd-045-03), reachable there under different routes: POST /api/contacts mirrors POST /v1/contacts, and POST /api/contacts/webhook/{sourceId} mirrors POST /v1/contacts/{sourceId}. The HighLevel webhook is served by the edge host only. The origin push fallback accepts a portal session in place of an API key. It may answer 429 with Retry-After. Either origin fallback may answer 200 with a synchronous result instead of 202 when the durable queue is unavailable. The origin webhook fallback applies no rate limit.

**Security schemes**
- `ApiKeyAuthBearer` (http, bearer): A tenant API key (`lsk_`-prefixed) presented as `Authorization: Bearer <key>`. A present-but-wrong or present-but-blank key answers 401 and never falls back to any other credential. Equivalent to ApiKeyAuthHeader; present exactly one of the two forms. The key is a secret: send it only from server-side code, never from a browser or a mobile app bundle.
- `ApiKeyAuthHeader` (apiKey, in header, x-api-key): A tenant API key presented as the `x-api-key` header. Equivalent to ApiKeyAuthBearer; present exactly one of the two forms.
- `SourceTokenHeader` (apiKey, in header, x-webhook-token): The per-source inbound webhook token. This is the preferred form: use it whenever the sending platform can set a custom header. Equivalent to SourceTokenQuery; when both are present, this header is the one checked.
- `SourceTokenQuery` (apiKey, in query, token): The per-source inbound webhook token as a query parameter. A fallback ONLY for platforms that cannot set a custom header: a URL that carries a token is routinely written to access, proxy and CDN logs, to browser history, and to the sending platform's own run history. Prefer SourceTokenHeader, never paste a token-bearing URL into a shared document or ticket, and rotate the token from the portal's Inbound Connections screen if such a URL is exposed. Equivalent to SourceTokenHeader, which takes precedence when both are present.

## Contact

Schema `Contact` (object)

The shared contact object. It is the webhook body's subject verbatim and the read contract's single-resource body. Every key of a caller's key set K appears exactly once, either here as a value or in missing as a reason, never both and never neither.

**Properties**
- `company` (object, required): The firmographic fields.
  - `domain` (string | null): The registrable domain of the person's employer.
  - `employee_count` (string | null): The employee-count band of the person's employer, as delivered by the provider.
  - `est_revenue` (string | null): The revenue band of the person's employer, as delivered by the provider.
  - `industry` (string | null): The industry of the person's employer, as the resolving provider bands it.
  - `linkedin_url` (string | null): The organization's LinkedIn page. Emitted in the export for a company record.
  - `name` (string | null): The denormalized name of the person's employer.
  - `website` (string | null): The company's website URL as delivered, kept alongside the normalized domain.
- `contract_version` (const "2026-09-04", required): The dated contract version.
- `custom_fields` (array of object, required): The tenant's own custom fields. Tier 1, always present (parent OD-27).
- `handles` (object, required): Email and phone handles. emails[] and phones[] are tier 2.
  - `business_email` (string | null): The person's work email address, stored case-insensitively.
  - `emails` (array of object): Tier 2. Empty when the tier is not enabled.
  - `phones` (array of object): Tier 2. Empty when the tier is not enabled.
- `id` (string, required): The tenant-scoped identifier of the resolved person record.
- `identity` (object, required): The subject identity fields.
  - `first_name` (string | null): The person's given name.
  - `full_name` (string | null): The person's full name, joined from the first and last name at ingest.
  - `last_name` (string | null): The person's family name.
  - `linkedin_url` (string | null): The person's LinkedIn profile URL. Half of the row's unique key, so the provider upsert never overwrites it.
  - `seniority` (string | null): The seniority band both providers return. Elected by the resolver today and landed by the winner writer this pull request ships.
  - `title` (string | null): The person's job title at the resolved company.
- `links` (object, required): Absolute links to this subject.
  - `portal` (string | null): The portal page for this subject.
  - `self` (string | null): The read-contract URL for this subject.
- `location` (object, required): The subject location fields.
  - `city` (string | null): The coarse business location the resolving provider reports. It is not the home address, which is a tier-3 trait.
  - `postal_code` (string | null): The coarse postal code the resolving provider reports for the business location.
  - `state` (string | null): The coarse business region the resolving provider reports.
- `missing` (object, required): Every key in this caller's key set K that carries no value, mapped to one of the five closed reasons.
- `object` (const "contact", required): Always the literal "contact".
- `provenance` (object, required): How this subject was resolved and when it was seen.
  - `first_seen_at` (string): When this person was first resolved for the tenant.
  - `last_seen_at` (string): When this person was last re-resolved. Refreshed on every provider upsert.
  - `name_source` (enum "enrichment", "form", "manual", "provider", null): Which class of writer last set the name columns. The ADR-031 ladder ranks form above manual above enrichment above provider, and NULL ranks as provider.
  - `resolved_by` (string): Which vendor resolved this person. A per-ROW insert-only stamp, never per-field provenance, and masked to a tier label on every customer surface.
- `subject_type` (enum "company_profile", "contact", "person_profile", required): Which catalogued subject this object describes.
- `traits` (array of object, required): Tier 3 (sensitive_traits): the household, demographic and financial traits. The tier is available to every account and is off by default on each connector, so this array carries values only once the customer enables it on that connector. Until then it is empty and every tier-3 key is named in missing with the reason withheld_tier.

## ContactList

Schema `ContactList` (object)

The read contract list body. Declared now and produced by the follow-on (parent NG15), so push and pull cannot diverge before pull is built.

**Properties**
- `contract_version` (const "2026-09-04", required)
- `data` (array of Contact, required)
- `has_more` (boolean, required)
- `next_cursor` (string | null): An opaque keyset cursor.
- `object` (const "list", required)

## FieldPolicy

Schema `FieldPolicy` (object)

The per-delivery accounting of what the caller received and what it did not. permitted_tiers is what the tenant may enable; enabled_tiers is what this integration has on.

**Properties**
- `enabled_tiers` (array of enum 1, 2, 3, required)
- `included` (integer, required)
- `missing` (integer, required)
- `missing_reason` (object, required): A count per reason. Every key is one of the five closed reasons.
- `permitted_tiers` (array of enum 1, 2, 3, required)
- `withheld_tiers` (array of enum "contact_handles", "sensitive_traits", required)

## WebhookEventV2

Schema `WebhookEventV2` (object)

The whole opt-in v2 outbound body. Its subject is a Contact; a whole body deliberately does NOT validate against Contact, because the envelope carries nine keys the subject does not.

**Properties**
- `classification` (string): Omitted when empty. The velocity-rule label.
- `contract_version` (const "2026-09-04", required)
- `emitted_at` (string, required)
- `event` (const "visitor.identified", required)
- `field_policy` (FieldPolicy): The per-delivery accounting of what the caller received and what it did not. permitted_tiers is what the tenant may enable; enabled_tiers is what this integration has on.
  - `enabled_tiers` (array of enum 1, 2, 3, required)
  - `included` (integer, required)
  - `missing` (integer, required)
  - `missing_reason` (object, required): A count per reason. Every key is one of the five closed reasons.
  - `permitted_tiers` (array of enum 1, 2, 3, required)
  - `withheld_tiers` (array of enum "contact_handles", "sensitive_traits", required)
- `id` (string, required): The visit_event id, and the X-Sight-Idempotency-Key value.
- `is_repeat` (boolean, required)
- `served_from` (string): Omitted when empty. "cache" on a serve-local of a recognized return.
- `subject` (Contact, required): The shared contact object. It is the webhook body's subject verbatim and the read contract's single-resource body. Every key of a caller's key set K appears exactly once, either here as a value or in missing as a reason, never both and never neither.
  - `company` (object, required): The firmographic fields.
  - `contract_version` (const "2026-09-04", required): The dated contract version.
  - `custom_fields` (array of object, required): The tenant's own custom fields. Tier 1, always present (parent OD-27).
  - `handles` (object, required): Email and phone handles. emails[] and phones[] are tier 2.
  - `id` (string, required): The tenant-scoped identifier of the resolved person record.
  - `identity` (object, required): The subject identity fields.
  - `links` (object, required): Absolute links to this subject.
  - `location` (object, required): The subject location fields.
  - `missing` (object, required): Every key in this caller's key set K that carries no value, mapped to one of the five closed reasons.
  - `object` (const "contact", required): Always the literal "contact".
  - `provenance` (object, required): How this subject was resolved and when it was seen.
  - `subject_type` (enum "company_profile", "contact", "person_profile", required): Which catalogued subject this object describes.
  - `traits` (array of object, required): Tier 3 (sensitive_traits): the household, demographic and financial traits. The tier is available to every account and is off by default on each connector, so this array carries values only once the customer enables it on that connector. Until then it is empty and every tier-3 key is named in missing with the reason withheld_tier.
- `tier` (enum "company", "person", required)
- `visit` (object): The visit that produced this event.
  - `captured_url` (string | null)
  - `domain_id` (string | null)
  - `referrer` (string | null)
  - `seen_at` (string | null)
  - `visitor_id` (string | null)

---

# Contacts

Source: https://docs.ospry.ai/api/v1/contacts

The tenant-facing contact push, inbound webhook and link-minting operations.

## mintContactLink

`POST /api/contacts/links`: Mint a token and a tagged link for one contact.

For platforms that generate the link at send time. Names the contact by contactId, or both source and externalId (contactId takes precedence if both are sent). Requires the `contacts:links:write` scope, which is NOT granted by default to a new key (a key carrying only contacts:write is 403 here). A same-origin portal session is also accepted in place of a key; that first-party path is out of scope for this document.

**Authentication:** ApiKeyAuthBearer or ApiKeyAuthHeader

**Request body** (application/json, required)

Fields:
- `contactId` (string): The contact's id, a UUID.
- `destinationUrl` (string, required): Must resolve to a domain this tenant has authorized.
- `expSeconds` (integer): Only meaningful for type=signed.
- `externalId` (string)
- `source` (string)
- `type` (enum "opaque", "signed")

**Responses**
- Response `200`: The minted token and its tagged link.
- Response `400`: Malformed JSON, a validation failure (issues carries the validation issues), an unauthorized destination host, or an invalid destination URL.
- Response `401`: No key and no portal session, or a present key that fails validation.
- Response `403`: The key is valid but lacks the contacts:links:write scope (not granted by default).
- Response `404`: No contact matches the given contactId, or the (source, externalId) pair.
- Response `429`: A per-customer fixed-window limit (120/min), or on the machine-auth path a per-key per-minute or daily limit; honor Retry-After.
- Response `500`: An unclassified mint failure.
- Response `503`: type=signed was requested but signed links are temporarily unavailable.

## pushContacts

`POST /v1/contacts`: Push a batch of contacts (the canonical bearer-authenticated ingest).

Idempotent per account on (source, external_id): a re-pushed batch refreshes the existing rows rather than duplicating them. Requires the `contacts:write` scope. API access is a plan feature; keys are issued, rotated and revoked from the portal's Inbound Connections screen.

**Authentication:** ApiKeyAuthBearer or ApiKeyAuthHeader

**Request body** (application/json, required): Accepts the narrow {contacts:[...]} shape. At most 10000 records per call (a larger batch is 413), and the whole body is capped at 8388608 bytes. A nested {events:[{resolution:{...}}]} shape some inbound connectors send is accepted only by the deprecated portal-origin fallback for this operation, never by this host; a body with no contacts array here is a 400.

Fields:
- `contacts` (array of object, required)

**Responses**
- Response `202`: 202 Accepted: the batch is durably queued and not yet upserted. Ingestion completes shortly after.
- Response `400`: Malformed JSON, or a body with no contacts array.
- Response `401`: The presented key is missing, unknown, malformed, expired, or past its revocation grace. The response never reveals which.
- Response `403`: The key is not permitted to perform this operation (for example, it lacks the contacts:write scope).
- Response `404`: The {customerPublicId} subdomain is unknown or inactive.
- Response `413`: More than 10000 records in one call, or a body over 8388608 bytes.
- Response `429`: Too many requests for this API key: more than 120 in a 60-second window, or more than 50,000 in a 24-hour window. Wait the number of seconds in Retry-After, then retry: 60 for the short window, or the seconds left in the 24-hour window. Requests that fail authentication or routing do not count toward the limit.
- Response `503`: The queue producer failed to accept the message. Retry is safe: the eventual upsert is idempotent.

## pushHighLevelContact

`POST /v1/contacts/highlevel`: The HighLevel native inbound webhook.

Authenticated by the connection's per-source token, sent as the ?token= query parameter of the webhook URL the portal shows (or the x-webhook-token header) and constant-time compared against the hash stored for the body's HighLevel location. A present token that does not match answers 401 in every case. The {customerPublicId} subdomain selects the account, and the body locationId (or location_id) must be an active HighLevel location connected to that account. Transition: until every connection has moved to the tokenized URL, a call that carries no token at all is still accepted and flagged to OSPRY; after the cutover it answers 401, so re-paste the webhook URL from the portal now. The HighLevel contact_id becomes external_id (source=highlevel), matching the idempotency anchor POST /v1/contacts and POST /v1/contacts/{sourceId} use.

**Authentication:** SourceTokenHeader or SourceTokenQuery

**Request body** (application/json, required)

Fields:
- `company` (string | null)
- `companyName` (string | null)
- `contactId` (string)
- `contact_id` (string)
- `email` (string | null)
- `firstName` (string | null)
- `first_name` (string | null)
- `id` (string): A HighLevel contact id, used as external_id when contactId/contact_id are absent.
- `lastName` (string | null)
- `last_name` (string | null)
- `locationId` (string)
- `location_id` (string)
- `title` (string | null)

**Responses**
- Response `202`: 202 Accepted: the batch is durably queued and not yet upserted. Ingestion completes shortly after.
- Response `400`: Malformed JSON, or the body carries no contact id.
- Response `401`: A token was presented and does not match the stored hash for the body's HighLevel location (including a token that belongs to another connection or account), or, after the tokenized-URL cutover, no token was presented. The response never reveals which.
- Response `404`: The {customerPublicId} subdomain is unknown or inactive, the account has no active HighLevel connection, or the body locationId is missing or is not an active HighLevel location of this account. Answered identically to an unknown subdomain, revealing nothing about whether HighLevel is configured.
- Response `413`: A body over 8388608 bytes.
- Response `429`: Too many requests for this HighLevel location: more than 120 in a 60-second window, or more than 50,000 in a 24-hour window. Wait the number of seconds in Retry-After, then retry: 60 for the short window, or the seconds left in the 24-hour window. Requests that fail authentication or routing do not count toward the limit.
- Response `503`: The queue producer failed to accept the message. Retry is safe: the eventual upsert is idempotent.

## pushContactsBySource

`POST /v1/contacts/{sourceId}`: The generic per-source inbound webhook (Zapier, Make, n8n, a custom script).

Resolves the tenant by {sourceId} plus the presented per-source token, constant-time compared against the stored hash. Accepts the same {contacts:[...]} body as POST /v1/contacts; each record is mapped through this source's field mappings.

**Authentication:** SourceTokenHeader or SourceTokenQuery

**Parameters**
- Parameter `sourceId` (path, string, required): The per-source id of the connection, as shown in its webhook URL in the portal. Selects which per-source token and field-mapping set authenticate and shape this call.

**Request body** (application/json, required): Accepts the narrow {contacts:[...]} shape. At most 10000 records per call (a larger batch is 413), and the whole body is capped at 8388608 bytes. A nested {events:[{resolution:{...}}]} shape some inbound connectors send is accepted only by the deprecated portal-origin fallback for this operation, never by this host; a body with no contacts array here is a 400.

Fields:
- `contacts` (array of object, required)

**Responses**
- Response `202`: 202 Accepted: the batch is durably queued and not yet upserted. Ingestion completes shortly after.
- Response `400`: Malformed JSON, or a body with no contacts array.
- Response `401`: The source id is unknown, inactive, not a webhook-type source, or the presented token does not match its stored hash. The response never reveals which.
- Response `403`: Edge only: the source belongs to a different tenant than the {customerPublicId} subdomain.
- Response `404`: The {customerPublicId} subdomain is unknown or inactive.
- Response `413`: More than 10000 records in one call, or a body over 8388608 bytes.
- Response `429`: Too many requests for this source: more than 120 in a 60-second window, or more than 50,000 in a 24-hour window. Wait the number of seconds in Retry-After, then retry: 60 for the short window, or the seconds left in the 24-hour window. Requests that fail authentication or routing do not count toward the limit.
- Response `503`: The queue producer failed to accept the message. Retry is safe: the eventual upsert is idempotent.

---

# Schema

Source: https://docs.ospry.ai/api/v1/schema

The machine-readable field contract.

## getContractSchema

`GET /api/v1/schema`: Fetch the JSON Schema 2020-12 contract document.

Unauthenticated and ungated: it carries the contract, never tenant data. It performs no tenant resolution and no database read.

**Responses**
- Response `200`: The contract document. The handler has no failure branch: it performs no tenant resolution, calls no database, and always answers 200 with the committed schema bytes.

---

# Webhooks

Source: https://docs.ospry.ai/api/v1/webhooks

## visitorIdentifiedV2

Webhook `visitor.identified` (POST): The opt-in v2 outbound webhook body.

Sent to the customer endpoint configured on an integration whose payload_version selects v2. Signed with X-Sight-Signature over the exact bytes, keyed for idempotency on X-Sight-Idempotency-Key.

**Request body** (application/json, required)

Fields:
- `classification` (string): Omitted when empty. The velocity-rule label.
- `contract_version` (const "2026-09-04", required)
- `emitted_at` (string, required)
- `event` (const "visitor.identified", required)
- `field_policy` (FieldPolicy): The per-delivery accounting of what the caller received and what it did not. permitted_tiers is what the tenant may enable; enabled_tiers is what this integration has on.
  - `enabled_tiers` (array of enum 1, 2, 3, required)
  - `included` (integer, required)
  - `missing` (integer, required)
  - `missing_reason` (object, required): A count per reason. Every key is one of the five closed reasons.
  - `permitted_tiers` (array of enum 1, 2, 3, required)
  - `withheld_tiers` (array of enum "contact_handles", "sensitive_traits", required)
- `id` (string, required): The visit_event id, and the X-Sight-Idempotency-Key value.
- `is_repeat` (boolean, required)
- `served_from` (string): Omitted when empty. "cache" on a serve-local of a recognized return.
- `subject` (Contact, required): The shared contact object. It is the webhook body's subject verbatim and the read contract's single-resource body. Every key of a caller's key set K appears exactly once, either here as a value or in missing as a reason, never both and never neither.
  - `company` (object, required): The firmographic fields.
  - `contract_version` (const "2026-09-04", required): The dated contract version.
  - `custom_fields` (array of object, required): The tenant's own custom fields. Tier 1, always present (parent OD-27).
  - `handles` (object, required): Email and phone handles. emails[] and phones[] are tier 2.
  - `id` (string, required): The tenant-scoped identifier of the resolved person record.
  - `identity` (object, required): The subject identity fields.
  - `links` (object, required): Absolute links to this subject.
  - `location` (object, required): The subject location fields.
  - `missing` (object, required): Every key in this caller's key set K that carries no value, mapped to one of the five closed reasons.
  - `object` (const "contact", required): Always the literal "contact".
  - `provenance` (object, required): How this subject was resolved and when it was seen.
  - `subject_type` (enum "company_profile", "contact", "person_profile", required): Which catalogued subject this object describes.
  - `traits` (array of object, required): Tier 3 (sensitive_traits): the household, demographic and financial traits. The tier is available to every account and is off by default on each connector, so this array carries values only once the customer enables it on that connector. Until then it is empty and every tier-3 key is named in missing with the reason withheld_tier.
- `tier` (enum "company", "person", required)
- `visit` (object): The visit that produced this event.
  - `captured_url` (string | null)
  - `domain_id` (string | null)
  - `referrer` (string | null)
  - `seen_at` (string | null)
  - `visitor_id` (string | null)

**Responses**
- Response `200`: The receiver accepted the delivery.