Consent and human steps
Some actions need a person: a signature, a card, consent to renewal terms, or a decision about money. Doing Work enforces this. Hosted-page operations return human_only (403) on the API and aren't MCP tools. Person-only operations refuse agent tokens with forbidden.
| Action | Who does it | What you do |
|---|---|---|
| auth.redeemLink | Hosted page only (a person does it in the browser) | Never call it yourself. The person's browser does this when they open the sign-in link. |
| media.requestCapture | Hosted page only (a person does it in the browser) | Never call it yourself. Used by the hosted camera page when a worker takes a photo in the browser. |
| jobs.confirm | Hosted page only (a person does it in the browser) | Never call it. The customer confirms or flags a problem on the hosted page. |
| quotes.sign | Hosted page only (a person does it in the browser) | Never call it. The customer signs on the hosted page after agreeing to sign electronically. |
| subcontractors.sign | Hosted page only (a person does it in the browser) | Never call it. The owner or office signs on the hosted page. |
| payments.connectStart | Hosted page only (a person does it in the browser) | Never call it. The owner connects their own Stripe account on the hosted page. |
| invoices.pay | Hosted page only (a person does it in the browser) | Never call it. The customer pays on the hosted page. |
| invoices.markPaidOutside | A person's own sign-in only (agent tokens are refused) | Agents can't call this. Tell the owner or office to record a cash, check, financing or insurance payment with their own sign-in. |
| invoices.refund | A person's own sign-in only (agent tokens are refused) | Agents can't call this. The owner or office refunds with their own sign-in. |
| webhooks.create | A person's own sign-in only (agent tokens are refused) | Agents can't call this. A developer adds an endpoint with their own sign-in. |
| platforms.grantManage | Hosted page only (a person does it in the browser) | Never call it. The shop owner allows a platform on the hosted page. |
| customers.privacyDelete | A person's own sign-in only (agent tokens are refused) | Erase a customer's personal details for a privacy request. Money and job records stay, unnamed. |
| quotes.respond | Hosted page only (a person does it in the browser) | Customer declines a quote or asks for changes (hosted page). Asking for changes needs a note and puts the quote back to draft for the shop to revise. |
| cards.resave | Hosted page only (a person does it in the browser) | Open the card saving page from a save-your-card-again email link (hosted page only). Returns the processor URL where the customer saves the card on the shop's current payments account. |
| keys.create | A person's own sign-in only (agent tokens are refused) | The owner makes a key for each agent they use, with a name they will recognize. The key is shown once and never again, so save it when it is made. |
| agents.approve | Hosted page only (a person does it in the browser) | Hosted claim page only: the shop owner whose email the claim names types the agent's 6 digit code, picks one of their shops and accepts the agent key terms. Makes a named agent key for that shop. |
| agents.deny | Hosted page only (a person does it in the browser) | Hosted claim page only: the person turns the agent down. The registration closes and the agent's poll gets access_denied. |
| members.setPermissions | A person's own sign-in only (agent tokens are refused) | Owner only, not an agent: turn a worker's permissions on or off. Give only the flags to change (see_prices, see_costs, take_money, delete, manage_schedule). |
| legal.accept | A person's own sign-in only (agent tokens are refused) | Record that the signed-in person accepts the current version of a legal document (clickwrap). The person does this themselves; an agent cannot accept for them. |
| signatures.sign | Hosted page only (a person does it in the browser) | Ask a customer, or someone in the shop, to sign a document: contract text you supply (for example a service agreement) or a PDF already stored on the job. signatures.request returns a sign_url on the hosted pages; send it to the signer yourself. |
| shops.transferStart | Hosted page only (a person does it in the browser) | Start handing the shop to a current worker (owner, on a hosted page). They accept on their own hosted page within 14 days, and ownership moves at once. |
| shops.transferAccept | Hosted page only (a person does it in the browser) | Accept a hand-off and become the shop's owner (the person asked, on a hosted page). The person agrees to the Terms of Service by ticking a box (accept_terms_version); the record keeps the version, time, IP address and browser. |
| shops.close | Hosted page only (a person does it in the browser) | Close the shop for good (owner, on a hosted page, typing the shop name). Everyone loses access, agent connections and webhooks stop, every customer link stops working, and the payments account only settles what is in flight. |
| shops.reopen | Hosted page only (a person does it in the browser) | Reopen a closed shop (only the owner who closed it, on a hosted page, within 90 days of closing). You come back as owner. |
| subs.view | Hosted page only (a person does it in the browser) | The subcontractor's page for one job: the shop, job summary, work address, scope note, upcoming visit times and their notes. state is ok, gone (removed, expired, job cancelled or shop closed) or wrong_person (signed in with a different email, or someone else opened it first). |
| subs.addNote | Hosted page only (a person does it in the browser) | Leave a note for the shop on this job, as the subcontractor (up to 20 a day). Hosted page only. |
| hub.view | Hosted page only (a person does it in the browser) | Give a customer one page with everything they have with the shop: hub.createLink makes a link for one customer (shown once; send it yourself, Doing Work sends nothing). On it the customer sees their quotes, jobs, invoices with what is still owed, upcoming visits and requests, opens a quote, pays an invoice, asks to move or cancel a visit, and asks for new work (it arrives as a portal request). |
| hub.open | Hosted page only (a person does it in the browser) | Give a customer one page with everything they have with the shop: hub.createLink makes a link for one customer (shown once; send it yourself, Doing Work sends nothing). On it the customer sees their quotes, jobs, invoices with what is still owed, upcoming visits and requests, opens a quote, pays an invoice, asks to move or cancel a visit, and asks for new work (it arrives as a portal request). |
| hub.requestVisitChange | Hosted page only (a person does it in the browser) | Give a customer one page with everything they have with the shop: hub.createLink makes a link for one customer (shown once; send it yourself, Doing Work sends nothing). On it the customer sees their quotes, jobs, invoices with what is still owed, upcoming visits and requests, opens a quote, pays an invoice, asks to move or cancel a visit, and asks for new work (it arrives as a portal request). |
| hub.withdrawVisitChange | Hosted page only (a person does it in the browser) | Give a customer one page with everything they have with the shop: hub.createLink makes a link for one customer (shown once; send it yourself, Doing Work sends nothing). On it the customer sees their quotes, jobs, invoices with what is still owed, upcoming visits and requests, opens a quote, pays an invoice, asks to move or cancel a visit, and asks for new work (it arrives as a portal request). |
| hub.requestWork | Hosted page only (a person does it in the browser) | Give a customer one page with everything they have with the shop: hub.createLink makes a link for one customer (shown once; send it yourself, Doing Work sends nothing). On it the customer sees their quotes, jobs, invoices with what is still owed, upcoming visits and requests, opens a quote, pays an invoice, asks to move or cancel a visit, and asks for new work (it arrives as a portal request). |
| approvals.setRule | A person's own sign-in only (agent tokens are refused) | An owner can say which actions an agent must ask about first, optionally only above an amount. When a rule matches, your call returns an approval id instead of running. |
| approvals.removeRule | A person's own sign-in only (agent tokens are refused) | An owner can say which actions an agent must ask about first, optionally only above an amount. When a rule matches, your call returns an approval id instead of running. |
| approvals.decide | A person's own sign-in only (agent tokens are refused) | An owner can say which actions an agent must ask about first, optionally only above an amount. When a rule matches, your call returns an approval id instead of running. |
Rules
- Never try another route around a refusal. Send the link or ask the person.
- Never tick a consent box, sign, or enter a card for someone.
- Say what the person is agreeing to before you send the link, for example the quote total and the e-sign consent.