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

List sellers

get /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

How many to return in a page, 1 to 100.

default 25 · up to 100

cursor

string · query

The next_cursor of the page before, for the next page. Send the same filters with it.

role

string · query

Only admins, or only sellers.

one of admin, seller

status

string · query

Only people in this status. 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

People whose name, email address or reference contains this text.

email

string · query

Only the person with exactly this email address. Capitals do not matter.

external_ref

string · query

Only the person with exactly this reference of yours.

updated_since

string · query

Only people whose 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

Whether there is a page after this one.

next_cursor

string, nullable

Pass as cursor for the next page.

data

array of objects

Errors

400 invalid_cursor: the cursor is not one this API gave out.
401 invalid_token: the token is missing, revoked or expired.
403 insufficient_ability: the token lacks the ability this call needs.
422 validation_error: a filter has a value that is not allowed, or limit is not 1 to 100.
429 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"
200 · Response
{
    "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.

Sending…

                    

Add a seller

post /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

Where the invitation goes and what they sign in with. No two people can have the same one.

at most 120 characters

role

string

admin also needs the admins:write ability.

one of admin, seller · default seller

external_ref

string, nullable

Your own ID for the person. No two of your sellers can have the same one.

at most 120 characters

invite

boolean

Email an invitation to the portal. With 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

Monotree's ID for the person.

object

string

name

string

email

string, nullable

Null for a seller known only by your reference.

role

string

An admin sees every customer of your company and manages people; a seller sees the customers they signed.

one of admin, seller

external_ref

string, nullable

Your own ID for the person. Null when you never gave one.

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

Whether the person can sign in to the portal: invited at some time and not disabled. False for api_only, for a disabled person and for every test seller.

disabled

boolean

True when the person was disabled.

two_factor

boolean

Whether two-factor sign-in is set up. Only present when the token has the security:read ability.

passkeys

integer

How many passkeys they have. Only present when the token has the security:read ability.

adoption_digest

boolean

Whether they get the Monday email about customers that stall.

live_customers

integer

Customers credited to them that are live or suspended.

employees

integer

The employees of those customers.

signed_this_month

integer

Customers of theirs submitted since the first of this month (UTC), whatever became of them.

invited_at

string, nullable

When the last invitation was emailed. Null when none was.

last_login_at

string, nullable

Their last sign-in to the portal. Null when they never signed in. Only present when the token has the security:read ability.

created_at

string

updated_at

string

When the person last changed: what updated_since filters on. Signing in does not move it.

Errors

400 invalid_idempotency_key: the Idempotency-Key is longer than 255 characters.
401 invalid_token: the token is missing, revoked or expired.
403 insufficient_ability: the token lacks sellers:write, or admins:write when role is admin.
409 idempotency_in_progress: a call with the same Idempotency-Key is still running.
422 validation_error: a field is missing or invalid, or the email address or reference is taken.
429 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"
}'
201 · Response
{
    "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.

Sending…

                    

Get a seller

get /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

The seller's ID (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

Monotree's ID for the person.

object

string

name

string

email

string, nullable

Null for a seller known only by your reference.

role

string

An admin sees every customer of your company and manages people; a seller sees the customers they signed.

one of admin, seller

external_ref

string, nullable

Your own ID for the person. Null when you never gave one.

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

Whether the person can sign in to the portal: invited at some time and not disabled. False for api_only, for a disabled person and for every test seller.

disabled

boolean

True when the person was disabled.

two_factor

boolean

Whether two-factor sign-in is set up. Only present when the token has the security:read ability.

passkeys

integer

How many passkeys they have. Only present when the token has the security:read ability.

adoption_digest

boolean

Whether they get the Monday email about customers that stall.

live_customers

integer

Customers credited to them that are live or suspended.

employees

integer

The employees of those customers.

signed_this_month

integer

Customers of theirs submitted since the first of this month (UTC), whatever became of them.

invited_at

string, nullable

When the last invitation was emailed. Null when none was.

last_login_at

string, nullable

Their last sign-in to the portal. Null when they never signed in. Only present when the token has the security:read ability.

created_at

string

updated_at

string

When the person last changed: what updated_since filters on. Signing in does not move it.

Errors

401 invalid_token: the token is missing, revoked or expired.
403 insufficient_ability: the token lacks the ability this call needs.
404 not_found: no such seller in the mode of the token.
429 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"
200 · Response
{
    "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.

Sending…

                    

Change a seller

patch /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

The seller's ID (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

Changing it makes an invitation link sent earlier stop working. For an admin it also needs admins:write.

at most 120 characters

role

string

Also needs 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

Monotree's ID for the person.

object

string

name

string

email

string, nullable

Null for a seller known only by your reference.

role

string

An admin sees every customer of your company and manages people; a seller sees the customers they signed.

one of admin, seller

external_ref

string, nullable

Your own ID for the person. Null when you never gave one.

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

Whether the person can sign in to the portal: invited at some time and not disabled. False for api_only, for a disabled person and for every test seller.

disabled

boolean

True when the person was disabled.

two_factor

boolean

Whether two-factor sign-in is set up. Only present when the token has the security:read ability.

passkeys

integer

How many passkeys they have. Only present when the token has the security:read ability.

adoption_digest

boolean

Whether they get the Monday email about customers that stall.

live_customers

integer

Customers credited to them that are live or suspended.

employees

integer

The employees of those customers.

signed_this_month

integer

Customers of theirs submitted since the first of this month (UTC), whatever became of them.

invited_at

string, nullable

When the last invitation was emailed. Null when none was.

last_login_at

string, nullable

Their last sign-in to the portal. Null when they never signed in. Only present when the token has the security:read ability.

created_at

string

updated_at

string

When the person last changed: what updated_since filters on. Signing in does not move it.

Errors

401 invalid_token: the token is missing, revoked or expired.
403 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.
404 not_found: no such seller in the mode of the token.
409 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.
422 validation_error: a field is invalid, an email address or reference is taken, or invite was sent for a seller without an email address.
429 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
}'
200 · Response
{
    "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.

Sending…

                    

Invite a seller

post /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

The seller's ID (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

Monotree's ID for the person.

object

string

name

string

email

string, nullable

Null for a seller known only by your reference.

role

string

An admin sees every customer of your company and manages people; a seller sees the customers they signed.

one of admin, seller

external_ref

string, nullable

Your own ID for the person. Null when you never gave one.

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

Whether the person can sign in to the portal: invited at some time and not disabled. False for api_only, for a disabled person and for every test seller.

disabled

boolean

True when the person was disabled.

two_factor

boolean

Whether two-factor sign-in is set up. Only present when the token has the security:read ability.

passkeys

integer

How many passkeys they have. Only present when the token has the security:read ability.

adoption_digest

boolean

Whether they get the Monday email about customers that stall.

live_customers

integer

Customers credited to them that are live or suspended.

employees

integer

The employees of those customers.

signed_this_month

integer

Customers of theirs submitted since the first of this month (UTC), whatever became of them.

invited_at

string, nullable

When the last invitation was emailed. Null when none was.

last_login_at

string, nullable

Their last sign-in to the portal. Null when they never signed in. Only present when the token has the security:read ability.

created_at

string

updated_at

string

When the person last changed: what updated_since filters on. Signing in does not move it.

Errors

400 invalid_idempotency_key: the Idempotency-Key is longer than 255 characters.
401 invalid_token: the token is missing, revoked or expired.
403 insufficient_ability: the token lacks sellers:write, or admins:write when the seller is an admin.
404 not_found: no such seller in the mode of the token.
409 already_active: the seller has chosen a password and can sign in. seller_disabled: a disabled seller cannot be invited.
422 validation_error on invite: the seller has no email address.
429 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"
200 · Response
{
    "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.

Sending…

                    

Reset two-factor sign-in

post /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

The seller's ID (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

Monotree's ID for the person.

object

string

name

string

email

string, nullable

Null for a seller known only by your reference.

role

string

An admin sees every customer of your company and manages people; a seller sees the customers they signed.

one of admin, seller

external_ref

string, nullable

Your own ID for the person. Null when you never gave one.

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

Whether the person can sign in to the portal: invited at some time and not disabled. False for api_only, for a disabled person and for every test seller.

disabled

boolean

True when the person was disabled.

two_factor

boolean

Whether two-factor sign-in is set up. Only present when the token has the security:read ability.

passkeys

integer

How many passkeys they have. Only present when the token has the security:read ability.

adoption_digest

boolean

Whether they get the Monday email about customers that stall.

live_customers

integer

Customers credited to them that are live or suspended.

employees

integer

The employees of those customers.

signed_this_month

integer

Customers of theirs submitted since the first of this month (UTC), whatever became of them.

invited_at

string, nullable

When the last invitation was emailed. Null when none was.

last_login_at

string, nullable

Their last sign-in to the portal. Null when they never signed in. Only present when the token has the security:read ability.

created_at

string

updated_at

string

When the person last changed: what updated_since filters on. Signing in does not move it.

Errors

400 invalid_idempotency_key: the Idempotency-Key is longer than 255 characters.
401 invalid_token: the token is missing, revoked or expired.
403 insufficient_ability: the token lacks sellers:write, or admins:write when the seller is an admin or has chosen a password.
404 not_found: no such seller in the mode of the token.
409 idempotency_in_progress: a call with the same Idempotency-Key is still running.
422 idempotency_key_reused: the Idempotency-Key was used for a different request.
429 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"
200 · Response
{
    "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.

Sending…