Get started

Sandbox and testing

Build and test your integration against the sandbox. It behaves like live, step by step, without setting anything up for real.

What the sandbox is

Your company has a sandbox next to its live data: a test copy of your account. Which one a call reaches is decided by the token alone. A call made with a sandbox token (mpt_test_…) creates test customers that:

  • go through the same states, steps and events as live ones, in about 40 seconds;
  • never reach Monotree's platform: no company is set up, no email goes to the admin;
  • are kept apart from live data: they are not in the portal's lists, the statistics or the monthly statement;
  • have their own webhook endpoints, events, tokens, sellers, support desk and external_refs, separate from the live ones.

In the sandbox, Monotree's part is played for you. A new customer is walked through the setup steps, and every change, suspend, resume and resent invitation is answered as done a few seconds later (customer.applied follows a PATCH). A sandbox customer cancelled 30 days ago is deleted by the same daily run as a live one, with a customer.deleted event.

What each area does in the sandbox

Area In the sandbox
Customers The full lifecycle, in about 40 seconds from create to live. A company ID only competes with your own sandbox customers. The sandbox holds at most 500 customers that are not cancelled or deleted (409 limit_reached above that): cancel the ones you are done with.
Sellers Test sellers, kept apart from your real people. They never sign in and are never emailed: inviting one answers 200 and sends nothing, and seller.invited is never sent. See Sellers and attribution.
Statistics Made-up numbers, written every morning at 04:30 UTC. A new customer has its first numbers the morning after it went live. See Statistics and adoption.
Adoption alerts Raised by the same rules as live, at 05:00 UTC, on the made-up numbers.
Statement Counts your sandbox customers, by the same rules as live.
Support A desk of its own. Nobody writes to it, so you simulate a customer's message. Answers are marked delivered at once and never leave, escalations never reach Monotree, and the assistant's drafts are scripted. See The support desk.
Security The lists of people and sign-ins are always empty: test sellers never sign in.
Webhooks Real deliveries to your sandbox endpoints, signed and retried as live.
Tokens A sandbox token lists, creates and revokes sandbox tokens only.

Nothing fails in the sandbox by itself: customer.apply_failed is never sent, and a setup only stops when you ask for it as below.

Making things happen on purpose

Do this To see
Use a company ID that starts with fail, such as failtest The setup stops at the second step with status: failed, a failure_reason and a customer.failed event. To see a recovery: change the company ID with a PATCH to one that does not start with fail, then call Retry a failed setup.
Use a company ID that starts with stall, such as stalltest, with 10 employees or more A customer whose employees do not sign in. The morning after it goes live (the check runs at 05:00 UTC) it has an adoption alert with the reason activation and an adoption.alert.raised event, without the 14 days a customer is normally given first.
Check a company ID that starts with taken, such as takentest available: false with reason: taken and a suggestion that adds a number, such as takentest2. An ID that starts with taken and ends in a digit is free, so the suggestion can be used.
Check a company ID with a hyphen, such as le-petit-bistrot available: false with reason: invalid and the suggestion lepetitbistrot.
Send the same Idempotency-Key twice The second answer is the first one, with the header Idempotent-Replayed: true.
Send the same key with a different body 422 with the type idempotency_key_reused.
Leave out terms_accepted 422 with a field error.
Create two customers with the same external_ref 422 on the second.
DELETE a customer twice 200 both times, with the cancelled customer.
Call Rotate the signing secret, then Send a test event A Monotree-Signature with two v1 values.
Simulate a customer's message A support thread, with the support.thread.created and support.message.received events.

Trying calls from the documentation

Every endpoint in the reference has a Try it panel. Paste a sandbox token and send the call from the page. The panel only accepts sandbox tokens: the API refuses a live token for calls from the documentation with 403 sandbox_only. The token stays in that browser tab and is gone when you close it.

The Downloads in the menu have the whole API as an OpenAPI 3.1 file and as a Postman collection.

Testing webhooks locally

  1. Run a tunnel to your machine (for example ngrok http 3000 or cloudflared tunnel).
  2. Add the tunnel's URL as a sandbox endpoint with a sandbox token.
  3. Press Test in Developers, or call Send a test event: a ping event arrives at once.
  4. Create a sandbox customer and watch customer.created, customer.provisioning, customer.step and customer.live arrive.
  5. Stop your server, change the customer, start it again and read what it missed with List events and after.

The tunnel's address must be a public https one: an endpoint whose host leads to a private or loopback address is refused.

Going live

Nothing in your code changes except the token. Create a live token with the same abilities, add your live webhook endpoint (it has its own signing secret), and switch. The go-live checklist has the rest.