API reference
Sellers
The people at your company who sign up customers. Every customer is credited to one seller.
Base URL https://partners.monotree.com/api/v1
· every call needs a token
Endpoints
get/sellers
List sellers
post
/sellers
Add a seller
get
/sellers/{seller}
Get a seller
patch
/sellers/{seller}
Change a seller
post
/sellers/{seller}/invite
Invite a seller
post
/sellers/{seller}/reset-two-factor
Reset two-factor sign-in
List sellers
/sellers
customers:read Everyone at your company, admins and sellers, with what each brought in. Newest first by when they were added; lists cannot be sorted another way. A sandbox token lists test sellers only and a live token never lists them. See Sellers and attribution.
Parameters
limit
integer · query
default 25 · up to 100
cursor
string · query
next_cursor of the page before, for the next page. Send the same filters with it.
role
string · query
one of admin, seller
status
string · query
active, invited and api_only leave disabled people out.
one of active, invited, api_only, disabled
disabled
boolean · query
true for disabled people only, false to leave them out. 1 and 0 are read the same way.
q
string · query
email
string · query
external_ref
string · query
updated_since
string · query
updated_at is at or after this time, to keep a copy in step. updated_at also moves when the person signs in.
Response · 200 A page of sellers.
object
string
has_more
boolean
next_cursor
string, nullable
cursor for the next page.
data
array of objects
Errors
invalid_cursor: the cursor is not one this API gave out.
invalid_token: the token is missing, revoked or expired.
insufficient_ability: the token lacks the ability this call needs.
validation_error: a filter has a value that is not allowed, or limit is not 1 to 100.
rate_limited: too many requests. The general limit is 120 requests a minute for all your tokens of one mode (live or sandbox) together, and 300 a minute per IP address before the token is checked. Some calls have a lower limit of their own, which counts only calls that did what they ask (a call refused with another error uses up no place); the Rate limits guide lists them. Wait for the number of seconds in the Retry-After header.
curl https://partners.monotree.com/api/v1/sellers \
-H "Authorization: Bearer $MONOTREE_TOKEN"$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://partners.monotree.com/api/v1/sellers', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/sellers', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.MONOTREE_TOKEN}`,
},
});
const data = await response.json();import os
import requests
response = requests.get(
"https://partners.monotree.com/api/v1/sellers",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
)
data = response.json(){
"object": "list",
"data": [
{
"id": "sel_9",
"object": "seller",
"name": "Inès Roux",
"email": "ines@acme.example",
"role": "seller",
"external_ref": "usr_20777",
"status": "invited",
"can_login": true,
"disabled": false,
"two_factor": false,
"passkeys": 0,
"adoption_digest": true,
"live_customers": 0,
"employees": 0,
"signed_this_month": 0,
"invited_at": "2026-11-10T13:28:07Z",
"last_login_at": null,
"created_at": "2026-11-10T13:28:07Z",
"updated_at": "2026-11-10T13:28:07Z"
},
{
"id": "sel_5",
"object": "seller",
"name": "Emma Dubois",
"email": "emma@acme.example",
"role": "seller",
"external_ref": "usr_20503",
"status": "active",
"can_login": true,
"disabled": false,
"two_factor": true,
"passkeys": 0,
"adoption_digest": true,
"live_customers": 11,
"employees": 261,
"signed_this_month": 1,
"invited_at": "2026-03-12T13:28:06Z",
"last_login_at": "2026-11-14T12:41:59Z",
"created_at": "2026-03-12T13:28:06Z",
"updated_at": "2026-11-14T12:41:59Z"
}
],
"has_more": true,
"next_cursor": "6Yb0mT9wQ3F7ImlkIjo1fQ"
}
Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.
Add a seller
/sellers
sellers:write Adds a person and, unless invite is false, emails them an invitation to the portal. You never need this call to credit customers to someone: seller_ref on a new customer adds a seller without a login by itself. Adding an admin (role: admin) also needs the admins:write ability. An email address that is in use anywhere else answers 422 with one sentence that does not say where: the answer never tells whose an address is, and calls with invite: false are limited to 60 an hour. With a sandbox token a test seller is made: nobody is invited or emailed whatever invite says, and the answer has status: api_only.
Accepts an optional Idempotency-Key header to make a retry safe.
Request body
name
required
string
at least 2 characters · at most 80 characters
email
required
string
at most 120 characters
role
string
admin also needs the admins:write ability.
one of admin, seller · default seller
external_ref
string, nullable
at most 120 characters
invite
boolean
false the seller has no login (api_only) until you invite them. Never sent with a sandbox token.
default true
adoption_digest
boolean
false turns the Monday email about stalling customers off for them.
default true
Response · 201 The seller: `invited`, or `api_only` when `invite` is false or the token is a sandbox one.
id
string
object
string
name
string
email
string, nullable
role
string
one of admin, seller
external_ref
string, nullable
status
string
active has a password and signs in to the portal; invited was emailed an invitation and has no password yet; api_only is known from the API and has no login; disabled can no longer sign in.
one of active, invited, api_only, disabled
can_login
boolean
api_only, for a disabled person and for every test seller.
disabled
boolean
two_factor
boolean
security:read ability.
passkeys
integer
security:read ability.
adoption_digest
boolean
live_customers
integer
employees
integer
signed_this_month
integer
invited_at
string, nullable
last_login_at
string, nullable
security:read ability.
created_at
string
updated_at
string
updated_since filters on. Signing in does not move it.
Errors
invalid_idempotency_key: the Idempotency-Key is longer than 255 characters.
invalid_token: the token is missing, revoked or expired.
insufficient_ability: the token lacks sellers:write, or admins:write when role is admin.
idempotency_in_progress: a call with the same Idempotency-Key is still running.
validation_error: a field is missing or invalid, or the email address or reference is taken.
rate_limited: more than 30 sellers invited in an hour, or more than 60 added with invite: false in an hour (each counted for all your tokens of one mode together), or over the general limit. Wait for the number of seconds in Retry-After.
curl -X POST https://partners.monotree.com/api/v1/sellers \
-H "Authorization: Bearer $MONOTREE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Inès Roux",
"email": "ines@acme.example",
"external_ref": "usr_20777"
}'$client = new GuzzleHttp\Client();
$response = $client->request('POST', 'https://partners.monotree.com/api/v1/sellers', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
'json' => [
'name' => 'Inès Roux',
'email' => 'ines@acme.example',
'external_ref' => 'usr_20777',
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/sellers', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.MONOTREE_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"name": "Inès Roux",
"email": "ines@acme.example",
"external_ref": "usr_20777"
}),
});
const data = await response.json();import os
import requests
response = requests.post(
"https://partners.monotree.com/api/v1/sellers",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
json={
"name": "Inès Roux",
"email": "ines@acme.example",
"external_ref": "usr_20777"
},
)
data = response.json(){
"id": "sel_9",
"object": "seller",
"name": "Inès Roux",
"email": "ines@acme.example",
"role": "seller",
"external_ref": "usr_20777",
"status": "invited",
"can_login": true,
"disabled": false,
"two_factor": false,
"passkeys": 0,
"adoption_digest": true,
"live_customers": 0,
"employees": 0,
"signed_this_month": 0,
"invited_at": "2026-11-10T13:28:07Z",
"last_login_at": null,
"created_at": "2026-11-10T13:28:07Z",
"updated_at": "2026-11-10T13:28:07Z"
}
Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.
Get a seller
/sellers/{seller}
customers:read One person, by Monotree's ID (sel_5) or by your own reference (external_ref:usr_20503). A person of the other mode answers 404.
Parameters
seller
required
string · path
sel_5), or external_ref: followed by your own reference for them (external_ref:usr_20503). A seller added by an email address has no reference until you give them one.
Response · 200 The seller.
id
string
object
string
name
string
email
string, nullable
role
string
one of admin, seller
external_ref
string, nullable
status
string
active has a password and signs in to the portal; invited was emailed an invitation and has no password yet; api_only is known from the API and has no login; disabled can no longer sign in.
one of active, invited, api_only, disabled
can_login
boolean
api_only, for a disabled person and for every test seller.
disabled
boolean
two_factor
boolean
security:read ability.
passkeys
integer
security:read ability.
adoption_digest
boolean
live_customers
integer
employees
integer
signed_this_month
integer
invited_at
string, nullable
last_login_at
string, nullable
security:read ability.
created_at
string
updated_at
string
updated_since filters on. Signing in does not move it.
Errors
invalid_token: the token is missing, revoked or expired.
insufficient_ability: the token lacks the ability this call needs.
not_found: no such seller in the mode of the token.
rate_limited: too many requests. The general limit is 120 requests a minute for all your tokens of one mode (live or sandbox) together, and 300 a minute per IP address before the token is checked. Some calls have a lower limit of their own, which counts only calls that did what they ask (a call refused with another error uses up no place); the Rate limits guide lists them. Wait for the number of seconds in the Retry-After header.
curl https://partners.monotree.com/api/v1/sellers/sel_5 \
-H "Authorization: Bearer $MONOTREE_TOKEN"$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://partners.monotree.com/api/v1/sellers/sel_5', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/sellers/sel_5', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.MONOTREE_TOKEN}`,
},
});
const data = await response.json();import os
import requests
response = requests.get(
"https://partners.monotree.com/api/v1/sellers/sel_5",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
)
data = response.json(){
"id": "sel_5",
"object": "seller",
"name": "Emma Dubois",
"email": "emma@acme.example",
"role": "seller",
"external_ref": "usr_20503",
"status": "active",
"can_login": true,
"disabled": false,
"two_factor": true,
"passkeys": 0,
"adoption_digest": true,
"live_customers": 11,
"employees": 261,
"signed_this_month": 1,
"invited_at": "2026-03-12T13:28:06Z",
"last_login_at": "2026-11-14T12:41:59Z",
"created_at": "2026-03-12T13:28:06Z",
"updated_at": "2026-11-14T12:41:59Z"
}
Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.
Change a seller
/sellers/{seller}
sellers:write Changes only the fields you send: the name, email address, reference or role, invite to the portal, the Monday email, or disabled. A disabled person is signed out at once and cannot sign in; their customers stay as they are. Making someone an admin, and changing an admin's email address, role or disabled or inviting an admin, also needs the admins:write ability. So does changing the email address of anyone who has chosen a password (status: active), admin or seller: it is what they sign in with; of anyone who is invited (the invitation would follow the address); and of a seller who has customers. And so does invite: true for a seller who has customers and was never invited: whoever accepts sees those customers. With sellers:write alone a token gives an address to, and invites, a seller who has no customers yet. A call with email counts against the invitation limit of that seller (3 an hour) and 30 address changes an hour for all your sellers. When the address of someone who signs in changes, the old address gets an email saying so, the person is signed out everywhere and any password-reset link they asked for stops working. The last admin who can sign in cannot be disabled or made a seller (409 last_admin).
Parameters
seller
required
string · path
sel_5), or external_ref: followed by your own reference for them (external_ref:usr_20503). A seller added by an email address has no reference until you give them one.
Request body
name
string
at least 2 characters · at most 80 characters
email
string
admins:write.
at most 120 characters
role
string
admins:write, to make someone an admin or to make an admin a seller.
one of admin, seller
external_ref
string, nullable
null removes it. Changing or removing the reference of a seller who has customers, signs in or is invited also needs admins:write.
at most 120 characters
invite
boolean
true emails an invitation to someone who has no password yet. They need an email address, which may come in the same call. Someone who has a password answers 409 already_active, as Invite a seller does. Never sent with a sandbox token.
disabled
boolean
true signs the person out and keeps them out; false lets them back in. For an admin it also needs admins:write.
adoption_digest
boolean
false turns the Monday email about stalling customers off for them.
Response · 200 The seller after the change.
id
string
object
string
name
string
email
string, nullable
role
string
one of admin, seller
external_ref
string, nullable
status
string
active has a password and signs in to the portal; invited was emailed an invitation and has no password yet; api_only is known from the API and has no login; disabled can no longer sign in.
one of active, invited, api_only, disabled
can_login
boolean
api_only, for a disabled person and for every test seller.
disabled
boolean
two_factor
boolean
security:read ability.
passkeys
integer
security:read ability.
adoption_digest
boolean
live_customers
integer
employees
integer
signed_this_month
integer
invited_at
string, nullable
last_login_at
string, nullable
security:read ability.
created_at
string
updated_at
string
updated_since filters on. Signing in does not move it.
Errors
invalid_token: the token is missing, revoked or expired.
insufficient_ability: the token lacks sellers:write, or admins:write when the change makes someone an admin, changes an admin's email address, role or disabled, invites an admin, changes the email address of anyone who has chosen a password, or changes the external_ref of a seller who has customers, signs in or is invited.
not_found: no such seller in the mode of the token.
last_admin: this is the only admin who can sign in, so they cannot be disabled or made a seller. seller_disabled: invite was sent for a disabled seller. already_active: invite was sent for someone who has a password already.
validation_error: a field is invalid, an email address or reference is taken, or invite was sent for a seller without an email address.
rate_limited: more than 3 invitations in an hour for this seller (only calls with invite: true are counted), or over the general limit. Wait for the number of seconds in Retry-After.
curl -X PATCH https://partners.monotree.com/api/v1/sellers/sel_5 \
-H "Authorization: Bearer $MONOTREE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"disabled": true
}'$client = new GuzzleHttp\Client();
$response = $client->request('PATCH', 'https://partners.monotree.com/api/v1/sellers/sel_5', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
'json' => [
'disabled' => true,
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/sellers/sel_5', {
method: 'PATCH',
headers: {
Authorization: `Bearer ${process.env.MONOTREE_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"disabled": true
}),
});
const data = await response.json();import os
import requests
response = requests.patch(
"https://partners.monotree.com/api/v1/sellers/sel_5",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
json={
"disabled": True
},
)
data = response.json(){
"id": "sel_9",
"object": "seller",
"name": "Inès Roux",
"email": "ines@acme.example",
"role": "seller",
"external_ref": "usr_20777",
"status": "disabled",
"can_login": true,
"disabled": true,
"two_factor": false,
"passkeys": 0,
"adoption_digest": true,
"live_customers": 0,
"employees": 0,
"signed_this_month": 0,
"invited_at": "2026-11-10T13:28:07Z",
"last_login_at": null,
"created_at": "2026-11-10T13:28:07Z",
"updated_at": "2026-11-14T12:43:48Z"
}
Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.
Invite a seller
/sellers/{seller}/invite
sellers:write Emails the seller an invitation to the portal, or sends it again; the link in an earlier invitation stops working. The seller needs an email address (422 otherwise) and takes no request body. Inviting an admin also needs admins:write, and so does a first invitation to a seller who already has customers (one known from seller_ref, say): whoever accepts it sees those customers in the portal. Sending an invitation again to the address it went to needs sellers:write alone. With a sandbox token nothing is sent and the seller is returned unchanged.
Parameters
seller
required
string · path
sel_5), or external_ref: followed by your own reference for them (external_ref:usr_20503). A seller added by an email address has no reference until you give them one.
Accepts an optional Idempotency-Key header to make a retry safe.
Response · 200 The seller, with `status: invited` and a new `invited_at`.
id
string
object
string
name
string
email
string, nullable
role
string
one of admin, seller
external_ref
string, nullable
status
string
active has a password and signs in to the portal; invited was emailed an invitation and has no password yet; api_only is known from the API and has no login; disabled can no longer sign in.
one of active, invited, api_only, disabled
can_login
boolean
api_only, for a disabled person and for every test seller.
disabled
boolean
two_factor
boolean
security:read ability.
passkeys
integer
security:read ability.
adoption_digest
boolean
live_customers
integer
employees
integer
signed_this_month
integer
invited_at
string, nullable
last_login_at
string, nullable
security:read ability.
created_at
string
updated_at
string
updated_since filters on. Signing in does not move it.
Errors
invalid_idempotency_key: the Idempotency-Key is longer than 255 characters.
invalid_token: the token is missing, revoked or expired.
insufficient_ability: the token lacks sellers:write, or admins:write when the seller is an admin.
not_found: no such seller in the mode of the token.
already_active: the seller has chosen a password and can sign in. seller_disabled: a disabled seller cannot be invited.
validation_error on invite: the seller has no email address.
rate_limited: more than 3 invitations in an hour for this seller, or over the general limit. Wait for the number of seconds in Retry-After.
curl -X POST https://partners.monotree.com/api/v1/sellers/sel_5/invite \
-H "Authorization: Bearer $MONOTREE_TOKEN"$client = new GuzzleHttp\Client();
$response = $client->request('POST', 'https://partners.monotree.com/api/v1/sellers/sel_5/invite', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/sellers/sel_5/invite', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.MONOTREE_TOKEN}`,
},
});
const data = await response.json();import os
import requests
response = requests.post(
"https://partners.monotree.com/api/v1/sellers/sel_5/invite",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
)
data = response.json(){
"id": "sel_9",
"object": "seller",
"name": "Inès Roux",
"email": "ines@acme.example",
"role": "seller",
"external_ref": "usr_20777",
"status": "invited",
"can_login": true,
"disabled": false,
"two_factor": false,
"passkeys": 0,
"adoption_digest": true,
"live_customers": 0,
"employees": 0,
"signed_this_month": 0,
"invited_at": "2026-11-14T12:43:48Z",
"last_login_at": null,
"created_at": "2026-11-10T13:28:07Z",
"updated_at": "2026-11-14T12:43:48Z"
}
Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.
Reset two-factor sign-in
/sellers/{seller}/reset-two-factor
sellers:write For a person who lost their phone and their recovery codes. Turns their two-factor sign-in off, removes their passkeys and signs them out everywhere; they set two-factor sign-in up again the next time they sign in with their password, and get an email saying it was done through the API with the name of your token. Resetting an admin, or anyone who has chosen a password (status: active), also needs admins:write; in practice that is everyone with something to reset. A seller with nothing to reset is returned unchanged and gets no email. It takes no request body. See Security and sign-in.
Parameters
seller
required
string · path
sel_5), or external_ref: followed by your own reference for them (external_ref:usr_20503). A seller added by an email address has no reference until you give them one.
Accepts an optional Idempotency-Key header to make a retry safe.
Response · 200 The seller, with `two_factor` false and `passkeys` 0.
id
string
object
string
name
string
email
string, nullable
role
string
one of admin, seller
external_ref
string, nullable
status
string
active has a password and signs in to the portal; invited was emailed an invitation and has no password yet; api_only is known from the API and has no login; disabled can no longer sign in.
one of active, invited, api_only, disabled
can_login
boolean
api_only, for a disabled person and for every test seller.
disabled
boolean
two_factor
boolean
security:read ability.
passkeys
integer
security:read ability.
adoption_digest
boolean
live_customers
integer
employees
integer
signed_this_month
integer
invited_at
string, nullable
last_login_at
string, nullable
security:read ability.
created_at
string
updated_at
string
updated_since filters on. Signing in does not move it.
Errors
invalid_idempotency_key: the Idempotency-Key is longer than 255 characters.
invalid_token: the token is missing, revoked or expired.
insufficient_ability: the token lacks sellers:write, or admins:write when the seller is an admin or has chosen a password.
not_found: no such seller in the mode of the token.
idempotency_in_progress: a call with the same Idempotency-Key is still running.
idempotency_key_reused: the Idempotency-Key was used for a different request.
rate_limited: more than 5 resets in an hour for this seller, or over the general limit. Wait for the number of seconds in Retry-After.
curl -X POST https://partners.monotree.com/api/v1/sellers/sel_5/reset-two-factor \
-H "Authorization: Bearer $MONOTREE_TOKEN"$client = new GuzzleHttp\Client();
$response = $client->request('POST', 'https://partners.monotree.com/api/v1/sellers/sel_5/reset-two-factor', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/sellers/sel_5/reset-two-factor', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.MONOTREE_TOKEN}`,
},
});
const data = await response.json();import os
import requests
response = requests.post(
"https://partners.monotree.com/api/v1/sellers/sel_5/reset-two-factor",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
)
data = response.json(){
"id": "sel_5",
"object": "seller",
"name": "Emma Dubois",
"email": "emma@acme.example",
"role": "seller",
"external_ref": "usr_20503",
"status": "active",
"can_login": true,
"disabled": false,
"two_factor": false,
"passkeys": 0,
"adoption_digest": true,
"live_customers": 11,
"employees": 261,
"signed_this_month": 1,
"invited_at": "2026-03-12T13:28:06Z",
"last_login_at": "2026-11-14T12:41:59Z",
"created_at": "2026-03-12T13:28:06Z",
"updated_at": "2026-11-14T12:43:36Z"
}
Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.