Pulse Connect API Keys
Create, copy, rotate and revoke the API keys outside tools use to reach your branch's data through the Pulse Connect API, and see how much of the branch's monthly API allowance has been used. You manage them in Settings > Integrations & System > Integrations > API Access > Pulse Connect API, and each new key is shown only once. (Sending texts and emails from Pulse is a different feature: see Pulse Connect (Messaging).)
Overview
The Pulse Connect API lets an approved outside tool, such as a reporting dashboard, a booking site or an automation service, work with your branch's customers, homes, jobs and other data. Each tool signs in with its own API key. You create and manage those keys yourself in Pulse, and the same screen shows the branch's monthly API usage.
Every key:
- Belongs to the branch you are working in and cannot reach any other branch
- Can do only what its scopes allow, for example reading jobs but not changing them
- Expires on the date you choose, up to 180 days after it is created
- Is shown in full only once, when you create it
- Can be revoked at any time, and stops working immediately
The Pulse Connect API may need to be turned on for your company. If you do not see API Access in your integrations, contact MaidCentral Support.
Keys you create here work on your live Pulse data. Outside software partners in the Pulse Connect pilot build and run against MaidCentral's staging copy only, and MaidCentral issues their staging keys; live access isn't offered to outside partners yet.
Who can manage API keys
Managing API keys is an admin task. You need the Manage Pulse Connect API Keys permission, which the Administrator role has. If you do not see API Access, ask an administrator at your company to grant you access or to create the key for you.
Where to find API keys
Go to Settings > Integrations & System > Integrations, expand API Access, then open Pulse Connect API. The list shows every key for the branch you are working in, with its name, the first characters of the key, its scopes, its status, and when it was created, expires and was last used. Dates are shown in UTC.
To manage another branch's keys, switch your working branch first.
Create an API key
You see the full API key only once. Copy it before you click Done.
A branch can have at most 10 active keys. At ten, Create key is greyed out (disabled) until you revoke one the branch no longer uses. Expired and revoked keys do not count.
- In Pulse Connect API, click Create key.
- In Key name, name the tool that uses the key, for example "Booking website".
- In Expires in, choose 30, 60, 90 or 180 days. The default is 90.
- Under Scopes, tick only what the tool needs. A report that only reads jobs needs Jobs (read). A booking website that loads your services and shows prices needs Booking configuration and pricing (read).
- Click Create key, then Copy, and paste the key into the tool or your password manager.
- Click Done.
Use a separate key for each tool. Ten keys leave room for each tool to keep its own key and still rotate one. Never paste a key into an email, ticket, chat or document.
Choose scopes: which scope does my tool need?
Tick only what the tool needs; the tool's developer can tell you which scopes it uses. A booking website that loads your services and shows prices needs Booking configuration and pricing (read).
| Scope | Lets the tool |
|---|---|
| Reads | |
| Usage | See how much of the branch's monthly API usage has been used |
| Customers (read) | List, look up and read customers |
| Tags (read) | List the branch's customer tags |
| Homes (read) | List and read homes |
| Services (read) | List and read customers' recurring services |
| Jobs (read) | List and read jobs |
| Teams (read) | List teams |
| Technicians (read) | List and read technicians |
| Zones (read) | List zones |
| Availability (read) | See open times for scheduling |
| Billing (read) | Read invoices, payments and customer balances |
| Leads (read) | List and read leads |
| Quotes (read) | List and read saved quotes |
| Booking configuration and pricing (read) | Load the services, frequencies and options customers can book online, and calculate prices. Does not read saved quotes. |
| Time (read) | Read daily and per-job time summaries |
| Reports (read) | Run reports such as sales and operations KPIs, week in review and open invoices |
| Scorecards (read) | List customers' ratings of completed visits, and get a webhook when a customer rates a visit (for example, to send a review request) |
| Writes | |
| Customers (write) | Create a customer, change its approved fields, and add or remove its tags |
| Homes (write) | Add a home to a customer and change its name or address |
| Leads (write) | Create and update leads. Does not read leads or save quotes. |
| Customer notes (write) | Add a note to a customer |
| Quote notes (write) | Add a note to a quote |
| Technician notes (write) | Add a note to a technician |
| Quotes (write) | Save and revise priced quotes. Does not read saved quotes. |
| Bookings (write) | Book a saved quote into a first visit and a recurring service |
| Jobs (change) | Move, skip or cancel a job, and list the move and skip reasons it takes |
| Services (cancel) | Cancel a customer's recurring service from a date, and list the Cancel Service reasons it takes |
| Payments (write) | Create a secure link where a customer saves a card for a quote |
| Administration | |
| Webhooks (manage) | Create, change and test webhooks that tell the tool when something changes in Pulse |
See your monthly API usage
How much of our API allowance have we used this month? The Monthly usage panel at the top of Pulse Connect API shows it for the branch you are working in:
- How many operations the branch's tools have used this month, out of its monthly allowance, with a progress bar
- When usage resets: the first day of the next month, in UTC
- How many operations are over the allowance, if the branch has gone past it
The allowance is agreed with MaidCentral. It is soft: requests keep working past it, and MaidCentral will contact you about usage beyond it. If no allowance is set, the panel shows how many operations were used and says "No monthly allowance is set for this branch"; contact MaidCentral Support to agree one.
Usage is counted a few moments after each request. "Recent requests are still being counted." means the last few requests are not in the total yet. "Usage counting is delayed; the total will catch up on its own." means counting has fallen behind for a while.
Usage and expiry emails
Who gets the 80% and 100% emails, and when does a key-expiry email arrive? Pulse emails the admins who created one of the branch's active API keys or connected an AI assistant to it, and still have the Manage Pulse Connect API Keys permission and access to the branch:
- When the branch has used 80% of its monthly allowance, and again when it reaches 100%. Each email is sent once a month. If usage jumps straight past 100%, only the 100% email is sent. If the allowance is raised during the month, an email already sent that month is not sent again. If the branch crosses a threshold in the last minutes of a month, the email for that month arrives early on the 1st.
- When an API key has 14 days or less left, once for that key (a key created with less than 14 days left gets it within about 15 minutes). The email names the key and the first characters of the key, never the full key. Rotate the key before it expires so the tool keeps working.
The emails come from MaidCentral, not from your company's email address. The link in the email opens Pulse Connect API for the branch the email is about. If you work in several branches, Pulse switches you to that branch; if you don't have access to it, you stay where you are. Pulse checks for them every 15 minutes, so an email can arrive up to 15 minutes after the branch crosses a threshold.
Change a key's name, scopes or expiry
You cannot edit a key after it is created. Use Rotate to make a replacement with the changes you need, then revoke the old key.
Rotate an API key
Rotate a key before it expires, or whenever you think someone else may have seen it. Rotating creates a new key first, so Rotate is greyed out while the branch has 10 active keys. Revoke a key the branch no longer uses before you rotate.
- Find the key in the list and click Rotate. The form opens with the same name and scopes filled in. Scopes the form no longer lists are left off; no tool needs them.
- Change anything you need, then click Create key, copy the new key and click Done.
- Update the outside tool to use the new key and check that it still works.
- Back in Pulse, click Revoke on the old key.
Rotating does not revoke the old key for you, so the tool keeps working while you switch it over.
Webhook subscriptions created with the old key pause when you revoke it. Ask your developer to resume them with the new key.
Keys that expire within 14 days show Expiring soon.
Revoke an API key
- Find the key in the list and click Revoke.
- Click Revoke key to confirm.
Requests that use the key fail immediately, and the key shows Revoked. Revoking cannot be undone. If a tool still needs access, create a new key for it.
AI assistant connections
Connect Claude, Codex or another AI assistant to Pulse with a Pulse sign-in instead of an API key, then see or disconnect it here. Anyone with the Manage Pulse Connect API Keys permission can connect one: see Connect Claude or Codex.
Connect Claude or Codex
Anyone with the Manage Pulse Connect API Keys permission can connect Claude, Codex or another AI assistant to Pulse. No API key is needed; the assistant signs in to Pulse.
- In the assistant, add a custom connector with the address
https://api.maidcentral.ai/api/connect/mcp. In Claude: Settings > Connectors > Add custom connector. - On the Pulse page that opens, enter your Pulse address if asked (for example
yourcompany), click Continue, and sign in. - Tick the branches under Branches it can use and click Allow.
The sign-in page expires after 10 minutes. You can have at most 10 active assistant connections. With write access, the assistant must show a preview before it saves a lead, quote or note, and is built to ask you first. An assistant set to run without asking can confirm its own changes, so give write access only to assistants you supervise.
Codex and Claude Code steps, and the full list of what the assistant can do: MCP server.
See connected assistants
AI assistant connections sits under the usage panel on the same screen and lists every assistant connected to the branch you are working in:
| Column | What it shows |
|---|---|
| Assistant | The assistant's name, for example Claude |
| Connected by | Who signed in and allowed it |
| Branches | Every branch the assistant was granted, not only this one |
| Access | Read only, or Read and write when it can also add leads, quotes and notes |
| Last used (UTC) | The last day it reached Pulse, or Never |
| Expires (UTC) | Connections end 90 days after they are allowed; connect again to keep using it |
| Status | Active, Revoked or Expired |
Disconnect an assistant
To disconnect an assistant, click Disconnect on its row, then Disconnect to confirm. It loses access to every branch it was granted, not only this one, and the row shows Revoked. The assistant has to sign in again to reconnect.
AI assistant connections do not use your API keys and do not count toward the branch's 10-key limit. Their requests do count toward the branch's monthly API usage, and the person who connected the assistant can receive the usage emails.
Connecting AI assistants may need to be turned on for your company. Until it is, this section only appears if an assistant is already connected. If you don't see it, or no branch can be chosen when you sign in, contact MaidCentral Support.
Troubleshooting
| Problem | What to try |
|---|---|
| Create key is greyed out | The branch already has 10 active keys. Revoke one it no longer needs. |
| "This branch has 10 active keys, the maximum" | Another admin created a key while your form was open. Close the form, revoke a key the branch no longer needs, then create yours. |
| "This request was already submitted with different details" | Close the form and check the list. If the key you just created is there, its full key cannot be shown again: revoke it and create a new one. |
| I lost the key before copying it | Revoke that key and create a new one. Pulse cannot show a key again. |
| The booking website cannot load prices | The key needs Booking configuration and pricing (read). Rotate the key with that scope ticked, update the website, then revoke the old key. |
| The tool stopped working | Check whether the key shows Expired or Revoked. Create a new key and update the tool. |
| I didn't get a usage email | Usage emails go only to admins who created one of the branch's active keys or connected an AI assistant to it, and still have the Manage Pulse Connect API Keys permission. Each threshold is emailed once a month, and an email can take up to 15 minutes. Check your spam folder. |
| Usage looks behind | If the panel says requests are still being counted or counting is delayed, wait a few minutes and reload. The total catches up on its own. |
| I cannot find API Access | The Pulse Connect API may not be turned on for your company, or you may not have permission. Ask an administrator or contact MaidCentral Support. |
Related Articles
- Integrations Overview - All the tools you can connect to Pulse
- Integrations, System, and Access Control - Where integration settings live