App Installer Details API GoHighLevel: Agency Branding Guide

Building a marketplace app for GoHighLevel? You're about to hit a critical fork in the road: either you integrate deeply with agency branding, or you watch user adoption tank.

The App Installer Details API is the bridge between your app and the agency owner's world. It tells you who installed your app, which agency or sub-account they're in, and—crucially—what white-label branding they've applied. That means you can personalize onboarding, match their UI, and engage them without requesting broad OAuth scopes that trigger privacy concerns.

In this guide, I'll walk you through exactly how to master this API, why it matters for retention, and how to implement it so your app feels like a native part of their GoHighLevel ecosystem. If you're serious about building on the platform, grab a free 30-day GoHighLevel trial to test your integrations in a real environment.

What Is the App Installer Details API?

The App Installer Details API is a lightweight, purpose-built endpoint that returns metadata about app installations. When someone installs your app from the GoHighLevel Marketplace, this API tells you:

• Installation context: Which location, sub-account, or company the app was installed into
• Agency owner details: Contact info and ID of the person who triggered the install
• White-label branding: Colors, logos, domain names, and custom branding the agency applied to their GoHighLevel account
• Account hierarchy: Whether this is a parent agency, sub-account, or standalone location

Unlike other API endpoints that require you to request broad company:read or location:read OAuth scopes, the Installer Details API is scoped specifically to the installation event. This means you get exactly what you need—nothing more, nothing less—which preserves user trust and reduces friction during onboarding.

Why Agency Branding Matters for App Retention

Here's the uncomfortable truth: if your app looks like a generic third-party tool grafted onto their GoHighLevel account, users will treat it like one. They'll use it occasionally, forget about it, and eventually uninstall.

But if your app adopts their branding—their logo, their color scheme, their domain—it feels native. It feels like part of the platform they're paying for. This psychological shift is massive for retention.

The Installer Details API gives you the branding data you need to make this happen. You pull their white-label settings on install, cache them securely, and apply them throughout your app's interface. Now when the agency owner or their team uses your app, they see themselves reflected back.

Retention studies show that branded integrations have 30-40% higher long-term adoption than generic ones. In a competitive marketplace, that's the difference between a thriving app and one that bleeds users.

How to Access Installer Details Without Broad OAuth Scopes

The traditional approach to getting installation context is to request company:read scope and then query the Company API. But this requires the user to grant broad access to their entire company profile—a red flag for security-conscious agencies.

The Installer Details API flips this model. When a user installs your app, GoHighLevel automatically sends you an INSTALL webhook event that contains installation metadata. You don't have to ask for it; it's pushed to you.

Here's what the webhook payload looks like:

