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.

cURL
export MONOTREE_TOKEN=mpt_test_…

Check it with Who am I:

cURL
curl https://partners.monotree.com/api/v1/partner \
  -H "Authorization: Bearer $MONOTREE_TOKEN"
JSON
{
  "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
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.

cURL
export COMPANY_ID=boulangeriemartin$RANDOM
export EXTERNAL_REF=org_$RANDOM
cURL
curl https://partners.monotree.com/api/v1/company-ids/$COMPANY_ID \
  -H "Authorization: Bearer $MONOTREE_TOKEN"
JSON
{ "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
  }'

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):

JSON
{
  "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
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