Concepts

Statistics and adoption

How your customers use Monotree, what each number means and how old it can be, and how to hear about a customer that stalls.

When the numbers land

Monotree counts each live customer once a night and keeps one set of numbers per customer per day. Everything on this page is built from those days, so it changes once a day and not while you watch.

  • Days are UTC days. updated_at is the day of the latest numbers, such as 2026-11-14.
  • A customer's first numbers come the night after it goes live. Until then its totals are 0, daily is empty and updated_at is null.
  • Numbers are normally less than a day old. If a night is missed, updated_at stays where it was; after 3 days without numbers the customer gets an adoption alert with the reason stale.

Every call here needs the customers:read ability. A sandbox token gets the sandbox's customers, a live token the live ones.

Call Answers
Get a customer's statistics The numbers of one customer
Get the statistics of all customers The same numbers for all your live customers together, and each customer beside the others
Get a customer's insights What one customer's numbers mean, and what to do next
Get the headline numbers Where you stand right now, in one small answer
List adoption alerts The customers that stall

The first three take range: 7d, 30d (when left out) or 90d. It is the last 7, 30 or 90 days, today included. Any other value answers 422.

One customer

cURL
curl "https://partners.monotree.com/api/v1/customers/cus_01jcz8w3k1x9q2v7s4e6m0b5n8/statistics?range=7d" \
  -H "Authorization: Bearer $MONOTREE_TOKEN"
JSON
{
  "object": "statistics",
  "customer": "cus_01jcz8w3k1x9q2v7s4e6m0b5n8",
  "range": "7d",
  "updated_at": "2026-11-14",
  "totals": {
    "users": 8,
    "invited": 9,
    "active_users_7d": 7,
    "activation_rate": 89,
    "weekly_active_rate": 88,
    "devices": { "ios": 4, "android": 3 },
    "push_enabled_rate": 86
  },
  "period": { "posts": 3, "comments": 9, "reactions": 27, "messages": 48, "user_growth": 0 },
  "languages": { "fr": 7, "en": 1 },
  "daily": [
    { "date": "2026-11-13", "users": 8, "active_users": 4, "posts": 1, "comments": 2, "reactions": 5, "messages": 9 },
    { "date": "2026-11-14", "users": 8, "active_users": 2, "posts": 0, "comments": 1, "reactions": 3, "messages": 4 }
  ]
}

(daily is cut short here: it has one row for each day in the range that has numbers, oldest first.)

Field Means
totals.invited Employees the customer's admin has invited to the app
totals.users Employees who registered in the app
totals.activation_rate users as a percent of invited, rounded. 0 when nobody is invited
totals.active_users_7d Users who opened the app in the last 7 days
totals.weekly_active_rate active_users_7d as a percent of users, rounded. 0 when there are no users
totals.devices Phones with the app, per platform (ios, android)
totals.push_enabled_rate Percent of those phones with push notifications on
period.posts, comments, reactions, messages Sums over the range
period.user_growth Percent change in users since the day before the range began, with one decimal. null when the customer had no users or no numbers then
languages Users per app language, by language code
daily[].users Registered employees on that day
daily[].active_users Users who opened the app that day

totals are the latest day in the range. period and daily cover the range.

  • The call answers for a customer in any status. A customer with no numbers in the range (a draft, or one that went live today) answers 0 everywhere, "daily": [], "updated_at": null and "user_growth": null.
  • When there are no numbers, languages is written as an empty list ([]) and not as an empty object. Treat both as "none".
  • Instead of the cus_… ID you can write external_ref: followed by your own reference, such as /customers/external_ref:org_48213/statistics.

All customers together

cURL
curl "https://partners.monotree.com/api/v1/statistics?range=7d" \
  -H "Authorization: Bearer $MONOTREE_TOKEN"
