Conventions

Idempotency

Send a POST twice and it is done once. Required when creating a customer, optional on most other POSTs.

A network can fail after Monotree created a customer but before you got the answer. Without protection, your retry would create a second one. With an Idempotency-Key, the retry gets the first answer instead. Idempotent means just that: doing it twice has the same effect as doing it once.

How to use it

Send a unique key, such as a UUID, in the Idempotency-Key header. Make a new key for every new request and reuse it only for retries of that request.

cURL
curl -X POST https://partners.monotree.com/api/v1/customers \
  -H "Authorization: Bearer $MONOTREE_TOKEN" \
  -H "Idempotency-Key: 6f1c2a3e-8b4d-4f7a-9c2e-1d5b7a9e3f10" \
  -H "Content-Type: application/json" \
  -d @customer.json

What happens

You send You get
A new key The call runs and its answer is kept for 24 hours
The same key with the same method, path and body The kept answer, status code included, with the header Idempotent-Replayed: true. Nothing runs again.
The same key with a different method, path or body 422 idempotency_key_reused
The same key from another of your tokens 409 idempotency_key_taken: a kept answer is only given to the token that made the call, as it can hold a new token or a signing secret
The same key while the first call is still running 409 idempotency_in_progress; retry in a moment
A key longer than 255 characters 400 invalid_idempotency_key

A key is kept per company and mode (live or sandbox) for 24 hours, and belongs to the token that sent it: retry with the same token. Every answer below 500 is kept, errors too: a call that answered 422 answers 422 again with the same key, so fix the request and send it with a new key. A call that failed with a 5xx is not kept, so a retry with the same key runs again; neither is a 429, so the same key goes through once you have waited. If the first call never finished at all (it is rare: a crash on our side), its key answers 409 idempotency_in_progress for five minutes and then lets the retry run.

The kept answer is stored encrypted, as it can hold a new token or signing secret, and is deleted after 24 hours.

Where it is needed

Required: Create a customer. Without the header it answers 400 idempotency_key_required.

Optional, and worth sending: the POST calls that make or send something. The reference says "Accepts an optional Idempotency-Key" on each.

Area Calls
Customers submit, suspend, resume, retry, resend the admin invitation
Sellers add, invite, reset two-factor sign-in
Webhooks add an endpoint, send a test event, rotate the signing secret, redeliver one delivery, redeliver the failed ones
Tokens create
Support start a thread, merge two threads, answer, send a failed answer again, add a note, ask for a draft, send a draft, close a thread on a draft, escalate, follow up an escalation, set the presence, teach the assistant, simulate a message (sandbox)

GET, PATCH and DELETE never take a key and are safe to repeat as they are: a PATCH sets values, and a DELETE of a customer that is already cancelled changes nothing (200 with the customer). Deleting a webhook endpoint or token that is already gone answers 404.