RoundPro API

Getting started

The RoundPro API lets another system work with a window cleaning business's RoundPro account: look up customers and the schedule, add and update customers, create and change jobs, and move or reassign cleans. Everything it does is checked, logged and can be undone by the business.

• The business owner makes a key in RoundPro: Settings → API & integrations → Make a key. They choose what it can do, and it's shown once — copy it straight into your system.
• Every request goes to https://roundpro.app/api/v1, with the key in the Authorization header.
• Start by calling GET /me. It tells you which business the key belongs to and what it's allowed to do.

curl https://roundpro.app/api/v1/me \
  -H "Authorization: Bearer rp_live_your_key_here"

On Windows, in PowerShell, type curl.exe instead of curl (plain curl there is a different command that doesn't understand -H).

{
  "business": { "id": "mumqddmwmmmSpnzVV2OQ", "name": "Crystal Clear Windows", "timezone": "Europe/London", "vatRegistered": false, "pricesIncludeVat": false },
  "key": { "id": "…", "name": "Zapier", "scopes": ["read", "customers:write"], "createdAt": "2026-10-07T08:07:18.803Z" },
  "today": "2026-10-07"
}

The API is part of the full RoundPro plan. A key stops working if it's revoked, if the person who made it stops being an owner or admin, or if the business's plan ends or the account is closed.

Keys and security

Send the key as a Bearer token on every request. Keys start rp_live_ followed by 40 letters and digits.

Authorization: Bearer rp_live_AbCdEf…

• Treat a key like a password. Keep it on your server or in your integration platform's secret store — never in a web page, a mobile app, a spreadsheet or an email. The API doesn't answer requests from web browsers (there are no CORS headers) for this reason.
• Use one key per system, so each can be switched off on its own and the change log shows which system did what.
• RoundPro stores only a scrambled (SHA-256) copy of each key, so it can't be shown again. If a key is lost, the owner revokes it and makes a new one.
• The owner is emailed whenever a key is made. Revoking a key in Settings stops it at once.
• All requests must use HTTPS.

Permissions

Each key has one or more permissions, chosen by the owner when it's made. Asking for something the key isn't allowed to do gets a 403 with the permission it needs.

Conventions

• Requests and answers are JSON. Send Content-Type: application/json with a body.
• Money is in whole pence, in fields ending Pence: £25.50 is 2550. Prices on jobs and visits are before VAT. If business.pricesIncludeVat is true, the owner thinks in prices including VAT: take the VAT out before sending one, and add it back when telling them.
• Dates are YYYY-MM-DD in the business's own time zone (see GET /me), e.g. "2026-10-14". "Today" means today for the business.
• Times are ISO 8601 in UTC, e.g. "2026-10-07T08:30:00.000Z".
• IDs are strings. Treat them as opaque: don't parse them or assume a length.
• In a PATCH, leave a field out to keep it as it is; send null to clear it.
• Unknown fields are refused with a 400 naming the field, so a typo never silently does nothing. Answers may gain new fields over time — ignore any you don't recognise.

Lists and paging

List endpoints return a page of results and a cursor for the next page. Ask for up to 100 at a time with limit (default 50). When nextCursor is null there are no more.

GET /customers?limit=100
→ { "data": [ … ], "nextCursor": "WyIyMDI2LTEwLTA3…" }

GET /customers?limit=100&cursor=WyIyMDI2LTEwLTA3…
→ { "data": [ … ], "nextCursor": null }

Cursors are opaque — pass back exactly what you were given. Paging is stable: records added while you page through don't cause duplicates or gaps in what you've already fetched.

Errors

Anything other than a 2xx answer has an error body like this. The message is plain English and safe to show to a person; field names the input at fault when there is one.

HTTP/1.1 400 Bad Request

{ "error": { "code": "invalid", "message": "startDate can't be in the past (today is 2026-10-07 for this business)", "field": "startDate" } }

Every answer has an X-Request-Id header. Quote it if you need to ask us about a request.

Rate limits

• 120 requests a minute per key, of which up to 60 can be changes (POST, PATCH and DELETE).
• 300 requests a minute per business, across all its keys.
• Over the limit you get a 429 with a Retry-After header (in seconds). Wait that long, then carry on.
• For bulk work (hundreds of customers), pace requests to about one a second.

Retrying safely (Idempotency-Key)

Networks fail. If a POST or PATCH times out, you can't tell whether it happened. Send an Idempotency-Key header with a value unique to that change (a UUID is ideal), and if you send the same request again with the same key within 24 hours, you get the first answer back instead of the change being made twice. A replayed answer carries Idempotent-Replayed: true.

POST /customers
Idempotency-Key: 3f6c1d1e-6a0b-4d8e-9c56-1d2b8c7e9a10
Content-Type: application/json

{ "name": "Sarah Jones", "phone": "07700 900123" }

• Use a new key for each different change. Reusing a key with a different body gets a 409.
• Keys are 1–100 characters: letters, digits, - _ : and .
• Zapier and GoHighLevel retries: map a unique value from the trigger (e.g. the contact or event ID) into the header so a retried step doesn't double up.

The change log and undo

Every change made through the API is written to the business's change log (Settings → API & integrations), with which key made it and what it was before. The ID of the log entry comes back in the RoundPro-Change header.

The business can undo any change from there. Undo is careful: if the record has been changed again since (in RoundPro or through the API), it's left alone rather than overwrite the newer change.

Webhooks: being told when things happen

Instead of asking RoundPro over and over whether anything has changed, a system can be told the moment something happens. The business owner adds the address to send to in Settings → API & integrations → Add a webhook, and ticks the events wanted (or everything).

Each event is a POST of JSON to the address. data is the record as the API returns it (so the same fields as GET /customers/{id} and so on), as it was when the message was first sent.

POST https://your-system.example.com/roundpro
Content-Type: application/json
RoundPro-Event: visit.moved
RoundPro-Event-Id: muxw3pteaClPBAhsp2Vj
RoundPro-Delivery-Id: muxw3q8kR2mXbN0aLp4Q
RoundPro-Signature: t=1791367200,v1=5f2b…

{
  "id": "muxw3pteaClPBAhsp2Vj",
  "type": "visit.moved",
  "createdAt": "2026-10-07T09:20:00.000Z",
  "business": { "id": "mumqddmwmmmSpnzVV2OQ", "name": "Crystal Clear Windows" },
  "source": { "kind": "api", "keyId": "…", "keyName": "GoHighLevel" },
  "data": { "id": "vis…", "jobId": "job…", "customerId": "cus…", "date": "2026-10-16", "originalDate": "2026-10-14", "status": "scheduled", … },
  "previous": { "date": "2026-10-14" }
}

• Answer with any 2xx status within 10 seconds to say it arrived. Do the slow work afterwards.
• Anything else (an error, no answer, a redirect) is tried again after 1, 5, 15 minutes, then 1, 3, 6, 14 hours — 8 tries over about a day. An address still failing after 24 hours is switched off and the owner emailed.
• The same event can occasionally arrive twice (for example if your answer was lost). Use id to ignore one you've already handled.
• Events can arrive out of order. Use createdAt, or look the record up with the API if order matters.
• source.kind says what caused it: app (someone in RoundPro), api (with keyId and keyName), customer (on their own page, or accepting a quote online) or system. If your system both changes RoundPro through the API and listens for events, ignore events whose source.keyId is your own key, so changes don't bounce back and forth.
• Events while a webhook is switched off aren't sent later. Imports and restoring a backup don't send events.
• Only https addresses on the public internet are used, on the normal port.

Checking a message really came from RoundPro: each webhook has a signing secret (shown once, when it's added). The RoundPro-Signature header has a time (t) and an HMAC-SHA256 (v1) of the time, a full stop, and the body exactly as sent, made with that secret. Work out the same and compare; refuse messages more than 5 minutes old. Zapier and GoHighLevel don't need this, but your own software should do it.

import crypto from "node:crypto";

// rawBody: the request body exactly as received (before JSON parsing)
function isFromRoundPro(rawBody, signatureHeader, secret) {
  const parts = Object.fromEntries(signatureHeader.split(",").map((p) => p.split("=")));
  const age = Math.abs(Date.now() / 1000 - Number(parts.t));
  if (!parts.t || !parts.v1 || age > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected, "hex"), b = Buffer.from(parts.v1, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Send a test from the webhook's page in Settings to check it's working: the event type is test.ping.

A system can also subscribe for itself with its API key (POST /webhooks, and DELETE /webhooks/{id} to stop) — this is how Zapier's instant triggers work. Those subscriptions show in the owner's Settings marked as added through the API, and go if the key is revoked.

Leads: enquiries quoted automatically

Send RoundPro the enquiries a business gets — from a Facebook lead form, a website form, Google or a lead site — with POST /leads (needs the Leads permission). RoundPro deals with each one as the business has set up in Settings › ALICE – Lead Assistant:

• It's priced from the business's price list: type of property and bedrooms, extras, and how often. Send the answers as people gave them — "Semi-detached house", "3 bedrooms", "Conservatory, Extension", "Every 4 weeks" or "Monthly" are all understood. Anything it can't read with confidence is left for the business, never guessed.
• With automatic quoting on, and everything needed in hand (a price, a street address, an email or UK mobile, inside the area the business covers), the quote is texted or emailed to them straight away, with a link to accept. Accepting adds them as a customer with the job booked in.
• Otherwise it waits in Leads with the reason (and the price worked out, where there is one); the business can send a thank-you straight away so they know they've been heard.
• The same email or phone number enquiring again within 7 days is kept as a duplicate, and nothing is sent twice. A business can take up to 300 leads a day.

The answer tells you what happened in outcome: quoted, quote_not_sent (a quote was made but couldn't be sent — reason says why), waiting_approval (priced, waiting for the business), needs_pricing (reason says why), outside_area, or duplicate. Put where the lead came from in source ("Facebook") and the ad or form in campaign: they're kept on the quote and the customer, and the business sees which sources win work.

POST https://roundpro.app/api/v1/leads
{ "name": "Sarah Jones", "email": "sarah@example.com", "phone": "07700 900123",
  "address1": "10 Holyhead Road", "town": "Telford", "postcode": "TF1 1AJ",
  "propertyType": "Semi-detached", "bedrooms": "3", "extras": "Conservatory", "frequency": "Every 4 weeks",
  "source": "Facebook", "campaign": "Spring offer" }
→ 201 { "id": "lead…", "status": "quoted", "outcome": "quoted", "suggestedPricePence": 2100, "quoteId": "quo…", … }

Then listen for quote.accepted (the customer and job made) and quote.declined — for example to tell Facebook which ads bring paying customers. Other answers from a form can go in answers (question → answer) and anything they wrote in message; both are shown to the business.

AI assistants (the RoundPro connector)

RoundPro has a connector for AI assistants, using the Model Context Protocol (MCP), at https://roundpro.app/mcp. Once connected, the owner can ask in plain English — "who's due on the Monday round next week?", "move Mrs Jones's clean to Friday and give it to Dan", "add Sarah Smith at 10 Holyhead Road, every 4 weeks at £18" — and the assistant does it with the same actions as this API.

• In Claude (Pro, Max, Team or Enterprise): go to Settings → Connectors, add a custom connector, and paste https://roundpro.app/mcp. On Team and Enterprise plans an administrator may need to allow it. Claude then opens RoundPro's sign-in page. It's added on the web or desktop app, then works on the phone app too.
• The business owner signs in, chooses what the assistant may do (it can always look things up; changing customers, jobs or the schedule are separate ticks), and confirms with their password and two-step code.
• Every change it makes is in the change log with Undo (messages already sent can't be taken back), and fires webhooks like any other change. It can never delete anything or see card details. It only messages customers — sending a quote, a reply to a lead or an invoice — or records payments if the owner ticked those, and it reads back what it will send first.
• It shows in Settings → API & integrations under AI assistants, where it can be disconnected at once.

For developers and other assistants:

• Transport: Streamable HTTP, JSON answers (no server-sent events), no sessions. Protocol versions 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05.
• Sign-in: OAuth 2.1 with dynamic client registration (RFC 7591), public clients and PKCE (S256). Metadata at https://roundpro.app/.well-known/oauth-protected-resource/mcp and https://roundpro.app/.well-known/oauth-authorization-server. Access tokens last an hour; refresh tokens are replaced on every use, and reusing an old one disconnects the app.
• An API key also works, sent as Authorization: Bearer rp_live_…, for assistants that take a fixed header.
• Tools are this API's operations, named with underscores (customers_list, jobs_update, visits_update…), each labelled read-only or not. A connection only sees the tools its permissions allow.

What it does, and doesn't

The API works through the same rules as the RoundPro app, so the schedule always stays right:

• Creating a regular job puts its cleans on the schedule straight away (up to 16 weeks ahead) from its start date, which must be today or later. For an existing customer, give the date of their next clean.
• Changing a job's frequency, start date or months off re-plans its upcoming cleans; cleans already done, invoiced or moved by hand are kept.
• Changing a job's price updates its upcoming cleans and is recorded in its price history.
• Moving one visit leaves the rest of the job's cycle where it is (unless the job counts from completion).
• Archiving a customer stops their jobs and removes upcoming cleans; history and invoices are kept.

To keep businesses and their customers safe, version 1 of the API won't:

• delete anything (customers are archived instead, and can be restored);
• send emails or texts to customers unless the key has Quotes and replies (quotes, replies to leads, a first clean's date), Payments and invoices (sending an invoice) or Leads (a lead you add may be sent its quote, or a thank-you, if the business has switched that on); or change anyone's marketing choice;
• mark cleans as done, take card payments, or create, change or void invoices (with Payments and invoices it can record money received);
• show card or bank details, customer page links, or anyone's email or password;
• change the team, settings, billing or sign-ins.

Examples

Add a new customer and book them in every 4 weeks on the Monday round:

POST https://roundpro.app/api/v1/customers
{ "name": "Sarah Jones", "email": "sarah@example.com", "phone": "07700 900123",
  "property": { "address1": "10 Holyhead Road", "town": "Telford", "postcode": "TF1 1AJ", "accessNotes": "Side gate, code 1234" } }
→ 201 { "id": "cus…", "properties": [ { "id": "prop…", … } ], … }

GET https://roundpro.app/api/v1/rounds
→ { "data": [ { "id": "rnd…", "name": "Monday" }, … ] }

POST https://roundpro.app/api/v1/jobs
{ "propertyId": "prop…", "pricePence": 1800, "frequencyWeeks": 4, "startDate": "2026-10-12", "roundId": "rnd…" }
→ 201 { "id": "job…", "nextVisitDate": "2026-10-12", … }

Find a customer by phone number or postcode:

GET https://roundpro.app/api/v1/customers?search=07700900123
GET https://roundpro.app/api/v1/customers?search=TF1%201AJ

Change a job to every 6 weeks and move it to another round:

PATCH https://roundpro.app/api/v1/jobs/job…
{ "frequencyWeeks": 6, "roundId": "rnd…" }

See tomorrow's work, then move one clean to Friday and give it to Dan:

GET https://roundpro.app/api/v1/visits?from=2026-10-08&to=2026-10-08
GET https://roundpro.app/api/v1/team

PATCH https://roundpro.app/api/v1/visits/vis…
{ "date": "2026-10-10", "operativeId": "usr…" }

Add a note to a customer (it's dated and marked with your key's name):

POST https://roundpro.app/api/v1/customers/cus…/notes
{ "text": "Asked for the conservatory roof next time" }

GoHighLevel, Zapier and AI assistants

No special app is needed: any tool that can send a web request with a header can use the API.

• GoHighLevel, hearing from RoundPro: add a workflow with the Inbound Webhook trigger, copy its address into a RoundPro webhook, press Send a test, then map the fields (data.name, data.email, data.phone…) in the workflow.
• Zapier, hearing from RoundPro: start a Zap with Webhooks by Zapier → Catch Hook, copy its address into a RoundPro webhook, and press Send a test so Zapier sees an example.
• GoHighLevel, changing RoundPro: in a workflow, add a Webhook (or Custom Webhook) action. Method POST or PATCH, the URL from this reference, a header Authorization: Bearer rp_live_…, and a JSON body mapping the contact's fields. Keep RoundPro as the place customers and the schedule live; send changes into it.
• Zapier, changing RoundPro: use Webhooks by Zapier → Custom Request. Set Data Pass-Through off, put the JSON body in Data, and add the Authorization and Content-Type headers. Use a Lookup (GET /customers?search=) step first to find the right customer ID.
• AI assistants: use the RoundPro connector (see AI assistants above) — no key to copy. For an agent you build yourself, give it the OpenAPI file and a key with only the permissions it needs.

A ready-made RoundPro app for Zapier (instant triggers, actions and searches, prices in pounds — including Create Lead for Facebook lead forms) is available by invitation — email us for the link.

Versions and changes

• This is version 1 (/api/v1). New endpoints and new fields in answers may be added at any time without notice — build your integration to ignore fields it doesn't know.
• Anything that would break an existing integration (removing or renaming a field, changing what one means) only happens in a new version, with at least 6 months' notice to everyone with a key.
• Every answer carries a RoundPro-Version header with the date of the current release.

Help

Questions, or something not working? Email info@cleanlynk.co.uk with the X-Request-Id from the answer, and what you sent (but never the key).