Booking connector

During a call Sanaa needs to read availability and make bookings in your product. It does that through a small HTTPS service you run: the connector. Each organization has one, and all of its tenants are served through it.

The operations

  • business-profile Name, time zone, services, staff, hours, policies, FAQs
  • services The service list
  • check-availability Open times for a date, service and optional person
  • hold-slot Hold a time briefly while the caller confirms
  • book Create a booking
  • find-booking Find a caller's upcoming bookings
  • cancel-booking Cancel a booking
  • reschedule-booking Move a booking
  • customer-history Recognise a returning customer
  • upsell-suggestions Optional suggestions
  • add-to-waitlist Add a caller to a waitlist

How requests arrive

  • Signed with the same Sanaa-Signature and Sanaa-Timestamp headers as webhooks. Verify them on every request.
  • Changes carry an Idempotency-Key: the same key must give the same result, never a second booking.
  • Sanaa waits about 4.5 seconds. A caller is on the line, so answer quickly. If a change gets no answer, Sanaa treats the result as unknown rather than failed.
  • Your answers are validated and cleaned before a caller hears them.

Register and test

curl -X PUT https://api.getsanaa.com/api/v1/connector \
  -H "Authorization: Bearer $SANAA_KEY" -H "Content-Type: application/json" \
  -d '{ "base_url": "https://api.yourapp.com/sanaa" }'
# the response includes your signing secret, once

curl -X POST https://api.getsanaa.com/api/v1/connector/test \
  -H "Authorization: Bearer $SANAA_KEY"

The conformance test sends about twenty signed requests in test mode and reports what to fix. A connector must pass before it serves live tenants. You can also run it from the console.

The complete contract, with request and response shapes, is the connector specification.

Back to the documentation.