JSON
{
  "object": "partner_statistics",
  "range": "7d",
  "updated_at": "2026-11-14",
  "customers": 43,
  "employees": 949,
  "totals": { "users": 724, "invited": 947, "active_users_7d": 468, "activation_rate": 76, "weekly_active_rate": 65, "devices": { "ios": 392, "android": 274 }, "push_enabled_rate": 80 },
  "period": { "posts": 147, "comments": 390, "reactions": 1450, "messages": 3019, "user_growth": 3.9 },
  "languages": { "fr": 425, "es": 112, "en": 88, "it": 67, "nl": 17, "de": 15 },
  "daily": [ { "date": "2026-11-14", "users": 724, "active_users": 160, "posts": 13, "comments": 29, "reactions": 128, "messages": 252 } ],
  "customers_ranked": [
    {
      "customer": "cus_01jcz8w3k1x9q2v7s4e6m0b5n8",
      "company_name": "Boulangerie Martin",
      "company_id": "boulangeriemartin",
      "external_ref": "org_48213",
      "seller": { "id": "sel_12", "name": "Emma Dubois", "external_ref": "usr_20503" },
      "employees": 9,
      "users": 8,
      "activation_rate": 89,
      "weekly_active_rate": 88,
      "weekly_active_change": 0,
      "activity": 87,
      "adoption": null
    },
    {
      "customer": "cus_01jd0b2q4m6s8u0w2y4a6c8e0g",
      "company_name": "Librairie Voltaire",
      "company_id": "librairievoltaire",
      "external_ref": "org_51877",
      "seller": { "id": "sel_12", "name": "Emma Dubois", "external_ref": "usr_20503" },
      "employees": 21,
      "users": 4,
      "activation_rate": 19,
      "weekly_active_rate": 75,
      "weekly_active_change": 0,
      "activity": 34,
      "adoption": { "alert": "ala_01jd3m5p7r9t1v3x5z7b9d1f3h", "reason": "activation", "message": "Only 19% of invited employees have signed in, 126 days after going live" }
    }
  ]
}
  • Only customers with the status live are counted: not suspended or cancelled ones. customers says how many, employees how many employees they were signed up with.
  • totals add up each customer's latest numbers, and updated_at is the newest day among them.
  • customers_ranked has every live customer and is never paged. The best taken up comes first: the order is activation_rate times weekly_active_rate, then users.
  • activation_rate and weekly_active_rate of a customer are null until its first numbers.
  • weekly_active_change is the weekly active rate now minus the rate on the day before the range began, in percentage points. It is null when the customer had no users or no numbers then.
  • activity is posts, comments, reactions and messages in the range.
  • adoption is null, or the customer's open adoption alert.
  • seller= narrows everything to one seller's customers: sel_…, or external_ref: and your own ID for the seller. An unknown seller answers 404. seller is null on a customer made over the API without a seller_ref.

The headline numbers

Get the headline numbers takes no parameters and answers what stands on top of the Customers page in the portal:

JSON
{
  "object": "summary",
  "counts": { "draft": 1, "provisioning": 0, "live": 43, "failed": 1, "suspended": 2, "cancelled": 3 },
  "live_customers": 43,
  "employees": 949,
  "users": 724,
  "activation_rate": 76,
  "weekly_active_rate": 65,
  "low_adoption": 4,
  "signed_by_month": [
    { "month": "2026-06", "signed": 6 },
    { "month": "2026-07", "signed": 7 },
    { "month": "2026-08", "signed": 6 },
    { "month": "2026-09", "signed": 5 },
    { "month": "2026-10", "signed": 5 },
    { "month": "2026-11", "signed": 7 }
  ]
}
  • counts is how many customers are in each status right now. Deleted customers are not counted.
  • employees, users and the two rates are those of all live customers together.
  • low_adoption is how many live customers have an open adoption alert.
  • signed_by_month is the customers submitted in each of the last six months (UTC), oldest first and this month last.

Insights

Get a customer's insights answers what the Statistics tab of a customer shows in the portal:

