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 -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.jsonWhat 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.