Help Center

What is the App Installer Details API?

The App Installer Details API is a specialized interface for developers who have published applications in the CRM's marketplace. It provides verified information about the specific user who installed your app and the exact business context—such as the agency and sub-account—where the installation occurred. Crucially, the API also returns white-label branding data from the agency, enabling you to tailor your application's appearance and onboarding process without needing extensive OAuth permissions.

Key Benefits

Integrating this API into your marketplace application offers several strategic advantages:

Identity and Context: Accurately identify the user who installed your app and the specific sub-account and agency it was installed into.
White-Label Awareness: Access the agency's branding information to seamlessly integrate your app's look and feel with their white-label environment.
Reduced Permission Scope: Obtain agency details without requesting broad, company-level OAuth scopes, adhering to the principle of least privilege.
Personalized Onboarding: Create tailored welcome flows, content, and pricing based on the specific agency context.
Direct Owner Outreach: Access agency owner details to build relationships that can improve customer retention.

Authentication Options

The API's response depends on the type of authentication token you use. It is essential to choose the correct token for your application's context.

Supported Tokens: You can use either an Agency Token or a Sub-account Token.
Agency Token: When called with an agency token, the API returns details about the installer and the agency context. It may also indicate the specific sub-account where the installation took place, if applicable.
Sub-account Token: When called with a sub-account token, the API returns details about the installer and the agency context associated with that specific sub-account.

Best Practice: Always use the token that matches your application's current runtime context. For instance, a workflow running within a sub-account should use a sub-account token. Request only the minimal permissions necessary.

Endpoint and Request

You can retrieve the installer details by making a GET request to the API endpoint.

HTTP Method: GET

Endpoint Path: /marketplace/app-installer/details

Headers:

Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json

Response Schema

The API returns a JSON object containing detailed information. Key fields include (confirm exact field names in the official API documentation):

installer.userId: The unique identifier of the user who installed the app.
installer.name: The full name of the installer.
installer.email: The email address of the installer.
installationContext.subAccountId: The ID of the sub-account where the app is installed (this field can be null).
installationContext.agencyId: The ID of the parent agency.
agency.companyName: The legal or brand name of the agency.
agency.companyEmail: A general contact email for the agency.
agency.ownerName: The name of the agency's primary owner or administrator.
whiteLabel.brandName: The brand name used in the white-label setup.
whiteLabel.supportEmail: The support email address for branded communications (can be null).
whiteLabel.logoUrl: A URL pointing to the agency's logo for UI theming (can be null).

White-Label Data Usage Guidelines

Respecting white-label integrity is paramount. Use the provided branding data to enhance the user experience for the agency's users without revealing the upstream agency's identity to their end clients, unless explicitly intended.

Use fields like whiteLabel.brandName and logoUrl to theme your application's user interface.
Implement server-side caching for branding fields with a short time-to-live (TTL), such as 15 to 60 minutes, to optimize performance and handle updates gracefully.
Invalidate your cache if you detect changes in key branding elements like the logo URL or brand name.

Rate Limiting and Error Handling

To ensure your application remains reliable, adhere to the following practices:

Caching: Cache the installer and white-label data per token or context, refreshing the cache upon a new user login or session start.
Backoff Strategy: If you encounter a 429 (Too Many Requests) or 5xx (Server Error) response, implement an exponential backoff strategy with jitter for retries.
Efficiency: Avoid making unnecessary duplicate API calls by leveraging your cache effectively.