Pulse Connect API
Pulse Connect is MaidCentral's API for connecting approved software, command-line tools, MCP servers and AI assistants to one branch's Pulse data. It returns a dedicated public view of that data, never the internal database or a user's full application access.
Pulse Connect is not generally available. External pilot partners build and run against staging only (https://api.staging.maidcentral.ai/api/connect/v1); production access isn't offered yet. MaidCentral enables it branch by branch, and turns each family below on separately. Nothing in it deletes Pulse data.
What you can do
| Family | Reads | Writes and actions |
|---|---|---|
Customer data (core_reads) | Customers, homes, service sets, jobs, scorecards, customer tags | — |
| Operations | Teams, technicians, zones, bookable availability | — |
| Billing | Invoices, payments, balances | — |
| Sales | Leads, quotes, booking-form configuration, instant pricing | — |
| Time tracking | Worked-time totals per technician and per job | — |
| Reports | Seven office reports | — |
| Writes | — | Create and update customers, homes, leads and quotes; add or remove a customer's tags; record a customer's text and email consent; close a lead as lost; book a saved quote; move, skip or cancel one visit and list their reasons; cancel a recurring service from a date; append notes to customers, quotes and technicians |
| Payments | — | Mint a hosted link where a customer saves a card (nothing is charged) |
| Webhooks | — | Signed event deliveries to your endpoint |
GET /capabilities says which families are on for your branch. Changes made in MaidCentral V2 (the classic app) appear in reads but send no webhooks.
What is excluded
Card numbers and payment credentials, payroll and pay rates, employee HR data, GPS and device data, access and key instructions, internal notes (they can be added, never read, except the note that closed a lead, which lead reads return as closed_reason), message bodies, and free-text fields (except that same closed_reason). Older MaidCentral app: a lead closed from its Sales Pipeline saved its reason before the close, so its closed_reason is null, or a note added after the close. Texts and emails are never returned.
Terms
| Term | Meaning |
|---|---|
| Customer | A person or company the branch serves. |
| Home | A customer's relationship to one service address. Two customers at one address have two homes. |
| Service set | A customer's recurring or one-time service at a home: what is cleaned, how often, and at what price. |
| Service type | A scope of work the branch sells, such as a standard or deep clean. |
| Frequency | frequency is how often a service repeats (weekly, one_time and so on). frequency_id is one priced frequency option of a service type, used when quoting. |
| Lead, quote | One record read two ways. A lead is a prospect who is not a customer yet; a quote is the same record with pricing. A lead id is a quote id. |
| Job | One visit. |
How access is controlled
During the external pilot, MaidCentral issues your staging keys. (A branch administrator creates production keys in Pulse, how, but production isn't offered to external partners yet.) Each key:
- Belongs to one branch and can't reach another
- Carries only the scopes ticked when it was made, and can't be edited afterwards
- Expires 90 days after creation by default, at most 180
- Is shown once, and can be revoked immediately
A branch has at most 10 active keys, so each integration keeps its own key with room to rotate. Replacing a key means creating the new one first, so keep a slot free for rotation. All keys on a branch share its rate limits and monthly allowance; more keys add neither.
How usage is counted
Each branch has a monthly allowance of operations, agreed with MaidCentral. GET /usage shows the allowance, what has been used, what remains and when it resets (the start of the next UTC month).
| Usage class | Operations | Counts |
|---|---|---|
core_read | Customer, home, service-set, job, lead, quote, billing, operations, time and scorecard reads | One per successful response; each page of a list is one |
core_write | Customer, home, lead and quote writes, booking, notes, job actions, the service cancel, payment links | One per successful write; a replay is free |
report_run | The seven reports | One per successful report |
| Free | /me, /branches, /capabilities, /usage, /quotes/config, /quotes/calculate, /service-sets/cancel-reasons, /jobs/move-reasons, /jobs/skip-reasons, webhook management | Never |
Failed, refused, rate-limited, not-found, oversized and cancelled requests are free. The allowance is soft: when a metered response takes the branch to or past its allowance, it carries Pulse-Connect-Usage-Warning: allowance_exceeded, and requests keep working. A branch with no allowance set gets no warning. MaidCentral will contact you about usage beyond the allowance.
Branch admins see the same usage in Pulse, in the Monthly usage panel of Settings > Integrations & System > Integrations > API Access > Pulse Connect API. Pulse emails the admins who created the branch's active keys, and can still manage keys there, when usage reaches 80% and 100% of the allowance (once each per UTC month), and 14 days before a key expires. During the external pilot MaidCentral creates your staging keys, so these emails go to MaidCentral rather than to you; watch GET /usage and the key's expires_at from GET /me yourself.
Before connecting an AI tool
The business chooses the external tool and approves any AI provider that will receive its data. Use a separate key per integration, grant the fewest scopes, keep the key out of prompts and source code, and revoke it when the integration is retired.
Getting access
Contact your MaidCentral representative or MaidCentral Support to sign the partner agreement, enable the branch on staging and agree the allowance. MaidCentral Support handles partner questions and issues the staging key. Developers continue with the developer quickstart; the business owner and developer complete the pilot checklist together.