Partner guide

1. What you get

You keep your platform and your members. Talkspresso handles booking, payment and video, which are hard to build well.

3. Flows and calls

Each flow lists who does what, then shows the real call. Every call on this page runs against staging with a sandbox key. Run them in order. The examples use ids from our own test organization. The dates in them will be in the past when you read this: take a start_time from a fresh availability answer, within the next 14 days.

How every call works

export TSP_KEY="tsp_your_sandbox_key"
API=https://api-staging.talkspresso.com/partner/v1

Errors

Every error has this shape: { "error": { "code", "message" } }. Some errors also include fields or retry_after_seconds. In your code, use code, not the message text.

{
  "error": {
    "code": "invalid_credentials",
    "message": "Invalid or missing API key."
  }
}

Limits

If you go over a limit, you get 429 with retry_after_seconds. Wait that many seconds before you call again.

Show your coaches and their times

1. 1.

   Your server

   GET /providers. You get your coaches and the sessions each one offers, with duration and price in cents. You can keep the answer for a few minutes, then ask again.

2. 2.

   Your page

   Show your coaches and their sessions. A coach with price_cents 0 offers a free session.

3. 3.

   Your server

   GET /services/:id/intake-questions. Use it when the coach asks the buyer questions before the session. Show the questions in your form and send the answers with the booking.

4. 4.

   Your server

   GET /services/:id/availability for the dates the buyer is looking at (up to 14 days at a time, in the buyer’s time zone). The times are always current, so you are never offered a time that was just taken.

curl -s "$API/providers" \
  -H "Authorization: Bearer $TSP_KEY"

{
  "data": [
    {
      "id": "sn_andre",
      "name": "Andre Williams",
      "title": "Leadership Coach & Former Founder",
      "handle": "andre-williams",
      "photo_url": "/images/startupnash/andre.jpg",
      "headline": "",
      "services": [
        {
          "id": "svc_sn_andre_williams_mentor",
          "title": "1:1 Mentorship Session",
          "duration_minutes": 30,
          "price_cents": 0,
          "currency": "USD",
          "free": true
        }
      ]
    }
  ]
}

curl -s "$API/services/svc_sn_andre_williams_mentor/availability?from=2026-11-17&days=2&timezone=America/Chicago" \
  -H "Authorization: Bearer $TSP_KEY"

{
  "data": {
    "service_id": "svc_sn_andre_williams_mentor",
    "provider_id": "sn_andre",
    "timezone": "America/Chicago",
    "duration_minutes": 30,
    "slots": [
      {
        "start_time": "2026-11-17T15:00:00.000Z",
        "end_time": "2026-11-17T15:30:00.000Z"
      },
      {
        "start_time": "2026-11-17T15:30:00.000Z",
        "end_time": "2026-11-17T16:00:00.000Z"
      }
    ]
  }
}

Book a free session

1. 1.

   Buyer

   Picks a time and gives you a name and an email.

2. 2.

   Your server

   POST /bookings with a new Idempotency-Key. The answer is 201 with the booking and the buyer’s join link.

3. 3.

   Talkspresso

   Books the time, emails the buyer and the coach, and sends booking.created to your webhook.

4. 4.

   Your page

   Shows “you are booked”, and shows the join link when it is time to join. If a call fails or times out, send the same request again with the same Idempotency-Key. You will not get two bookings.

curl -s -X POST "$API/bookings" \
  -H "Authorization: Bearer $TSP_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-booking" \
  -d '{
    "provider_id": "sn_andre",
    "service_id": "svc_sn_andre_williams_mentor",
    "start_time": "2026-11-17T16:00:00Z",
    "buyer": { "name": "Sam Rivera", "email": "sam@example.com", "timezone": "America/Chicago" },
    "partner_ref": "order-1042"
  }'

{
  "data": {
    "id": "cmwecj3ax00dm1vjzdl3ceij7",
    "status": "active",
    "approval_status": "auto_approved",
    "start_time": "2026-11-17T16:00:00.000Z",
    "end_time": "2026-11-17T16:30:00.000Z",
    "duration_minutes": 30,
    "provider": {
      "id": "sn_andre",
      "name": "Andre Williams"
    },
    "service": {
      "id": "svc_sn_andre_williams_mentor",
      "title": "1:1 Mentorship Session"
    },
    "buyer": {
      "name": "Sam Rivera",
      "email": "sam@example.com"
    },
    "partner_ref": "order-s5-1794536217",
    "paid_cents": 0,
    "currency": "USD",
    "created_at": "2026-11-13T02:16:57.466Z",
    "join_url": "https://staging.talkspresso.com/meet/SESSION_ID?cid=BUYER_ID&ct=BUYER_TOKEN",
    "notes_available": false
  }
}