JSON
{
  "object": "insights",
  "customer": "cus_01jcz8w3k1x9q2v7s4e6m0b5n8",
  "range": "7d",
  "live_days": 128,
  "verdict": {
    "key": "doing_well",
    "title": "Doing well",
    "text": "88% of its users came this week, more than your customers on average (64%).",
    "next_step": "A good customer to ask for a quote or a reference."
  },
  "funnel": [
    { "key": "employees", "label": "Employees", "value": 9 },
    { "key": "invited", "label": "Invited", "value": 9 },
    { "key": "signed_in", "label": "Signed in", "value": 8 },
    { "key": "active_this_week", "label": "Active this week", "value": 7 }
  ],
  "comparison": [
    { "key": "activation_rate", "label": "Signed in", "value": 89, "average": 76, "unit": "percent" },
    { "key": "weekly_active_rate", "label": "Active this week", "value": 88, "average": 64, "unit": "percent" },
    { "key": "activity_per_active_user", "label": "Activity per active user", "value": 12.4, "average": 10.7, "unit": "per_week" },
    { "key": "push_enabled_rate", "label": "Push notifications on", "value": 86, "average": 80, "unit": "percent" }
  ],
  "activity": { "now": 87, "before": 92, "change": -5 },
  "weekly_active_rate": [ { "date": "2026-11-14", "rate": 88, "average": 65 } ]
}

The texts (title, text, next_step, label) are English sentences for a person and may be reworded. Build on the keys.

The verdict is the first of these that fits:

verdict.key When
needs_attention The customer is live and has an open adoption alert. text is the alert's message, next_step its advice.
getting_started It went live less than 14 days ago.
doing_well Its weekly active rate is at or above that of your other live customers together.
on_track Anything else.
  • funnel is the rollout: the employees the customer was signed up with, then invited, users and active_users_7d of its statistics.
  • comparison[].average is the same number for your other live customers together, without this one. It is null when no other live customer has numbers.
  • activity_per_active_user is posts, comments, reactions and messages a week for each user active in the last 7 days.
  • activity.before is the period of the same length before the range, and change the percent between the two (null when before is 0).
  • weekly_active_rate has one row for each day in the range the customer has numbers for. average is null on a day none of your other live customers has numbers for.
  • A customer that was never live answers 409 with the error type invalid_state. A customer that was live and is now suspended or cancelled still answers.

Adoption alerts

An adoption alert says that a live customer stalls. Monotree checks every customer with the status live each morning at 05:00 UTC, after the night's numbers. The first rule that fits gives the alert its reason:

reason Raised when
stale The latest numbers are 3 days old or more (or there are none), for a customer live 3 days or more. Monotree looks into these; there is nothing for you to do.
activation Fewer than 30% of the invited employees have registered, with 5 or more invited.
drop The weekly active rate is below half of what it was 4 weeks earlier, and it was 20% or more then.
inactive The weekly active rate is below 20%.
  • The first 14 days after going live are a grace period: only stale is raised in them.
  • A rate over fewer than 5 people is not judged: activation needs 5 invited employees, drop and inactive need 5 users (and drop 5 users 4 weeks earlier too).
  • A customer has at most one open alert. While it stays open, its reason and message follow the latest numbers, without a new event.
  • The alert is resolved (resolved_at is set) at the next morning's check when the customer no longer fits any rule, or is no longer live (suspended, cancelled or deleted).
  • A customer that stalls again within 14 days of resolved_at re-opens the same alert: same id, same flagged_at, and resolved_at is null again. Later than that, it gets a new alert.
  • An alert cannot be closed by hand, in the portal or over the API.
JSON
{
  "id": "ala_01jd3m5p7r9t1v3x5z7b9d1f3h",
  "object": "adoption_alert",
  "customer": { "id": "cus_01jd0b2q4m6s8u0w2y4a6c8e0g", "company_name": "Librairie Voltaire", "external_ref": "org_51877" },
  "reason": "activation",
  "message": "Only 19% of invited employees have signed in, 126 days after going live",
  "advice": "Ask Louis Arnaud to invite the team again, or to share the company ID librairievoltaire at the next staff meeting.",
  "flagged_at": "2026-11-14T05:00:04Z",
  "resolved_at": null
}

