Get started
Quickstart
From a sandbox token to a live test customer in five calls, and a webhook when it is live.
This takes about ten minutes. Everything happens in the sandbox, so nothing is set up for real.
1. Get a sandbox token
In the portal, open Developers › API tokens › Create token, choose Sandbox and give it customers:read, customers:write and webhooks:manage. The first two are ticked already; webhooks:manage is not, so tick it yourself (step 2 answers 403 without it). Copy the token (it starts with mpt_test_); it is shown once.
export MONOTREE_TOKEN=mpt_test_…Check it with Who am I:
curl https://partners.monotree.com/api/v1/partner \
-H "Authorization: Bearer $MONOTREE_TOKEN"{
"object": "partner",
"id": "prt_acme",
"name": "Acme Scheduling",
"token": { "id": "tok_12", "name": "Quickstart", "abilities": ["customers:read", "customers:write", "webhooks:manage"], "sandbox": true },
"api_version": "1.0.0"
}2. Listen for events
A webhook endpoint is a URL on your side that Monotree calls when something happens. Add one so you hear when the customer goes live. For a first try, a tunnel to your own machine works: see Testing webhooks locally. You can also skip this step and poll in step 5.
curl -X POST https://partners.monotree.com/api/v1/webhooks \
-H "Authorization: Bearer $MONOTREE_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "url": "https://api.acme.example/hooks/monotree", "events": ["customer.live", "customer.failed"] }'Store the secret in the answer (whsec_…). You need it to verify signatures.
3. Pick a company ID
The company ID is the customer's address (boulangeriemartin.monotree.com) and what its employees type in the app: 3 to 40 lower-case letters and digits. A company ID is taken by one customer, and so is your own reference for the customer (external_ref), so pick your own two values here. The examples below show boulangeriemartin and org_48213; yours will differ, and running this guide a second time needs two new ones.
export COMPANY_ID=boulangeriemartin$RANDOM
export EXTERNAL_REF=org_$RANDOMcurl https://partners.monotree.com/api/v1/company-ids/$COMPANY_ID \
-H "Authorization: Bearer $MONOTREE_TOKEN"{ "object": "company_id", "company_id": "boulangeriemartin", "available": true, "reason": null, "suggestion": null }If available is false, reason says why (taken, reserved or invalid) and suggestion holds an ID that is free: set COMPANY_ID to it.
4. Create the customer
curl -X POST https://partners.monotree.com/api/v1/customers \
-H "Authorization: Bearer $MONOTREE_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"company_name": "Boulangerie Martin",
"company_id": "'"$COMPANY_ID"'",
"country": "FR",
"employees": 18,
"default_language": "fr",
"languages": ["fr", "en"],
"admin": { "name": "Claire Martin", "email": "claire@boulangeriemartin.example" },
"brand": { "primary_color": "#b45309" },
"seller_ref": "usr_20503",
"seller_name": "Emma Dubois",
"external_ref": "'"$EXTERNAL_REF"'",
"terms_accepted": true
}'$client = new GuzzleHttp\Client(['base_uri' => 'https://partners.monotree.com/api/v1/']);
$response = $client->post('customers', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
'Idempotency-Key' => bin2hex(random_bytes(16)),
],
'json' => [
'company_name' => 'Boulangerie Martin',
'company_id' => getenv('COMPANY_ID'),
'country' => 'FR',
'employees' => 18,
'default_language' => 'fr',
'languages' => ['fr', 'en'],
'admin' => ['name' => 'Claire Martin', 'email' => 'claire@boulangeriemartin.example'],
'brand' => ['primary_color' => '#b45309'],
'seller_ref' => 'usr_20503',
'seller_name' => 'Emma Dubois',
'external_ref' => getenv('EXTERNAL_REF'),
'terms_accepted' => true,
],
]);
$customer = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/customers', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.MONOTREE_TOKEN}`,
'Idempotency-Key': crypto.randomUUID(),
'Content-Type': 'application/json',
},
body: JSON.stringify({
company_name: 'Boulangerie Martin',
company_id: process.env.COMPANY_ID,
country: 'FR',
employees: 18,
default_language: 'fr',
languages: ['fr', 'en'],
admin: { name: 'Claire Martin', email: 'claire@boulangeriemartin.example' },
brand: { primary_color: '#b45309' },
seller_ref: 'usr_20503',
seller_name: 'Emma Dubois',
external_ref: process.env.EXTERNAL_REF,
terms_accepted: true,
}),
});
const customer = await response.json();import os, uuid
import requests
response = requests.post(
"https://partners.monotree.com/api/v1/customers",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"company_name": "Boulangerie Martin",
"company_id": os.environ["COMPANY_ID"],
"country": "FR",
"employees": 18,
"default_language": "fr",
"languages": ["fr", "en"],
"admin": {"name": "Claire Martin", "email": "claire@boulangeriemartin.example"},
"brand": {"primary_color": "#b45309"},
"seller_ref": "usr_20503",
"seller_name": "Emma Dubois",
"external_ref": os.environ["EXTERNAL_REF"],
"terms_accepted": True,
},
)
customer = response.json()seller_ref is your own ID for the person who signed the customer; a reference seen for the first time adds that seller. external_ref is your own ID for the customer. The Idempotency-Key makes a retry safe: see Idempotency.
The answer is 201 Created with the customer in provisioning (trimmed here):
{
"id": "cus_01jcz8w3k1x9q2v7s4e6m0b5n8",
"object": "customer",
"status": "provisioning",
"company_id": "boulangeriemartin",
"url": "https://boulangeriemartin.monotree.com",
"provisioning": { "step": "reserve", "step_label": "Reserving a place for the company", "steps_done": 0, "steps_total": 6, "failure_reason": null },
"seller": { "id": "sel_13", "name": "Emma Dubois", "external_ref": "usr_20503" },
"external_ref": "org_48213",
"sandbox": true
}5. Follow it to live
Wait for the customer.live event at your endpoint, or poll the customer every few seconds. You can use your own reference in place of its ID:
curl https://partners.monotree.com/api/v1/customers/external_ref:$EXTERNAL_REF \
-H "Authorization: Bearer $MONOTREE_TOKEN"When status is live, the setup is done. For a live customer the admin now has an invitation by email, and employees can download the Monotree app and enter the company ID. In the sandbox this takes about 40 seconds, and no email is sent.
Next
- Go live: create a Live token and run the same calls. Nothing else changes.
- Run everything from your own system: the whole integration, with a go-live checklist.
- Webhooks: check the signature of what your endpoint receives.
- The customer lifecycle: every state and what to do in it.
- Changing a customer: rename, new logo, more languages.