join_url is the buyer’s link to the call. Treat it like a password: share it only with that buyer. A paid session answers this call with 402 payment_required. If a field is missing, you get 400, and fields lists the field names.

{
  "error": {
    "code": "idempotency_key_reused",
    "message": "This Idempotency-Key was already used with a different request."
  }
}

{
  "error": {
    "code": "slot_unavailable",
    "message": "That time is no longer available.",
    "reason": "slot_taken"
  }
}

Book and pay

1. 1.

   Buyer

   Picks a time on a paid session and gives you a name and an email.

2. 2.

   Your server

   POST /checkouts with the same body as a booking, plus return_url (an https address on a host we registered). The answer is 201 with a checkout and a url. It is open for 30 minutes.

3. 3.

   Your page

   Send the buyer to url exactly as given. Do not log or store it. The part after # lets one buyer pay for this booking.

4. 4.

   Buyer

   Pays on the Talkspresso payment page, with PayPal or a card. The page shows the coach, the price, the cancellation rule and your organization’s name and logo.

5. 5.

   Talkspresso

   Sends the buyer back to your return_url with ?checkout_id=...&status=paid added. Talkspresso also sends checkout.paid and booking.paid to your webhook.

6. 6.

   Your server

   Do not trust status in the address, because the buyer can edit it. Confirm with GET /checkouts/:id (status paid, booking_id set) or wait for the webhook. The webhook arrives even if the buyer closes the tab before returning. A checkout that is not paid in 30 minutes becomes expired.

7. 7.

   Your server

   GET /bookings/:id for the booking and the join link.

curl -s -X POST "$API/checkouts" \
  -H "Authorization: Bearer $TSP_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1043-checkout" \
  -d '{
    "provider_id": "cmlrh3wdm002l1qhg56q14ydj",
    "service_id": "svc-ppcp-walkthrough-50",
    "start_time": "2026-11-17T15:30:00Z",
    "buyer": { "name": "Sam Rivera", "email": "sam@example.com" },
    "partner_ref": "order-1043",
    "return_url": "https://partner-e2e.example.com/done"
  }'

{
  "data": {
    "id": "cmweclzhd00gf1vjz7ucke94j",
    "status": "open",
    "url": "https://staging.talkspresso.com/pay/partner/cmweclzhd00gf1vjz7ucke94j#token=CHECKOUT_TOKEN",
    "expires_at": "2026-11-13T02:49:12.480Z",
    "partner_ref": "order-s5-1794536217-co",
    "booking_id": null,
    "provider_id": "cmlrh3wdm002l1qhg56q14ydj",
    "service_id": "svc-ppcp-walkthrough-50",
    "start_time": "2026-11-17T15:30:00.000Z"
  }
}

curl -s "$API/checkouts/CHECKOUT_ID" \
  -H "Authorization: Bearer $TSP_KEY"

{
  "data": {
    "id": "cmweclzhd00gf1vjz7ucke94j",
    "status": "open",
    "expires_at": "2026-11-13T02:49:12.480Z",
    "partner_ref": "order-s5-1794536217-co",
    "booking_id": null,
    "provider_id": "cmlrh3wdm002l1qhg56q14ydj",
    "service_id": "svc-ppcp-walkthrough-50",
    "start_time": "2026-11-17T15:30:00.000Z"
  }
}

A checkout has one of four statuses: open, paid, expired or cancelled. Once it is paid, booking_id has a value. The return address must be https on a host we registered for you. Any other address is refused:

{
  "error": {
    "code": "return_url_not_allowed",
    "message": "return_url must be https on a host registered for this organization.",
    "fields": [
      "return_url"
    ]
  }
}

{
  "error": {
    "code": "payment_required",
    "message": "This service is paid. Open a checkout with POST /partner/v1/checkouts.",
    "next": "POST /partner/v1/checkouts"
  }
}

Look up bookings

GET /bookings/:id returns one booking with its join link. GET /bookings lists your bookings, without join links. Filter with partner_ref, status (active, cancelled, awaiting_payment, completed), provider_id, from and to. Get more results with cursor and limit (1 to 100). GET /bookings/:id/intake returns the buyer’s answers to the coach’s questions.

