Concepts
Run everything from your own system
How to sign up, follow and look after your customers from your own product, what to keep in step, and what still needs the portal.
Your sellers and your back office already work in your own product. This guide shows how to make that product the place where Monotree is sold and looked after, so nobody has to open the Partners portal for daily work. It ends with the short list of things that still need the portal, and a checklist for going live.
The portal and the API are two doors to the same thing. What your system does over the API shows in the portal at once, and the other way round: you can move over step by step.
The parts
| You want to | Use | Guide |
|---|---|---|
| Tie Monotree's objects to yours | external_ref on customers and sellers |
below |
| Sign up a customer | POST /customers |
Quickstart |
| Know what happens to it | Webhooks, and GET /events to catch up |
Webhooks |
| Change, suspend, cancel | PATCH, /suspend, /resume, DELETE |
Lifecycle, Changing a customer |
| Credit your sellers | seller_ref, /sellers |
Sellers |
| See how customers do | /statistics, /adoption-alerts |
Statistics and adoption |
| Check your month | /overview |
The monthly statement |
| Answer support | /support/… |
The support desk |
1. Map your IDs
You do not need to store Monotree's IDs. Give each customer and each seller your own ID as its external_ref, and use that ID everywhere.
| Your object | Send | Then use |
|---|---|---|
| The organisation that buys Monotree | external_ref when you create the customer, such as org_48213 |
/customers/external_ref:org_48213 in any path that takes a customer, ?external_ref=org_48213 to find it, customer=external_ref:org_48213 as a filter |
| The person who sold it | seller_ref (and seller_name) when you create the customer, such as usr_20503 |
/sellers/external_ref:usr_20503 in any path that takes a seller, seller=external_ref:usr_20503 as a filter on lists |
An external_ref names one customer (or one seller) of yours per mode: a second one with the same reference is refused with 422. It may not contain /, ? or #. Every customer in an answer or an event carries its external_ref and its seller's, so you can find your own record without a lookup table.
2. Create a customer and follow it
- Optional: check the company ID while your seller types it, and look for look-alikes to warn about a customer you already have.
- Create the customer with an
Idempotency-Key. Use a key you can make again for the same sign-up, such as the ID of the order in your system, so a retry after a crash on your side is still safe. - The answer is the customer in
provisioning. Show your seller that it is being set up. - Wait for
customer.live(orcustomer.failed) at your webhook endpoint.customer.stepevents give you a progress bar. - On
customer.failed, showdata.details.reason, let someone fix what it names with aPATCH, then retry.
To let a seller save a sign-up and finish it later, create it with draft: true. A draft needs only a company_name: everything else, the admin and terms_accepted included, can be added later with PATCH. What you do send is checked as always. Submit it when it is ready: that is where a draft is checked as a whole, and a draft that is not finished answers 422 with the missing fields in fields, named as Create a customer names them (admin.email).
After that, the same customer is changed with PATCH, paused with /suspend when it stops paying you, given back with /resume, and ended with DELETE. The customer lifecycle has every state.
3. Stay in step
Your copy of a customer can fall behind: your server was down, an endpoint was paused, or someone changed the customer in the portal. Three tools keep it right. Use all three.
| Tool | Tells you | Use it |
|---|---|---|
| Webhooks | Each change, seconds after it happened | Always. This is the normal path. |
GET /events?after=… |
Every event since the last one you handled, in order, for 90 days | After downtime, after an endpoint was paused, and on a timer as a safety net |
GET /customers?updated_since=… |
The customers as they are now, changed since a time | To rebuild or check your copy, for example once a night |
A loop that works:
- On each webhook: check the signature, answer
2xx, then handle the event. Skip an event whoseidyou have handled before. Remember theidof the newest event you handled. - Every few minutes, and when your server starts: call
GET /events?after=<that id>&limit=100with a token that may read everything you listen to (customers:read, plussupport:readfor support events) and handle what comes back, oldest first, followingnext_cursorwhilehas_moreistrue. When webhooks work this returns nothing. - Once a night: call
GET /customers?updated_since=<the time of the last run, minus a few minutes>and compare each customer with your copy.
curl "https://partners.monotree.com/api/v1/events?after=evt_01jcz8wg4h7v3y6n9q2k5m8p1r&limit=100" \
-H "Authorization: Bearer $MONOTREE_TOKEN"An event carries the customer as it was right after the event. Events can arrive out of order, so when you update your copy from one, keep the newer of the two by updated_at, or read the customer again.
Sellers work the same way: seller.* events, and List sellers with updated_since. So do support threads, with support.* events and updated_since on List support threads.
4. Sellers and attribution
Every customer is credited to one seller, and the monthly statement is split by seller. The simplest way is to send seller_ref with your own ID for the person, and seller_name, on every POST /customers: the first time a reference is seen, a seller is added for it. Such a seller has no portal login and needs none.
Use the sellers endpoints when you want more: to add your team up front, rename someone, invite a person to the portal, make them an admin (this needs the admins:write ability as well), or disable someone who left. A customer's seller is set when it is created and cannot be changed afterwards. Sellers and attribution has the details.
5. Statistics and adoption
Monotree collects each live customer's numbers once a night: how many employees were invited, how many signed in, how many were active. Read them per customer or for all customers at once, and show them where your account managers work.
An adoption alert is raised when a live customer stalls. Listen for adoption.alert.raised and adoption.alert.resolved, or read List adoption alerts, and create a task in your own system for the customer's seller. Statistics and adoption explains the numbers and the rules.
6. The support desk
Employees and admins of your customers ask for help in the Monotree app or by email. Those questions come to your support desk, and you can run the desk from your own helpdesk: support.message.received tells you about a new message, Answer a support thread sends your answer, and the rest of the desk (notes, assigning, closing, the assistant's drafts, escalations to Monotree, the desk's settings) has endpoints too. The support desk walks through it.
7. The monthly statement
Get a month returns your month as Monotree counts it: the live customers and their employees, per seller and per customer, as JSON or as CSV. Pull it after the month has ended to check your invoice or to feed your own billing and commission runs. The monthly statement says exactly who is counted.
What still needs the portal
Everything above works without the portal. These things do not have an endpoint:
| What | Where it is done |
|---|---|
| Your first API token | An admin creates it in the portal under Developers, or Monotree gives it to you. Further tokens can be created over the API. |
| A person's own sign-in | Each person does this themselves in the portal: choosing a password from the invitation link, changing or resetting the password, setting up two-factor sign-in or moving it to a new phone, new recovery codes, adding and removing passkeys, and choosing their language. The API can only reset someone's two-factor sign-in so they can set it up again. |
| Reading the portal's charts | The portal draws charts of the statistics. The numbers behind them are all in the API. |
| One support message to many people | Writing to several customers' people at once is done on the portal's Support page. Over the API you start one thread per person. |
| Translating a support message, and the assistant's working steps | Shown on the portal's Support page only. |
| The Monday email about stalling customers | Sent by Monotree to your sellers and admins. Each person can switch it off on their account page; over the API it is adoption_digest on the seller. |
And a few things cannot be done by you at all, in the portal or over the API. Ask your Monotree contact:
- undoing a cancellation in the 30 days before the customer is deleted;
- moving a customer to another seller;
- deleting a seller (disable them instead);
- editing or deleting a support message or note once it is sent;
- closing an adoption alert by hand (it closes when the customer recovers);
- changing your company's name, or the logo the portal shows for it;
- a higher rate limit for a migration.
The guides of each area list their own gaps: sellers, security, statistics, the statement and support.
Go-live checklist
Build in the sandbox first
- The whole flow runs with a sandbox token: create, live, change, suspend, resume, cancel.
- You have seen a failed setup (
fail…company ID) and your product shows the reason and can retry. - Your code ignores fields, event types and
provisioning.stepvalues it does not know.
Webhooks
- Your endpoint checks
Monotree-Signatureon the raw body, in constant time, and refuses atmore than 5 minutes off. - It accepts an event when any
v1matches, so a rotated secret does not break it. - It answers
2xxwithin 10 seconds and does the work afterwards. - It skips an event
idit has handled before, and does not rely on the order of arrival. - A job reads
GET /events?after=…on a timer and at start-up. - You subscribe a second endpoint (or a person watches the portal) for
webhook_endpoint.paused.
Calls
- Every
POST /customerssends anIdempotency-Key, and so do the otherPOSTcalls you retry. - You retry
429,5xxand network errors with growing waits, and honourRetry-After. - You act on the error
type, never on themessage.
Secrets
- Tokens and signing secrets live in a secrets manager, never in a browser, an app or a repository.
- Each system has its own token with only the abilities it uses, and an
expires_at. - You have rotated a token and a signing secret once, on purpose, and know how.
- Sandbox tokens are used for development and CI; live tokens only in production.
Switch
- Create the live token and the live webhook endpoint (it has its own secret).
- Sign up one real customer and follow it to
live.