message and advice are English sentences for a person and may be reworded; build on reason. flagged_at is when the alert was first raised.

Reading alerts

List adoption alerts gives the open ones. status=resolved or status=all gives the others; customer= (a cus_… ID, or external_ref: and your own reference), seller= (a sel_… ID, or external_ref: and your own reference) and reason= filter. An unknown customer or seller answers 404. The list is paged like every list (limit, cursor), the alert made last first. Get an adoption alert answers one.

cURL
curl "https://partners.monotree.com/api/v1/adoption-alerts?reason=activation" \
  -H "Authorization: Bearer $MONOTREE_TOKEN"

The customer itself carries its open alert too. Get a customer has adoption, which is null when the customer has no open alert:

JSON
{
  "adoption": {
    "alert": "ala_01jd3m5p7r9t1v3x5z7b9d1f3h",
    "reason": "activation",
    "message": "Only 19% of invited employees have signed in, 126 days after going live",
    "flagged_at": "2026-11-14T05:00:04Z"
  }
}

List customers with adoption=stalling gives only the customers with an open alert.

Events

Event Sent when
adoption.alert.raised The morning check opens an alert, or re-opens one after the customer had recovered
adoption.alert.resolved The morning check closes the alert: the customer recovered, or is no longer live

Both carry the alert in data.adoption_alert, in the shape above, and nothing else in data. Their actor is null. They are sent once per change, not every morning the alert stays open, and not when only reason or message change. See Webhooks for how to receive them.

JSON
{
  "id": "evt_01jd3m5p9c2e4g6j8m0p2r4t6v",
  "object": "event",
  "type": "adoption.alert.raised",
  "created_at": "2026-11-14T05:00:04Z",
  "sandbox": false,
  "actor": null,
  "data": {
    "adoption_alert": {
      "id": "ala_01jd3m5p7r9t1v3x5z7b9d1f3h",
      "object": "adoption_alert",
      "customer": { "id": "cus_01jd0b2q4m6s8u0w2y4a6c8e0g", "company_name": "Librairie Voltaire", "external_ref": "org_51877" },
      "reason": "activation",
      "message": "Only 19% of invited employees have signed in, 126 days after going live",
      "advice": "Ask Louis Arnaud to invite the team again, or to share the company ID librairievoltaire at the next staff meeting.",
      "flagged_at": "2026-11-14T05:00:04Z",
      "resolved_at": null
    }
  }
}

(The event also has api_version, as every event does.)

In the sandbox

Sandbox customers never reach Monotree's platform, so nobody uses them. Their numbers are made up: a team that signs in over three weeks, busier on weekdays than at weekends. The same customer always gets the same numbers.

  • The made-up numbers are written each morning at 04:30 UTC, not at once. A sandbox customer has no numbers on the day it goes live; its first ones come the next morning.
  • The adoption check at 05:00 UTC judges sandbox customers by the same rules as live ones. A normal sandbox team is busy enough not to stall.
  • To get an alert on purpose, give the customer a company ID that starts with stall, such as stalltest, and 10 employees or more. Only about 18% of its team signs in and the 14 days of grace are skipped, so it has an alert with the reason activation, and you get adoption.alert.raised, at the first check after the day it goes live. See Sandbox and testing.
  • Statistics, insights, alerts and both events work with a sandbox token and stay in the sandbox: sandbox numbers are never mixed into live ones, and the events go only to your sandbox webhook endpoints.
  • The Monday email about customers that stall never mentions a sandbox customer.

What still needs the portal

  • The charts. The API gives the numbers behind them.
  • The Monday email about customers that stall, sent to your sellers and admins. Each person turns it off on their account page; over the API it is adoption_digest of a seller.

There is no endpoint that changes anything on this page: the numbers, the rules and their thresholds are Monotree's.