curl -s "$API/bookings/BOOKING_ID" \
  -H "Authorization: Bearer $TSP_KEY"

Cancel and refund

1. 1.

   Your server

   POST /bookings/:id/cancel with a new Idempotency-Key and a reason_code. The reason_code is required.

2. 2.

   Talkspresso

   Cancels, refunds the buyer in full to the original payment method with no late fee, emails the buyer with your organization’s name and the reason in plain words, and tells the coach.

3. 3.

   Your server

   You get the cancelled booking back. booking.cancelled goes to your webhook with cancelled_by set to partner.

curl -s -X POST "$API/bookings/BOOKING_ID/cancel" \
  -H "Authorization: Bearer $TSP_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-cancel" \
  -d '{ "reason_code": "buyer_requested" }'

{
  "data": {
    "id": "cmwecj3ax00dm1vjzdl3ceij7",
    "status": "cancelled",
    "approval_status": "auto_approved",
    "start_time": "2026-11-17T19:00:00.000Z",
    "end_time": "2026-11-17T19:30:00.000Z",
    "duration_minutes": 30,
    "provider": {
      "id": "sn_andre",
      "name": "Andre Williams"
    },
    "service": {
      "id": "svc_sn_andre_williams_mentor",
      "title": "1:1 Mentorship Session"
    },
    "buyer": {
      "name": "Sam Rivera",
      "email": "sam@example.com"
    },
    "partner_ref": "order-s5-1794536217",
    "paid_cents": 0,
    "currency": "USD",
    "created_at": "2026-11-13T02:16:57.466Z",
    "notes_available": false
  }
}

{
  "error": {
    "code": "validation_failed",
    "message": "The request body is not valid.",
    "fields": [
      "reason_code"
    ]
  }
}

A coach must have agreed that you may cancel their sessions. If not, the call returns 409 coach_consent_required and nothing is refunded. The buyer can still cancel from the manage link Talkspresso emails them (in partner mode they get one only if Talkspresso sent a confirmation or they ask for a new link), or you can ask the coach.

Move a booking

1. 1.

   Your server

   GET /services/:id/availability for new times.

2. 2.

   Your server

   POST /bookings/:id/reschedule with a new Idempotency-Key and { "start_time": "..." }.

3. 3.

   Talkspresso

   Moves the booking if the coach allows it. A coach can limit how many times a buyer can move a booking and how close to the start time a move can happen. If the move has a reschedule fee, only the buyer can pay it, from the manage link Talkspresso emails them. Your call then gets 409 reschedule_fee_required.

4. 4.

   Your server

   You get the booking back with the new time. booking.rescheduled goes to your webhook.

curl -s -X POST "$API/bookings/BOOKING_ID/reschedule" \
  -H "Authorization: Bearer $TSP_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-move" \
  -d '{ "start_time": "2026-11-17T19:00:00Z" }'

{
  "data": {
    "id": "cmwecj3ax00dm1vjzdl3ceij7",
    "status": "active",
    "approval_status": "auto_approved",
    "start_time": "2026-11-17T19:00:00.000Z",
    "end_time": "2026-11-17T19:30:00.000Z",
    "duration_minutes": 30,
    "provider": {
      "id": "sn_andre",
      "name": "Andre Williams"
    },
    "service": {
      "id": "svc_sn_andre_williams_mentor",
      "title": "1:1 Mentorship Session"
    },
    "buyer": {
      "name": "Sam Rivera",
      "email": "sam@example.com"
    },
    "partner_ref": "order-s5-1794536217",
    "paid_cents": 0,
    "currency": "USD",
    "created_at": "2026-11-13T02:16:57.466Z",
    "notes_available": false
  }
}

Booking emails

Your organization has a setting called “Who sends booking emails”. An owner or admin changes it in Partner settings, or you email us. A key cannot change it. It has three values:

You can also ask for a value on one booking. Add notifications to POST /bookings or POST /checkouts, with talkspresso, branded or partner. If you leave it out, the organization’s setting applies. A request can ask for less than the setting, never more. The booking answer does not repeat the value.

curl -s -X POST "$API/bookings" \
  -H "Authorization: Bearer $TSP_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1044-booking" \
  -d '{
    "provider_id": "sn_andre",
    "service_id": "svc_sn_andre_williams_mentor",
    "start_time": "2026-11-18T16:00:00Z",
    "buyer": { "name": "Sam Rivera", "email": "sam@example.com" },
    "partner_ref": "order-1044",
    "notifications": "branded"
  }'

