Overview
The TeachMe.To Partner API lets approved partners add coaching to their own products. You search TeachMe.To coaches by skill and place, show them in your own design, and link each learner to TeachMe.To. TeachMe.To handles the booking, payment, scheduling, and the lesson itself. You earn revenue on purchases made through your links, as set out in your partner agreement.
Version 1 has these properties:
- Read-only listings. The listings endpoint returns coaches. It never creates a booking, charges a card, or changes data. Partners we approve for it can also book and take payment in their own app. See Native booking and payment.
- Server-side. Every request carries a secret key, so every request must come from your backend.
- Public data only. Responses hold what a learner sees on a public TeachMe.To profile. Contact details, calendars, exact addresses, meeting links, and coach pay never leave TeachMe.To.
- Two kinds of coaching. Online lessons are available worldwide. In-person lessons are available in the United States and Canada.
All requests use HTTPS. All responses are JSON encoded in UTF-8. All prices are in US dollars.
Getting access
- Apply. Tell us about your product on the partner page. We review every application and reply by email.
- Sign in. When we approve you, we email a link to your partner portal. Sign in with the email you applied with.
- Create a key. In the portal, create an API key. The full key is shown once. Copy it straight into your server’s secret store.
- Build. Follow the Quickstart. Your portal shows your referral link, your clicks, and your earnings.
When you create a key, choose what it does. Every key carries the listings:read scope. Book lessons adds agent:read and agent:book. Book and take payment in your app also adds agent:pay_in_app for native booking. Keys expire 365 days after creation. You can hold up to 3 active keys at a time, which lets you rotate without downtime.
Quickstart
Store your key as TEACHMETO_PARTNER_API_KEY in your server environment, then make your first request:
curl 'https://api.teachme.to/v1/partner/listings?skill=tennis&modality=online&limit=20' \
-H "Authorization: Bearer $TEACHMETO_PARTNER_API_KEY"The same request from a Node.js server:
const response = await fetch(
'https://api.teachme.to/v1/partner/listings?' +
new URLSearchParams({ skill: 'tennis', modality: 'online', limit: '20' }),
{ headers: { Authorization: `Bearer ${process.env.TEACHMETO_PARTNER_API_KEY}` } }
);
if (!response.ok) throw new Error(`Partner API returned ${response.status}`);
const { data, pagination } = await response.json();Show each result in your product. When a learner picks a coach, send them to that result’s bookingUrl exactly as returned.
Build with an AI agent
Give your coding agent a head start
The prompt carries the full v1 contract: authentication, parameters, response fields, error codes, regional limits, and the attribution rule. Paste it into Claude Code, Codex, Cursor, or any coding agent. Add your approved key on your server when the agent asks for it.
You are adding TeachMe.To coach discovery to my product.
Goal: my users find coaches inside my product, then book and pay on TeachMe.To. I earn attributed booking revenue. I never recruit coaches or run lessons.
## API contract
Base URL: https://api.teachme.to/v1/partner
Endpoint: GET /listings
Auth header: Authorization: Bearer <TEACHMETO_PARTNER_API_KEY>
Scope: listings:read
Call this API only from a server. Read the key from an environment variable. Never put the key in browser JavaScript, a mobile binary, a public repository, or logs. Never send the key to the browser in a server-rendered payload.
Query parameters for every request:
- skill: required string, for example tennis, golf, or pickleball
- modality: required, either online or in_person
- limit: optional integer from 1 to 50, defaults to 20
- cursor: optional string, use pagination.nextCursor from the previous page
- sort: optional, recommended (default), price, or distance. distance works only when modality is in_person
Extra required parameters when modality is in_person:
- country: US or CA
- latitude: number from -85 to 85
- longitude: number from -180 to 180
- radiusMiles: number from 1 to 100
Online coaching is available worldwide. Local coaching is limited to the United States and Canada. Reject an in_person search outside those two countries before you call the API.
Example online request:
curl 'https://api.teachme.to/v1/partner/listings?skill=tennis&modality=online&limit=20' -H "Authorization: Bearer $TEACHMETO_PARTNER_API_KEY"
Example local request:
curl 'https://api.teachme.to/v1/partner/listings?skill=tennis&modality=in_person&country=US&latitude=32.7157&longitude=-117.1611&radiusMiles=25&limit=20' -H "Authorization: Bearer $TEACHMETO_PARTNER_API_KEY"
## Response shape
A 200 response returns this JSON:
{
"data": [
{
"id": "listing_01",
"name": "Jordan",
"avatarUrl": "https://media.teachme.to/example.webp",
"bio": "Patient tennis coach for beginners and returning players.",
"skill": "tennis",
"modality": "online",
"rating": 4.9,
"reviewCount": 82,
"lessonsCount": 340,
"startingPrice": { "amount": 65, "currency": "USD" },
"packPrices": [
{ "lessons": 1, "pricePerLesson": 79, "currency": "USD" },
{ "lessons": 3, "pricePerLesson": 72, "currency": "USD" },
{ "lessons": 10, "pricePerLesson": 65, "currency": "USD" }
],
"locationFeeFrom": null,
"happyStudentScore": 92,
"isSuperCoach": true,
"certification": "PTR Certified",
"availabilityHoursPerWeek": 14,
"badges": [{ "key": "superCoach", "label": "SuperCoach" }],
"distanceMiles": null,
"locations": [],
"bookingUrl": "https://teachme.to/listings/tennis/jordan?utm_medium=partner_api&utm_source=your-partner-ref&ref=your-partner-ref&online=true"
}
],
"pagination": { "limit": 20, "nextCursor": null }
}
The fields above are the complete public surface. The API never returns coach contact details, precise coordinates, calendars, meeting links, payout rates, or internal marketplace fields. Do not model or request those fields.
avatarUrl, bio, certification, availabilityHoursPerWeek, and happyStudentScore can be null. locations is empty, and locationFeeFrom and distanceMiles are null, for online listings. Handle each case in the UI.
startingPrice is the per-lesson price of a 10-lesson pack. packPrices lists the per-lesson price for 1, 3, and 10 lessons; the 10-lesson entry equals startingPrice. A listing may return only the 10-lesson entry. Prices exclude any location fee. For local listings, locationFeeFrom is the lowest fee a student may pay to use a venue, and 0 means at least one venue is free.
## Errors and limits
- 400 with code INVALID_REQUEST: your query failed validation. Read the errors array.
- 400 with code INVALID_CURSOR: discard the cursor and restart pagination. Restart whenever filters, page size, or credentials change.
- 401 with code UNAUTHORIZED: the key is missing, wrong, or lacks listings:read.
- 429 with code RATE_LIMITED: honor the Retry-After header. Read RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset on every response.
- 503 with code SERVICE_UNAVAILABLE: retry with exponential backoff and jitter.
Responses carry Cache-Control: private, no-store. Never store a response in a shared or public cache, such as a CDN.
## What to build
1. Write a typed server-side client for GET /listings. Add a request timeout. Retry 429 and 503 with exponential backoff.
2. Add a discovery surface that fits my product. Show name, avatar, bio, rating, review count, lessons count, starting price, and city and distance for local coaches. Show badges when present.
3. Add a search input for skill. Add a location input for local search. Geocode the location to latitude and longitude before you call the API.
4. Send every user to the returned bookingUrl to book and pay. Use the URL exactly as returned. Never rewrite it, strip its query parameters, or wrap it in a redirect that drops parameters. That URL carries my partner attribution and my revenue depends on it.
5. Paginate with pagination.nextCursor. Stop when nextCursor is null.
6. Render a clear empty state when data is empty.
7. Write tests for the client, the error paths, and the attribution rule that bookingUrl passes through unchanged.
## Before you start
Ask me for my TeachMe.To partner API key. Store it as TEACHMETO_PARTNER_API_KEY in server environment configuration. Tell me which files you plan to add or change, then wait for my approval.
If I do not have a key yet, tell me to apply at https://teachme.to/partners#apply.Authentication
Send your key as a Bearer token in the Authorization header of every request:
Authorization: Bearer YOUR_PARTNER_API_KEYA missing, wrong, expired, or revoked key returns 401 UNAUTHORIZED. The response does not say which, so that a stolen or guessed key reveals nothing.
Keep your key on your server. Never put it in browser JavaScript, a mobile app, a public repository, a server-rendered page, or logs. Anyone who holds the key can use your rate limit and act as you.
Rotating a key
- Create a new key in the partner portal.
- Deploy it to your servers.
- Confirm traffic succeeds with the new key.
- Revoke the old key in the portal.
If a key leaks, revoke it in the portal at once, then email support@teachme.to with your partner ref.
List coach listings
/v1/partner/listingsScope listings:readReturns bookable coach listings for one skill, either online or near a point in the United States or Canada. Only coaches with a live profile and a published price appear. For in-person searches, a coach appears only when they have open time at a venue inside the radius.
| Parameter | Type | Description |
|---|---|---|
skillRequired | string | A TeachMe.To skill slug, such as tennis or spanish. See Skills. An unknown slug returns an empty list, not an error. |
modalityRequired | enum | online for remote lessons, available worldwide. in_person for lessons at a venue in the United States or Canada. |
sortOptional | enum | recommended (default) uses TeachMe.To ranking. price lists the lowest starting price first. distance lists the closest venue first and works only with in_person. |
limitOptional | integer | Listings per page, from 1 to 50. Defaults to 20. |
cursorOptional | string | The pagination.nextCursor value from the previous page. See Pagination. |
| Parameter | Type | Description |
|---|---|---|
countryRequired | enum | US or CA. The country of the search point. |
latitudeRequired | number | Latitude of the search point, from -85 to 85. |
longitudeRequired | number | Longitude of the search point, from -180 to 180. |
radiusMilesRequired | number | Search radius in miles, from 1 to 100. |
Parameters are strict. An unknown parameter, or an in-person parameter on an online request, returns 400 INVALID_REQUEST. Check that an in-person search point is in the United States or Canada before you call the API.
Example: coaches near a point
curl 'https://api.teachme.to/v1/partner/listings?skill=tennis&modality=in_person&country=US&latitude=32.7157&longitude=-117.1611&radiusMiles=25&sort=distance' \
-H "Authorization: Bearer $TEACHMETO_PARTNER_API_KEY"Response
A 200 response holds a data array of listing objects and a pagination object. An empty data array means no coaches matched. Show an empty state rather than an error.
{
"data": [
{
"id": "listing_01",
"name": "Jordan",
"avatarUrl": "https://media.teachme.to/example.webp",
"bio": "Patient tennis coach for beginners and returning players.",
"skill": "tennis",
"modality": "in_person",
"rating": 4.9,
"reviewCount": 82,
"lessonsCount": 340,
"startingPrice": {
"amount": 65,
"currency": "USD"
},
"packPrices": [
{
"lessons": 1,
"pricePerLesson": 79,
"currency": "USD"
},
{
"lessons": 3,
"pricePerLesson": 72,
"currency": "USD"
},
{
"lessons": 10,
"pricePerLesson": 65,
"currency": "USD"
}
],
"locationFeeFrom": {
"amount": 0,
"currency": "USD"
},
"happyStudentScore": 92,
"isSuperCoach": true,
"certification": "PTR Certified",
"availabilityHoursPerWeek": 14,
"badges": [
{
"key": "superCoach",
"label": "SuperCoach"
}
],
"distanceMiles": 3.4,
"locations": [
{
"city": "San Diego",
"state": "CA",
"country": "US"
}
],
"bookingUrl": "https://teachme.to/listings/tennis/jordan?utm_medium=partner_api&utm_source=your-partner-ref&ref=your-partner-ref"
}
],
"pagination": {
"limit": 20,
"nextCursor": "eyJ2IjoxLCJvZmZzZXQiOjIw…"
}
}Skills
The skill parameter takes a TeachMe.To skill slug. These are the skills with the most coaches today. Other slugs work too. An unknown slug returns an empty list.
pickleballtennisgolfsoccerbasketballbaseballfootballvolleyballsurfingpersonal-trainingguitarpianosingingmusic-productionenglishspanishfrenchmathreading-and-writingsciences
Language and academic skills are taught mostly online. Football and surfing are taught in person only today.
The listing object
Each item in data is a listing: one coach teaching one skill. A money value is an object with an amount in dollars and a currency that is always USD.
| Field | Type | Description |
|---|---|---|
id | string | Stable identifier for the listing. |
name | string | The coach’s public display name, usually a first name. |
avatarUrl | string | null | URL of the coach’s profile photo. |
bio | string | null | The coach’s public bio. |
skill | string | Skill slug of the listing. Matches the requested skill. |
modality | enum | online or in_person. Matches the requested modality. |
rating | number | Average student rating, from 0 to 5. |
reviewCount | integer | Number of published reviews. |
lessonsCount | integer | Lessons the coach has taught on TeachMe.To. |
startingPrice | money | Lowest price per lesson, which is the per-lesson price of a 10-lesson pack. Always in USD. Excludes any location fee. |
packPrices | array | Per-lesson price for each pack size (lessons is 1, 3, or 10). The 10-lesson entry equals startingPrice. Some listings return only the 10-lesson entry. |
locationFeeFrom | money | null | For in-person listings, the lowest venue fee a student may pay. 0 means at least one venue is free. Always null for online listings. |
happyStudentScore | number | null | TeachMe.To score for how satisfied the coach’s students are. Higher is better. Null when the coach has too little history. |
isSuperCoach | boolean | True when the coach holds TeachMe.To SuperCoach status. |
certification | string | null | Name of the coach’s leading certification, such as “PTR Certified”. |
availabilityHoursPerWeek | number | null | Hours per week the coach is open for booking. |
badges | array | Highlights for this result, each with a stable key and a display label. Show the label as given. |
distanceMiles | number | null | Miles from the search point to the closest venue, to one decimal place. Null for online listings. |
locations | array | City-level venues inside the search radius, each with city, state, and country. Empty for online listings. |
bookingUrl | string | Where to send the learner to book and pay. Carries your attribution. See Booking links and attribution. |
These fields are the complete response. We may add fields in version 1, so ignore fields you do not recognize. We will not remove or rename a field in version 1.
Pagination
Results come in pages. When more results exist, pagination.nextCursor holds a string. Pass it back as cursor, with every other parameter unchanged, to get the next page. When nextCursor is null, you have every result.
- Treat the cursor as an opaque string. Do not decode or build one.
- A cursor works only with the same key and the same query. Change a filter, the page size, or the key, and start again without a cursor.
- One search returns at most 150 listings across all its pages. Narrow the search, for example with a smaller radius, to see different coaches.
Booking links and attribution
Every listing has a bookingUrl on teachme.to. It carries your partner ref in the ref and utm_source parameters. Online results also carry online=true, which opens the coach’s online booking.
When a learner follows that link and buys, TeachMe.To records the purchase against your partner account. Your partner portal shows the result, and your partner agreement sets what you earn.
Use the booking URL exactly as returned. Do not rewrite it, shorten it, strip its query parameters, or send it through a redirect that drops them. A changed link can lose your attribution, and we cannot credit purchases we cannot attribute.
You may open the link in a new tab, an in-app browser, or the learner’s default browser.
Native booking and payment
Approved partners can let learners pick a coach, choose a time, and pay without leaving their app. You build the screens in your own design. TeachMe.To hosts the coach, the schedule, and the payment, and the card goes straight from Stripe’s payment sheet to Stripe.
This uses the Agent Booking API at https://api.teachme.to/agent/v1. Create a key with Book and take payment in your app in your partner portal. It carries the agent:read, agent:book, and agent:pay_in_app scopes. Without agent:pay_in_app, an in-app payment returns 403 insufficient_scope. Your first booking key turns on commission for bookings made through the API.
GET /coachesSearch coaches by skill and place. Each result carries the next open time and itsslotKey.GET /coaches/{listingId}/slotslists more times.POST /quotesPrice a package for a slot. ReturnsquoteIdand the total. Show the learner that total before they pay.POST /buyers/resolveSend the learner’s name, email, and phone number. Returns abuyerToken. A new email creates the learner’s TeachMe.To account.POST /bookingsSendbuyerToken,quoteId,slotKey, andpayment: { type: "in_app" }. Returns201with the booking and apaymentobject. Nothing is charged yet.Payment sheetInitialize Stripe withpayment.publishableKeyand present PaymentSheet (iOS or Android) or the Payment Element (web) withpayment.clientSecret. The learner pays by card, Apple Pay, or Google Pay and completes any card check there.GET /bookings/{id}When Stripe confirms the payment, the booking turnspaidand the coach gets the requested time to confirm. Read the booking for its payment status and the coach’s answer.
curl -X POST 'https://api.teachme.to/agent/v1/bookings' \
-H "Authorization: Bearer $TEACHMETO_PARTNER_API_KEY" \
-H "Idempotency-Key: 6f1c2d3e-0a4b-4c5d-8e9f-1a2b3c4d5e6f" \
-H "Content-Type: application/json" \
-d '{
"buyerToken": "BUYER_TOKEN",
"quoteId": "QUOTE_ID",
"slotKey": "SLOT_KEY",
"payment": { "type": "in_app" }
}'{
"booking": {
"id": "9c1d2e3f-4a5b-4c6d-8e7f-000000000010",
"status": "pending_payment",
"paymentStatus": "awaiting_payment",
"amountCharged": {
"amount": 0,
"currency": "USD"
}
},
"lesson": {
"startAt": "2026-11-08T17:00:00.000Z",
"endAt": "2026-11-08T18:00:00.000Z",
"timezone": "America/Los_Angeles"
},
"proposal": null,
"paymentStatus": "awaiting_payment",
"paymentUrl": null,
"payment": {
"type": "in_app",
"paymentIntentId": "pi_…",
"clientSecret": "pi_…_secret_…",
"publishableKey": "pk_live_…",
"amount": {
"amount": 33000,
"currency": "USD"
}
}
}// iOS (Stripe iOS SDK). Values come from your server, never your API key.
STPAPIClient.shared.publishableKey = payment.publishableKey
var configuration = PaymentSheet.Configuration()
configuration.merchantDisplayName = "Your app"
configuration.applePay = .init(merchantId: "merchant.com.yourapp", merchantCountryCode: "US")
let sheet = PaymentSheet(paymentIntentClientSecret: payment.clientSecret,
configuration: configuration)
sheet.present(from: viewController) { result in
// .completed: show the confirmation, then read GET /bookings/{id}
}Call the booking API from your server. Send only payment.clientSecret and payment.publishableKey to the learner’s device. Never ship your API key in the app, and never log or store the client secret.
Retries and payment status
- Every
POSTneeds anIdempotency-Keyheader. Sending the same key and body again returns the same booking and client secret, so a dropped connection never creates a second booking. awaiting_paymentmeans the learner has not finished paying.paidmeans the payment succeeded.failedmeans the last card was declined. The learner can try another card with the same client secret.- If the chosen time was taken after the quote, the booking call returns
409 slot_unavailableand creates nothing. List times again and quote the new one. - The coach confirms the requested first-lesson time after payment. Show the learner that the time is requested, not confirmed.
Your student discount
If your account has a student discount, you decide who gets it. Send applyPartnerDiscount: true on POST /quotes for a learner who qualifies, for example a paying member of your app. The amount and the skills it covers are fixed on your account. The quote shows it as a discount line and in partnerDiscount, and the total already includes it. Only your key can book that quote, and only with payment set. The discount is not applied to Coach Site packages or to prices in other currencies.
Apple Pay and Google Pay
- Register a merchant ID in your Apple Developer account and email it to support@teachme.to.
- We send you a certificate signing request from our Stripe account. Upload it to Apple for that merchant ID.
- Send us the certificate Apple returns. Apple Pay then works in your app.
Use a new merchant ID for TeachMe.To bookings, not one you already use with your own Stripe account. Its certificate then belongs to our Stripe account and leaves your existing Apple Pay setup unchanged. An app can carry several merchant IDs.
Cards need no setup. For Google Pay, request production access for your app in the Google Pay and Wallet Console, as Google requires for any app, and choose the Gateway integration. Nothing is needed from us.
For the Payment Element on a website, add each domain under Book and take payment in your app in your partner portal. Host Stripe’s Apple Pay domain file at /.well-known/apple-developer-merchantid-domain-association on that domain, then choose Check again. The portal shows when Apple Pay and Google Pay are ready. Cards and Link work on any domain.
Attribution and the full contract
Every booking made with your key is credited to your partner account. Your portal shows it with your link referrals. The complete request and response schema is at https://api.teachme.to/agent/v1/openapi.json.
Rate limits
Each key has its own limit per one-minute window. The default is 120 requests per minute. If you need more, ask us. Every response to a valid key carries these headers:
| Header | Description |
|---|---|
RateLimit-Limit | Requests allowed in each window. |
RateLimit-Remaining | Requests left in the current window. |
RateLimit-Reset | When the window resets, in Unix seconds. |
Retry-After | On a 429 only: seconds to wait before you retry. |
HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 120
RateLimit-Remaining: 0
RateLimit-Reset: 1793318460
Retry-After: 23Errors
Errors use standard HTTP status codes. The body is JSON with a human-readable message and a stable code. Branch on the code, not the message. A 400 INVALID_REQUEST also includes an errors array that names each bad parameter.
{
"message": "Rate limit exceeded",
"code": "RATE_LIMITED"
}| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | INVALID_REQUEST | A parameter is missing, out of range, or not recognized. | Read the errors array, fix the request, and do not retry it unchanged. |
| 400 | INVALID_CURSOR | The cursor is malformed, or belongs to a different query or key. | Drop the cursor and start again from the first page. |
| 401 | UNAUTHORIZED | The key is missing, wrong, expired, revoked, or lacks listings:read. | Check the key in your partner portal. Do not retry with the same key. |
| 429 | RATE_LIMITED | This key used its requests for the current minute. | Wait for the number of seconds in Retry-After, then retry. |
| 503 | SERVICE_UNAVAILABLE | TeachMe.To could not complete the request. | Retry with exponential backoff and jitter. |
Set a request timeout of about 10 seconds. Retry only 429 and 503 responses, and only a few times.
Caching and freshness
Responses carry Cache-Control: private, no-store, because each booking URL holds your partner ref. Never store a response in a shared cache, such as a CDN or a public edge cache.
You may cache results on your own server to stay within your rate limit. Prices, ratings, and availability change, so refresh cached results at least once a day, and drop a listing that no longer appears in a fresh search.
Usage guidelines
These guidelines keep the experience good for learners and fair to coaches. They apply alongside your partner agreement and the TeachMe.To Terms of Service.
- Show listings accurately. Do not change prices, ratings, review counts, or credentials. When you show a price, show it as a starting price.
- Book on TeachMe.To. Send learners to the returned booking URL, or book through native booking if we approved you for it. Take payment only through the payment sheet the booking API returns. Never collect card details yourself, and do not arrange lessons with coaches outside TeachMe.To.
- Use the data in your product only. Do not resell, republish in bulk, or share listing data with others. Do not use it to contact or recruit coaches.
- Respect the limits. Do not crawl every skill and place to copy the catalog, or spread traffic across keys to get around a rate limit.
- Protect your keys. Keep them on your server and revoke any key you think has leaked.
We may limit, suspend, or revoke a key that breaks these guidelines or puts learners or coaches at risk. When we can, we contact you first.
Changelog
Approved partners can book and take payment in their own app with
payment: { type: "in_app" }and theagent:pay_in_appscope. Partners create these keys in the portal, register website domains for Apple Pay and Google Pay there, and can apply their student discount withapplyPartnerDiscount.Approved partners create and revoke their own keys in the partner portal.
Listings add
lessonsCount,packPrices,locationFeeFrom,happyStudentScore,isSuperCoach,certification,availabilityHoursPerWeek,badges, anddistanceMiles. Thesortparameter addspriceanddistance.Version 1 launches with
GET /v1/partner/listings.
Support
Email support@teachme.to with “Partner API” in the subject. Include your partner ref and, for a failed request, the time, the full request URL without your key, and the response status and code. Never send us your key.
Not a partner yet? Apply on the partner page.