Seasonly API

The owner makes one in Seasonly under Settings, AI & API. Pick what it may do and how long it lasts (7, 30 or 90 days, 1 year, or never). The key is shown once. Send it on every call:

Authorization: Bearer ss_mcp_...

A key can only call the tools its permissions allow. Only an owner's key can change anything. The areas are the rows of the key table in Settings, each with a See permission, a Change permission or both.

• Campaignscampaigns:readSee your campaigns and their resultscampaigns:writeCreate, edit and end campaigns
• Saved lists and service areaaudiences:readSee saved customer lists, customer counts and your service areaaudiences:writeCreate, change and delete saved customer lists, and set the service area your booking form checks addresses against
• Customer detailscustomers:readSee customer names, addresses and contact detailscustomers:writeRemove customers from Seasonly and put them back (Homeworks is not changed)
• Requestsrequests:readSee booking requestsrequests:writeAct on booking requests: mark not real, retry, measure, size, price and send estimates
• Booking formform:readSee your booking form settings and servicesform:writeBuild your booking form (its services, questions, branding, pages and switches), put it live or switch it off, and change how it prices
• Pricespricing:readSee your pricespricing:writeChange your prices
• Scheduleschedule:readSee your schedule, scheduling rules and activityschedule:writeMove, assign, complete, skip and book visits in Homeworks
• Schedule rules and time zoneschedule_rules:writeChange your scheduling rules and your company time zone
• Who is on a listhandoff:readSee exactly who is on a saved list (nothing is tagged)
• Tagging in Homeworkstags:readSee who a campaign would tag in Homeworks and how tagging wenttags:writeTag campaign customers in Homeworks, or take Seasonly's tags off
• Follow-upsfollow_ups:readSee campaign follow-ups and what they didfollow_ups:writeAdd, change, pause and remove campaign follow-ups
• Lawn measuringmeasure:readSee your Clarity Measure connection and lawn measurementsmeasure:writeMeasure a lawn with Clarity Measure, which uses paid credit
• Company settingssettings:readSee your company, estimate and measuring settingssettings:writeChange your company, estimate and Clarity Measure settings (the risky ones wait for your approval in Seasonly)
• Web address and domainswebsite:writeChange your booking form web address and add or remove your own domains

Every tool is one address. The body is the tool's arguments as JSON, and the answer is JSON.

POST https://app.useseasonly.com/api/v1/tools/<tool>
Content-Type: application/json

Reads change nothing. A change answers first with a dry run and a previewToken. Send the same body again with "confirm": true and that token within ten minutes; it works once. A change that writes to Homeworks, spends money, changes the live form or cannot be undone then answers with an approval link: the owner opens it and presses Approve, and you send the same body with the approvalId.

The owner can also trust one key or connected app for 1, 7 or 30 days. While it is trusted, changes to the live form and its prices, and lawn sizes on Homeworks properties, apply on confirm with no approval link. Everything else still waits for Approve. Only the owner, signed in to Seasonly, can trust a connection or stop trusting it.

Every tool, its arguments and what each one means, generated from the same checks the server runs. Import it into Postman or Retool, or generate a client from it.

GET https://app.useseasonly.com/api/v1/openapi.json

The Referrals page is also one GET, for a dashboard that only reads. It answers exactly what the seasonly_list_referrals tool does, with the same key and the customers:read permission. Query parameters: status, limit (1 to 100) and before (the nextBefore of the previous page). Any other parameter is refused. While referrals are not turned on for the account it answers 404 with a sentence saying so.

GET https://app.useseasonly.com/api/v1/referrals?status=owed&limit=50

Every error is JSON with an error sentence you can show a person.

• 400The arguments were not valid, or a rule refused them. The error says why, naming each argument that is wrong.
• 401No key, or the key or connection expired or was revoked. An expired access token says so: refresh it and try again.
• 403The key lacks a permission, or the change needs the owner. On Free the body also has "code": "premium_required" and an upgradeUrl: AI & API is part of Premium, and the key works again once the company upgrades.
• 404No tool with that name, the tool is not turned on for this account, or the record is not in this company.
• 409The change conflicts with what is there now, or the preview is stale. The error says what to do.
• 413The request or the answer was too large. Narrow the request.
• 415The body was not JSON. Send Content-Type: application/json.
• 429Too many calls. Wait for the Retry-After seconds.
• 503AI & API is switched off, or Seasonly could not finish the call just now. Try again later.

The same tools are served to assistants at https://app.useseasonly.com/api/mcp. Add it as a custom connector and sign in with Seasonly; the owner picks the permissions on the consent screen.

Your own app can sign in the same way instead of using a key: OAuth 2.1 with PKCE (S256) and dynamic client registration, described at https://app.useseasonly.com/.well-known/oauth-authorization-server. Ask for the resource https://app.useseasonly.com/api/v1: a token issued for the assistants' address is refused by the API, and the other way round.

Money is in whole cents. Dates are YYYY-MM-DD on the company's own calendar. Text a homeowner typed comes back wrapped as {"untrustedText": "..."}. Each key or connection may make 120 calls a minute (a staff member's read-only connection 60), and each company 300. Reads that load the whole customer list or an audience are limited to 30 a minute per key and 60 per company: filter instead of paging through everything.