{
  "error": {
    "code": "notifications_mode_not_enabled",
    "message": "Your organization is not set up for \"partner\" booking emails. Change \"Who sends booking emails\" in your organization's partner settings first.",
    "fields": ["notifications"]
  }
}

{
  "error": {
    "code": "webhook_endpoint_required",
    "message": "\"partner\" booking emails need an active webhook endpoint subscribed to booking.created, so your platform is told to send the buyer's email.",
    "fields": ["notifications"]
  }
}

Any other value is refused with 400 validation_failed and fields set to ["notifications"].

What changes when your platform sends the emails:

• Partner mode needs a live webhook endpoint that receives booking.created. Without one, a request for partner is refused with 409 webhook_endpoint_required. If your endpoint is paused or removed later, Talkspresso goes back to sending the emails itself.
• Send the confirmation after you receive booking.created. “Delivered” means your endpoint answered with an HTTP 2xx. It does not mean your mailer sent anything.
• Talkspresso sends no reminders for these bookings, and there is no reminder event. Use the start_time in booking.created to schedule your own.
• The coach’s calendar invitation is not emailed to the buyer in partner mode either, while your endpoint is live.
• If booking.created is not delivered and answered with 2xx within 30 minutes (the check runs every 5 minutes, so allow up to 35), Talkspresso sends the buyer’s confirmation itself. If your endpoint answers late, the buyer can get both emails. The buyer always gets one confirmation.
• A confirmation is never held back when the session starts within 60 minutes. Talkspresso sends it at once. After Talkspresso has sent a booking’s confirmation in this way, it sends that booking’s reminders too.
• If your organization is set back to talkspresso or branded, Talkspresso sends the emails for every booking from then on, including bookings made earlier.

Always sent by Talkspresso

In every mode, Talkspresso never holds back an email that carries money, a cancellation, a link the buyer asked for or a notice about recording. In partner mode these emails also read “Your organization via Talkspresso”, with your organization’s name and logo, so the buyer knows who they are from.

Talkspresso does not send thank-you, review request or book-again emails to buyers of bookings your platform created, in any mode. The coach can still write to the buyer, and those messages come from Talkspresso.

Coach consent

• A coach agrees to be listed on your platform and agrees that you may cancel or move the sessions your members book. A cancel through the API refunds the buyer in full with no late or reschedule fee, even if the coach’s own policy would keep one. Talkspresso emails the coach when you cancel, and shows each move in the coach’s Talkspresso notifications.
• If a coach’s consent is not in place when you cancel or move a session, the call is refused with 409 coach_consent_required, including for sessions already booked. Tell the buyer to contact the coach, or ask us for a new manage link for the buyer.
• Talkspresso can raise the consent text. A coach who has not agreed to the new text leaves GET /providers until they do, and is asked on their next sign-in. A coach on the older text stays listed until we raise the requirement.
• If your organization stops being ready (an agreement or fee needs renewing, for example), creating bookings and checkouts and moving bookings are refused with 403 org_not_ready. Reading bookings, cancelling and refunding, and replaying events keep working, so you can finish what is already in progress. Room links stop too, and rooms already shown in your page stop loading.

Show the room in your page

The room can open inside your own page, so the buyer never leaves it. What the buyer sees depends on the browser:

1. 1.

   Your server

   GET /bookings/:id/room-links when the buyer is about to join. You get url, embed_url and parent_origins. The link is for the buyer only.

2. 2.

   Your page

   Put embed_url in an iframe on a website we registered for you, with allow="camera; microphone; autoplay; fullscreen". Also offer “Open in a new tab” with url.

3. 3.

   Talkspresso

   Shows the waiting room inside your page. The buyer waits there until the coach lets them in. The notices that a session is recorded or that AI notes are on appear inside your frame.

4. 4.

   Your page

   Listen for messages from the room (joined, left, ended) and update your screens.

curl -s "$API/bookings/BOOKING_ID/room-links" \
  -H "Authorization: Bearer $TSP_KEY"

{
  "data": {
    "booking_id": "cmwecj3ax00dm1vjzdl3ceij7",
    "role": "buyer",
    "url": "https://staging.talkspresso.com/meet/SESSION_ID?cid=BUYER_ID&ct=BUYER_TOKEN",
    "embed_url": "https://staging.talkspresso.com/meet/SESSION_ID?cid=BUYER_ID&ct=BUYER_TOKEN&embed=1",
    "parent_origins": [
      "https://staging.talkspresso.com",
      "https://partner-e2e.example.com"
    ],
    "session_ends_at": "2026-11-17T16:30:00.000Z"
  }
}

