Elevale connects to HighLevel-family CRM platforms through three branded integrations that share the same API backend: The Momentum Engine, LeadConnector, and HighLevel CRM. Each uses OAuth (not a personal access token). After you connect, you can create connected KPIs that sync contacts, opportunities, conversations, appointments, and payment metrics on a schedule you choose.
Which integration should I use?
The Momentum Engine: for Momentum Engine whitelabel accounts. OAuth opens on marketplace.leadconnectorhq.com.
LeadConnector: for LeadConnector-branded sub-accounts on the same HighLevel API.
HighLevel CRM: for standard GoHighLevel accounts. OAuth opens on marketplace.gohighlevel.com.
All three use the same OAuth credentials on the Elevale platform and the same sync engine (
highlevel_kpi_sync
). Pick the brand that matches where you installed the Elevale app.
Before you connect
You need a HighLevel location (sub-account) with data you want to measure.
Use a user who can authorise the Elevale marketplace app for that location.
Elevale requests read-only scopes: contacts, conversations, opportunities, calendars, locations, and payment transactions/subscriptions.
Pop-ups must be allowed, OAuth opens in the same window for HighLevel providers.
Connect OAuth
Open Workspace Settings → Integrations and connect the correct brand (Momentum Engine, LeadConnector, or HighLevel CRM).
Complete the provider consent screen and select the location (sub-account) to link.
Elevale stores the location ID on the connection and uses it for every API call.
If location ID was missing on an older connection, the first sync resolves it from the HighLevel locations API and saves it.
The connection appears under Connected integrations when active.
How KPI sync works
When you save or manually resync a connected KPI, Elevale calls the highlevel_kpi_sync edge function with the KPI ID and workspace context.
The function loads the KPI, OAuth connection, and data-point configuration from oauth_provider_endpoints.
Your access token is decrypted server-side and sent to HighLevel at services.leadconnectorhq.com with API version header 2021-07-28.
The returned value is written to kpi_history and the KPI current field is updated. Connection sync status is updated on success or failure.
Scheduled syncs use the same path with a service-role context.
Opportunity metrics, status logic
Most opportunity KPIs use GET /opportunities/search with location_id (snake_case) as a query parameter. HighLevel status values are open, won, lost, and abandoned. Elevale maps legacy config value active to open automatically.
All Opportunities: total count across every status (no status filter).
Live Opportunities / Open Deals (Live): count where status = open.
Won Deals: count where status = won.
Lost Deals: count where status = lost.
Abandoned Opportunities: count where status = abandoned.
Win Rate: won ÷ (won + lost), expressed as a percentage.
Loss Rate: lost ÷ (won + lost), expressed as a percentage.
Abandonment Rate: abandoned ÷ all opportunities, expressed as a percentage.
Opportunity value metrics
Pipeline Value / Open Pipeline Value: sum of monetaryValue for open opportunities.
Won Opportunity Value: sum of monetaryValue for won opportunities.
Lost Opportunity Value: sum of monetaryValue for lost opportunities.
Abandoned Opportunity Value: sum of monetaryValue for abandoned opportunities.
Average Deal Value: average monetaryValue across opportunities returned in the API response.
Value sums paginate through opportunity pages (100 per page) and add monetaryValue from each record.
Lost opportunities by reason
When you select a HighLevel connection in the KPI form, Elevale loads your account's configured lost reasons from the HighLevel API.
Each lost reason appears as an extra data point labelled Lost: {reason name} (for example Lost: Price too high).
These use endpoint keys of the form lost_reason_{id} and count lost opportunities tagged with that reason.
If the HighLevel API supports server-side lost_reason_id filtering, Elevale uses meta.total for a fast count. Otherwise it paginates lost opportunities and matches lostReasonId client-side.
Lost reasons are specific to your HighLevel location, different sub-accounts may show different reason lists.
Contact, conversation, and appointment metrics
Total Contacts: GET /contacts/ with locationId; count uses meta.total or the contacts array.
Active Contacts: intended to count contacts with recent activity. The HighLevel list endpoint does not accept a hasRecentActivity filter today, so sync returns total contact count from the first page/meta until a search-based filter is added.
New Contacts This Month: contact count; date-filtered contact queries are not yet wired to the search API.
Lead Conversion Rate: percentage metric; requires contact-level fields that may not be present on basic list responses.
Total Conversations, SMS Sent, Email Sent, Response Rate: conversation endpoints; date filters apply only when explicitly configured.
Total Appointments, Appointment Show Rate, No-Show Rate: calendar appointment endpoints with date range support.
Payment and revenue metrics
Total Revenue, Monthly Revenue, Average Transaction Value: payment transaction endpoints.
Subscription Revenue / One-Time Payment Revenue: filtered transaction sums by type.
Transaction endpoints support startDate/endDate when the data point declares a date_filter in configuration.
Data point categories
All HighLevel-family KPI data points are categorised as Marketing in the KPI form, regardless of the underlying endpoint category stored in the database.
This keeps CRM and pipeline metrics grouped with other growth and acquisition KPIs in your workspace.
Known limitations
Edge function timeout (150 seconds): value-sum syncs paginate opportunities. Pagination is capped at 20 pages (2,000 opportunities). Very large pipelines may return a partial sum if more than 2,000 open records exist.
Opportunity pagination safety: sync stops when meta.total is reached, when a page returns fewer than 100 rows, or when the API repeats a pagination cursor.
Count vs sum accuracy: count metrics (live deals, won deals, etc.) use meta.total from a single API call and are accurate for totals reported by HighLevel. Sum metrics require fetching each opportunity row.
Active Contacts filter: hasRecentActivity is configured but not yet sent to HighLevel; the metric may reflect total contacts rather than recently active contacts.
Contact date filters: GET /contacts/ rejects startDate/endDate query parameters (422). Date-filtered contact KPIs need the contacts search API in a future update.
Duplicate KPI titles: creating a KPI with the same title as an existing workspace KPI may return HTTP 409; use a unique title.
Token refresh: if the access token expires and refresh fails, reconnect the integration from Workspace Settings.
One connection per brand: each workspace connection is tied to one location. Multi-location reporting requires separate connections or manual KPIs per location.
Create connected KPIs
On OKRs & KPIs, create or edit a KPI and choose Connected as the type.
Select your Momentum Engine, LeadConnector, or HighLevel CRM connection.
Pick a data point from the list, opportunity metrics, lost-by-reason entries, contacts, conversations, appointments, or payments.
Choose a sync frequency (daily, weekly, monthly, etc.).
Save the KPI; an initial sync runs automatically. Use Resync on the KPI card to pull fresh data on demand.
Troubleshooting
Blank OAuth page: confirm you connected the brand that matches your HighLevel install domain (Momentum Engine/LeadConnector vs HighLevel CRM).
Invalid scope error: platform OAuth scopes must use current HighLevel scope names (for example payments/transactions.readonly, not deprecated payments.readonly). Contact your administrator if Connect fails at consent.
Failed to fetch data / 422 on contacts: usually caused by unsupported query parameters on GET /contacts/. Count-based contact KPIs should work; date-filtered contact KPIs may fail until search API support is added.
504 / Request idle timeout: opportunity value KPIs on very large pipelines. Retry after off-peak hours or split into smaller filtered KPIs (for example won value only).
Location ID not found: disconnect and reconnect, ensuring you select a location during OAuth.
Lost reason data points missing: your location may have no configured lost reasons in HighLevel, or the lost-reasons API returned empty. Add lost reasons in HighLevel CRM settings.
Sync succeeded but value looks wrong: check whether the metric is a count (meta.total) or a paginated sum (capped at 2,000 rows). Verify status filters match how deals are staged in HighLevel (open vs won vs lost).
Disconnect and privacy
Disconnect from Workspace Settings → Integrations to revoke stored OAuth tokens and stop scheduled syncs.
Previously synced KPI history remains until you delete or convert those KPIs.
Integration data is used only to populate KPIs and dashboards in your workspace.
Subprocessors and data handling are described in Subprocessors and integrations.