{
  "type": "INSTALL",
  "installationId": "install_abc123",
  "locationId": "loc_xyz789",
  "companyId": "comp_def456",
  "userId": "user_ghi012",
  "agencyId": "agency_jkl345",
  "isWhiteLabel": true,
  "whiteLabel": {
    "companyName": "Acme Marketing Agency",
    "logo": "https://...",
    "primaryColor": "#0066cc",
    "domain": "acme.gohighlevel.com"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

Store this data securely (encrypted in your database, never in local storage or cookies). Now you have everything you need to personalize the experience—and you never asked for a single OAuth scope beyond what's required for your core functionality.

Handling INSTALL and UNINSTALL Webhook Events

Webhooks are the heart of the Installer Details API workflow. GoHighLevel will POST two types of events to the Default Webhook URL you configured in your marketplace app settings:

INSTALL Event: Triggered when a user installs your app at a location or company. In bulk installations (where one user installs across multiple locations), you'll receive one INSTALL event per location. Your SDK should generate and store an access token for each.

UNINSTALL Event: Triggered when the app is uninstalled at a location or company. Your app should immediately revoke the stored token and clean up any cached data tied to that installation.

Here's the critical detail: you must use the same webhook URL for both events. If you configure a different webhook URL in your app settings, GoHighLevel will ignore your endpoints and only send events to the default URL. This catches many developers off guard.

Most official SDKs (PHP, Python, Node.js) include built-in signature verification for webhooks. Always verify the signature before processing. This prevents spoofed webhook attacks.

Pulling White-Label Data for UI Personalization

Once you've captured the white-label branding data from the INSTALL webhook, the next step is applying it consistently throughout your app.

Store the branding in a secure, encrypted database field. Never rely on client-side storage for agency branding data—it's both a security risk and unreliable across sessions.

Build a theming layer into your frontend. Whether you're using React, Vue, or vanilla JavaScript, create a theme context or module that pulls branding from your backend. This centralizes the logic and makes updates instant across your entire UI.

Apply branding at runtime, not build time. If you hardcode branding during your build process, you'll have to redeploy your app every time an agency changes their colors. Instead, fetch branding from your API when the user loads your app, and apply it dynamically via CSS variables or a theming library.

Example CSS approach:

:root {
  --primary-color: var(--agency-primary);
  --logo-url: url(var(--agency-logo));
  --company-name: var(--agency-name);
}

.app-header {
  background-color: var(--primary-color);
}

.app-logo {
  background-image: var(--logo-url);
}

SDK Implementation Across Languages

GoHighLevel provides official SDKs for the three most common platform stacks. Each handles webhook verification and token management natively.

Node.js/TypeScript (@gohighlevel/api-client): Install via npm, initialize with your client credentials, and the SDK automatically handles INSTALL/UNINSTALL events. Use the built-in webhook handler middleware in your Express or Fastify app.

Python (gohighlevel-api-client): Install via pip. Initialize with OAuth credentials, and use the webhook verification utilities to validate incoming events before processing them. This is the go-to for data-heavy apps and automation workflows.

PHP (gohighlevel/api-client on Packagist): Composer is your package manager. The PHP SDK includes Laravel middleware for webhook handling out of the box, making integration seamless if you're building on Laravel.

Whichever language you choose, always use the official SDK. Trying to reverse-engineer the API or build custom HTTP clients will cost you more time than it saves, and you'll miss critical security features like signature verification.

This is built into GoHighLevel. Try it free for 30 days →

Best Practices for Production Deployments

1. Cache installer details aggressively. You don't need to hit the Installer Details API on every request. Cache the installation metadata in Redis or your database for at least 24 hours. This reduces latency and API calls.

2. Implement token rotation. Store access tokens securely with an expiration timestamp. Implement a refresh flow so expired tokens are renewed without user action. The GoHighLevel platform supports refresh tokens for exactly this reason.

3. Log all webhook events. Keep a detailed audit trail of every INSTALL and UNINSTALL event. This makes debugging account issues and tracking app usage trivial.

4. Handle bulk installations gracefully. If a user installs your app across 50 locations at once, you'll receive 50 INSTALL webhooks rapidly. Use a queue (Bull, Celery, or Sidekiq) to process them asynchronously so you don't block your webhook handler.

5. Test uninstall flows thoroughly. Many developers skip uninstall testing and ship broken cleanup logic. When the app is uninstalled, verify that all tokens are revoked, cached data is deleted, and webhooks stop being processed for that installation.

Real-World Scenarios: When App Installer Details Become Critical

Understanding when and why to implement the App Installer Details API separates successful marketplace apps from abandoned ones. Consider this common scenario: you're building a lead management tool for the GoHighLevel marketplace. Without installer details, every agency sees identical branding, buttons, and color schemes—regardless of their white-label setup. This creates cognitive friction. An agency owner logs in expecting their branded experience and instead sees generic developer branding. They uninstall within days.

With the App Installer Details API, your app automatically detects the agency's white-label colors, logo, and branding guidelines. Your UI adapts in real-time. The same app feels like a native extension of their platform. Installation rates climb. Retention improves. Support tickets drop because users immediately recognize the tool as "theirs."

Another critical scenario: multi-location agencies with sub-accounts. Without installer details, you can't distinguish between a company owner and a location-level user. The API provides this context automatically. You can enforce different permission levels, surface location-specific data, and prevent unauthorized access—all without requesting broad OAuth scopes that trigger security concerns.

The third scenario involves webhook handling during bulk installations. If an agency owner installs your app across 50 locations simultaneously, the INSTALL webhook fires for each location. Without proper installer details handling, you might create duplicate records, lose token associations, or fail to map installations to the correct account hierarchy. The API ensures each installation is tracked independently while maintaining the parent-child relationship.

Advanced Token Management and Scope Reduction Strategy

One of the most overlooked benefits of the App Installer Details API is scope reduction. Traditional OAuth flows request broad permissions like "manage:company" or "read:all_locations." This triggers red flags during security audits and makes agencies hesitant to install. The App Installer Details API flips this approach.

Instead of requesting company-wide access, you request minimal scopes: location-specific read access and app-level installation data. The installer details endpoint then provides company and white-label metadata without requiring broader permissions. Your security posture improves. Agencies feel safer installing. Your app gets approved faster in security reviews.

Token rotation becomes simpler too. When an agency reinstalls your app or refreshes credentials, the installer details endpoint confirms the new token's scope and associated account hierarchy. You can validate token validity without making multiple test API calls. This reduces latency during onboarding and prevents failed installations due to scope mismatches.

For agencies managing 90+ sub-accounts (a common Reddit pain point), this approach scales elegantly. Each sub-account gets its own token, but the parent company's white-label data flows through the installer details endpoint. You build once, scale infinitely.

Troubleshooting Common Implementation Issues

Most implementation failures stem from three root causes: webhook timing issues, inconsistent token storage, and missing UNINSTALL handlers. When the INSTALL webhook fires, your backend must immediately fetch and cache installer details. Many developers wait too long, causing race conditions where users access your app before data is cached. Use synchronous storage during the webhook handler—write first, then trigger async enrichment tasks.

Inconsistent token storage breaks multi-location setups. Store tokens with a composite key: company_id + location_id. Don't use just the location ID. When handling UNINSTALL events, match this same key pattern to remove the correct token, preventing orphaned entries and authentication failures.

Finally, skip the UNINSTALL handler and you'll accumulate zombie tokens. These create support tickets when users reinstall but can't re-authenticate. The UNINSTALL handler is non-negotiable for production deployments.