parent_origins are the websites we registered to show this room. The room refuses to load inside any other page. session_ends_at is when the booked time ends.

<iframe
  id="room"
  src="EMBED_URL_FROM_YOUR_SERVER"
  allow="camera; microphone; autoplay; fullscreen"
  style="width:100%;height:640px;border:0"
></iframe>

<script>
  // Messages come only from the room's own address, which is the host of the url we gave you.
  const roomOrigin = new URL("EMBED_URL_FROM_YOUR_SERVER").origin;
  window.addEventListener("message", (event) => {
    if (event.origin !== roomOrigin) return;
    const m = event.data;
    if (!m || m.type !== "talkspresso-room-event") return;
    if (m.event === "joined") console.log("buyer is in the room");
    if (m.event === "left" || m.event === "ended") console.log("call over", m.session_id);
  });
</script>

What the room sends to your page, and only to a website on that list:

{ "type": "talkspresso-room-event", "version": 1, "event": "joined", "session_id": "..." }

• joined: the buyer is in the call.
• left: the buyer left.
• ended: the call is over.

The room only sends messages to your page. It does not receive any from your page, so your page cannot control the call. The buyer taps to join, so the browser can ask for permission. If there is a camera or microphone problem, the room shows a plain instruction.

Things to plan for:

• Talkspresso has to switch this on for your organization (the video setting is “inside your own page”) and register your website. Until then, GET /bookings/:id/room-links answers 409 video_mode_not_enabled. A change we make to your website list or this setting can take up to about 90 seconds to reach rooms.
• Use allow="camera; microphone; autoplay; fullscreen" on the iframe. Without it the browser blocks the camera and microphone and the buyer sees a plain instruction.
• The room shows the buyer the notices that the session is recorded or that AI notes are on, and offers Join only after the buyer has seen them in full. If something on your page covers the frame, even something see-through that fills the screen (a cookie banner layer or a chat widget container), Join is withheld and the buyer is offered the own-window path. The notices must also sit fully inside the visible part of your page, so the buyer may have to scroll your page until the whole frame is in view.
• A buyer can join only near the session time. The buyer’s call link stops working two hours after the session ends (this holds for every buyer call link, not only these), and room links stop 15 minutes after it ends. Until then, whoever holds the link can join as the buyer, so keep it on your server and give it only to that buyer.
• Make the frame at least 300 pixels wide and 380 pixels tall. In a smaller frame, the buyer is offered a button to open the call in a new window.
• A buyer’s link is tied to one browser at a time. If it is opened in a second browser while the first is in the room, the room asks for a name and asks the coach to let that person in.
• The coach hosts from Talkspresso. Host controls are not available inside your page. Only adults are supported, so a booking for a minor is never shown in a frame.

5. Settings you control and settings Talkspresso sets

Your organization has a Partner settings screen for owners and admins. It shows each setting, who can change it, when it last changed and your go-live checklist. Your developers can read the same data with GET /settings.

You control

Talkspresso sets, after your agreement

These can affect money, buyer data and compliance, so we set them with you. Email support@talkspresso.com to ask for a change. Every change is recorded with who made it and why.

7. Sandbox

The sandbox is our staging system with a staging copy of your organization. Build here first.

What you can book against

Staging and production use different base addresses: https://api-staging.talkspresso.com/partner/v1 and https://api.talkspresso.com/partner/v1. When you switch to production, change only the base address. We register your payment return address and webhook address separately for staging and for production.

9. Developer kit

Everything a developer needs to start without reading this whole guide first: a machine-readable description of the API, a Postman collection, and a small working sample website.

• Live API description: https://api-staging.talkspresso.com/partner/v1/openapi.json
• Saved copy: https://talkspresso.com/partner/openapi.json
• Postman collection: https://talkspresso.com/partner/talkspresso-partner.postman_collection.json

Open the live API description, open the saved copy, or download the Postman collection.

Good to know

• The description follows the code. If this guide and the description ever differ, the description on staging is right, and we want to hear about it.
• The saved copy can be a few days behind the live copy on staging. Use the live copy when you need the newest fields.
• On the production address the live copy answers once the partner API is turned on for production. Until then, use the staging address.