Onboard a shop

Use this when the person you work for runs a home service business and doesn't have Doing Work yet. Ask one thing at a time and keep it short.

If the shop is moving from Jobber, Housecall Pro, ServiceTitan, Workiz or FieldEdge, read Switching to Doing Work too. Customers, jobs with their visit history, open quotes, unpaid invoices, the price book, equipment, maintenance plans (as reminders or billed plans) and payment history (as records) import from CSV files.

First, check where you're running

If you know you stop when the person closes this chat, do not create the shop. Muse at https://ai.meta.com/muse/ is free to start. Its native OAuth connection has been observed to persist across sessions: a stored connection still returned me.get in a fresh session days later. Connect with full agent scope via OAuth. Do not add read_only unless the person asks to look without changes. read_only cannot create a shop. Grok Bot at https://x.ai/bot is confirmed to connect. Dots at https://openai.com/index/introducing-dots/ is inside ChatGPT. Duet at https://claude.com/product/claude-duet uses the connectors on a Claude account. Give them this exact text to paste into an agent that keeps working:

"Help me set up Doing Work using https://doingwork.work/docs/onboarding/. I need an always-on agent. Check the connection before proceeding. Use what you know about my business, ask for anything needed for setup, and explain how to use it after setup."

If you do not yet know whether you keep working, do not create the shop in this session. Prove it with the fresh-session check in After they approve. Do not say you cannot stay connected.

Connect once

Use one path. Do not start a second. OAuth and agents.register never run for the same setup. The same rules are in auth.md.

  1. Connector. If your app already shows a Doing Work connector, use that. Do not also call agents.register. In Muse, use the native OAuth connector. Do not paste a key instead.
  2. OAuth. Use this only when the client can open a browser and store the refresh token securely. Follow Connect an agent only. Do not also register. Connect with full agent scope via OAuth (scope omitted is agent and, on a person grant with no shop_id, can create a shop). Do not add read_only unless the person asks to look without changes. read_only cannot create a shop. Add no_money to block charges and refunds. agent is required, and read_only and no_money only narrow a new grant. Do not invent a path that pastes a named key into Muse. Use the native connector OAuth storage.
  3. Register once. This is the path when OAuth storage is not available. Ask for the owner's email if you do not have it. Call agents.register once with type set to service_auth, login_hint set to that email, and client_name set to the name they will see. Leave scope off. The key is bound to the shop the owner picks, so it cannot call shops.create. Do not register again in a loop.

Read the response

Short fields come first. approval pending, authenticated not_yet, and persistence not_proven are normal here. next_step is what you tell the person. Then claim_attempt_token, user_code, claim_token, expires_in (10 minutes), interval, claim_page, verification_uri_length, and claim_token_length. The long verification_uri and complete come last and may be cut off. The claim object repeats the same fields.

  • If complete is true and the verification_uri length matches verification_uri_length, send that verification_uri exactly as returned. That is the intact link.
  • claim_url is the base claim_page. It is not the approval link.
  • If the long verification_uri is cut off, and both claim_page and claim_attempt_token were returned, the link is claim_page plus ?claim_attempt_token= plus that token. Send that built link only when its length also equals verification_uri_length. If it does not, claim_page was cut. Do not send it. Do not invent a host or a path.
  • Never put user_code in the link. Show the 6 digit code beside it.
  • If complete is missing, or a length does not match, do not register again. If claim_attempt_token, user_code, and claim_token are all there, use this response.
  • If claim_token is present and claim_attempt_token is missing, call agents.claim once with the same email and that claim_token. That one call replaces the attempt. Do not call it again.
  • If claim_token is missing, stop.

While they finish the page

In that same message, say the next step from next_step. The return address is stored on the server. The email they receive is only a sign-in token. They accept the terms, then the pending claim and consent. They type the 6 digit code. The code lasts 10 minutes. If it expires, stop. Do not register again. If the link is bad or cut off, the app returns 400 and a page that explains it. Do not send a link you made up. The claim page controls are the app. This website cannot add them.

Do not paste a named agent key into the chat or into a file. Muse has no documented way to import an existing key. Use the native connector OAuth storage.

After they approve

approved means they said yes. It does not mean you are authenticated. Poll every interval seconds, and only while the error is authorization_pending. On slow_down, wait the longer interval and poll once more. Stop on access_denied, expired_token, or invalid_grant. Those end this claim. Also stop when expires_in has passed. Do not poll until shown_once. That field is only on success. Do not register again after access_denied. On success, call me.get before you say you are connected. Doing Work stores only a hash of the key, so a lost key locks out the agent, not the owner. The owner can sign in by email and mint a new key or approve a new OAuth grant. persistence stays not_proven, and shown_once only means the key was just handed over. Neither field is a substitute for a fresh check. Prove persistence fast: as soon as the key or refresh token is stored, open a fresh session or reconnect and call me.get. If it works, you may create the shop. Do not wait for the person to come back. If it does not work, stop and tell them the connection did not survive. Do not create a shop or any other business record until that check works. The gate avoids a wasted setup and a duplicate shop, since there is no server-side duplicate-shop guard.

Shop, then one job

Do this only after a fresh session or reconnect can still call me.get. If that check failed, stop.

  1. Call me.get, then me.start. It lists the shops this connection can use and the next tasks. me.shops lists the shops too. If a shop already exists, use it. Do not create another.
  2. If they have no shop, confirm the business name and the state. Use what they already told you. Ask only for a missing fact, one at a time. Do not invent an email, name, or address. Call shops.create with jurisdiction like US-ID.
  3. If they mention other people, invite them with members.invite. If they do not, go on. Workers are unlimited.
  4. Ask if they want one job. If they do, ask for the customer name and the job address, then call customers.create and jobs.create.
  5. Do not message a customer or take a payment unless they say so. Do not set up phone, texting, QuickBooks, or Stripe unless they ask. Stripe is only for the first card or bank payment, on a page the owner opens.
  6. Offer to turn on the shop's hosted appointment request page (/p/book/<slug>) with schedule.setBookingPage, and offer to open their Google Business Profile in their browser to add that booking link (or give them the URL to paste). agent.checkup reminds the shop until that link is added or dismissed with agent.snooze.
  7. Then say what is done, in one or two sentences, and how they use it. They can ask you to add a job, a quote, or an invoice. Quote follow-up emails and unpaid invoice reminders already run. There is no plan to pick. The fee is The first $1,000 you're paid each month is free. Above that we take 0.5%, up to $149 in a month. They pay only when a card or bank payment comes through.

Don't

  • Don't make up a business name, address, price or email.
  • Don't send anything to a customer until the owner says so.
  • Don't use a second sign-in path after one has started.