Master App Installer Details API in GoHighLevel — Agency Branding

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.

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

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.

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.