Skip to main content
The AppInstall event fires whenever your app is installed by a user, either at the location (sub-account) level or at the agency level. It includes trial information, whitelabel details, and the plan selected at installation time. Note that userId and companyId may not always be present — for example, when the app is installed via a future location provisioning flow. Use this event to initialize app state, begin onboarding flows, or activate the correct plan tier for the installing account.

​
Payload

FieldTypeDescription
typestringAlways "INSTALL"
appIdstringID of the app that was installed
companyIdstringAgency ID of the installing account
locationIdstringSub-account ID if installed at the location level; omitted for agency-level installs
userIdstringID of the user who initiated the install; may be absent in some flows
planIdstringID of the plan selected at install time
trialobjectTrial information for the install
trial.onTrialbooleanWhether the account is starting on a trial
trial.trialDurationnumberDuration of the trial period in days
trial.trialStartDatestringISO 8601 timestamp of when the trial started
isWhitelabelCompanybooleanWhether the installing agency is a whitelabel customer
whitelabelDetailsobjectWhitelabel branding details; present when isWhitelabelCompany is true
whitelabelDetails.domainstringCustom domain used by the whitelabel company
whitelabelDetails.logoUrlstringURL of the whitelabel company’s logo
companyNamestringDisplay name of the installing agency

​
Example payload

​
Location level (whitelabeled)

{
  "type": "INSTALL",
  "appId": "ve9EPM428h8vShlRW1KT",
  "locationId": "otg8dTQqGLh3Q6iQI55w",
  "companyId": "otg8dTQqGLh3Q6iQI55w",
  "userId": "otg8dTQqGLh3Q6iQI55w",
  "planId": "66a0419a0dffa47fb5f8b22f",
  "trial": {
    "onTrial": true,
    "trialDuration": 10,
    "trialStartDate": "2024-07-23T23:54:51.264Z"
  },
  "isWhitelabelCompany": true,
  "whitelabelDetails": {
    "domain": "example.com",
    "logoUrl": "https://example.com/logo.png"
  },
  "companyName": "Example Company"
}

​
Agency level

{
  "type": "INSTALL",
  "appId": "ve9EPM428h8vShlRW1KT",
  "companyId": "otg8dTQqGLh3Q6iQI55w",
  "planId": "66a0419a0dffa47fb5f8b22f",
  "trial": {
    "onTrial": true,
    "trialDuration": 10,
    "trialStartDate": "2024-07-23T23:54:51.264Z"
  }
}
  • App Uninstall — fires when your app is removed
  • OAuth 2.0 — authorization flow used during app installation
Last modified on March 4, 2026