OSPRY Docs

Automation

Import, enrich, and sync contacts with HighLevel

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.

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.

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.