Book with permission. Connect with confidence.

API v1 · SERVER-TO-SERVER

Start here

These appointments are two-hour visits to assess the property and prepare a quote. They do not schedule cleaning or promise a cleaning price. Services are provided by Rolling Suds of Collierville-Southaven.

Download OpenAPI specification Owner credential management ↗

1. Sign in to the owner admin panel and find Agent booking access. Create a test credential with the permissions below.
2. Store the credential in your agent server’s secret manager. Send it as Authorization: Bearer YOUR_TOKEN. Browser clients supplying an Origin header are rejected; no cross-origin browser access is offered.
3. Read the catalog, match the property type to valid service IDs, and fetch availability.
4. Preview the request. Explain the property, selected services, quote visit time, two-hour duration and service-related contact to the customer. Obtain their approval.
5. Create the booking with customerApproved: true and a UUID Idempotency-Key. Test mode returns simulated and never writes to Workiz, sends email or reserves live time.
6. After testing, have the owner issue a separate live credential. Only status: confirmed confirms a real quote visit.

Endpoints and permissions

Base URL: https://midsouthpowerwashing.com/api/v1/agent

Request example

Replace all customer placeholders and replace appointment: 0 with a start value from availability. Timestamps are Unix seconds, and appointment labels use America/Chicago. Each draft field below must be present; size, access and timing may be empty strings. Property details must be provided even when unknown: use “Unsure” where appropriate.

{
  "draft": {
    "type": "residential",
    "services": [
      "house-wash",
      "driveway",
      "windows"
    ],
    "address": "CUSTOMER STREET ADDRESS",
    "city": "Memphis",
    "state": "TN",
    "zip": "38117",
    "material": "Brick and concrete",
    "size": "Unsure",
    "stories": "1",
    "condition": "Dirt and buildup",
    "water": "yes",
    "access": "",
    "timing": "Flexible",
    "name": "CUSTOMER NAME",
    "email": "CUSTOMER EMAIL",
    "phone": "CUSTOMER PHONE"
  },
  "appointment": 0,
  "customerApproved": true
}

Preview accepts the same body without customerApproved. It never reserves a slot, so creation checks availability again.

Server-side requests

Load MPW_AGENT_TOKEN from your server’s secret store; do not paste real credentials into documentation or shell history.

curl https://midsouthpowerwashing.com/api/v1/agent/catalog \
  -H "Authorization: Bearer $MPW_AGENT_TOKEN"

curl https://midsouthpowerwashing.com/api/v1/agent/bookings \
  -H "Authorization: Bearer $MPW_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_REQUEST_UUID" \
  --data-binary @approved-booking.json

Retries, status and privacy

• New bookings return HTTP 201; completed identical retries return 200 with the same reference. A key is isolated to its credential.
• Reuse the same Idempotency-Key and identical details after a timeout. Changed details return 409 REQUEST_CHANGED. An in-flight attempt can return 409 IN_PROGRESS.
• For 409 SLOT_TAKEN, refresh availability and obtain approval for the new time before starting a new request.
• For review_required, do not claim confirmation or create another booking. The owner must check the provider record. Polling retrieves the stored receipt; it does not reconcile vendor state automatically.
• Receipts contain status and appointment information, not contact details, provider job IDs, staff information or vendor credentials. Other agents’ references return 404.
• Only confirmed appointments trigger confirmation email. Email delivery is separate from appointment confirmation; a confirmed appointment does not prove that an email arrived.
• No customer search, cancellation, rescheduling or payment endpoints are provided.

Limits and credential lifecycle

Credentials expire within 1–90 days. The owner chooses scopes and a limit of 1–50 new bookings per rolling 24-hour window. Each credential allows 60 requests per minute; shared safeguards limit total new bookings and repeated contact to the same customer. A 429 response includes Retry-After; if still limited, wait for the applicable quota window. Failed new attempts may consume quota. Revocation blocks subsequent requests immediately; an already authorized in-flight operation may finish.

Only the credential hash is stored. The full credential is shown once when created and cannot be recovered. Create a replacement and revoke the old credential to rotate access. Test and live credentials are distinct and cannot change environment. Rate limits, validation, encrypted booking storage and audit records protect the API; public website visitors still use its security challenge.

Next steps

Create a test credential, run the read → preview → simulated booking → receipt sequence, and verify that a changed retry and another credential’s receipt are rejected. Issue live access only after that test passes.