The DojoMesh API lets your own website, a developer, or another tool talk directly to your academy's data: read the class schedule, add leads, book trial classes, take contact messages, look up members and record payments. This guide is the reference. It assumes you, or whoever is building for you, is comfortable with a web form or a few lines of code.
What the API is for
Most academies never need it. The built-in landing page, the Website Form and the Schedule Embed Code cover a website without writing anything; see Your website and domain. The API is for three situations:
- A website you host elsewhere that should show your live timetable and send bookings and messages into DojoMesh, without ever touching your database.
- An existing signup form on your site that should also create a lead in DojoMesh when someone submits it.
- A till or payment device, such as a Square Terminal, whose sales should appear on the right member's record automatically.
Everything the API writes shows up in your dashboard the same way it would if you had typed it in: leads on the Leads page, bookings under Trial Bookings, payments on the member's profile and in your reports.
Get your key
Open Settings API Integration. The page shows the three things every call needs: the API Endpoint, your Tenant ID (your academy's subdomain), and your API Key.
New academies start with a default key that only allows adding members. Click Generate New API Key once to get a random key that unlocks the rest. Do the same any time a key has been shared or pasted somewhere public: the old key stops working the moment you confirm, so update anything that uses it.
Anyone holding it can read your members' contact details and record payments against them. Use it from your own server or a script, never inside a public web page or an app someone could inspect. Keep it in a file outside your website's public folder.
Make a call
Every request goes to the same address with two headers, and says which action it wants. Read-only actions accept GET; anything that writes must be a POST. Data can be sent as JSON or as an ordinary form post.
| Endpoint | https://www.dojomesh.com/platform/api.php |
|---|---|
| Header | X-API-Key: your key |
| Header | X-Tenant: your-academy |
| Action | action= as a query parameter, a form field, or a JSON field |
A first call to try from a terminal, which lists your timetable:
| curl "https://www.dojomesh.com/platform/api.php?action=list_schedule" -H "X-API-Key: your key" -H "X-Tenant: your-academy" |
Every reply has the same shape, so one piece of code can handle all of them:
| Field | Meaning |
|---|---|
| success | true or false |
| message | A sentence you can show to a person. On a validation problem it names the field. |
| data | The result, or null |
| timestamp | When the reply was produced |
The HTTP status tells you what kind of reply it is: 200 for a read or an already-recorded duplicate, 201 for something newly created, 400 for a field problem, 401 for a wrong key or tenant, 403 when the action needs a generated key, 404 when a member is not found, 429 when you are calling too fast.
The actions
The first works with any key. The rest need a key you generated in step 1.
create_member (POST)
Adds a person, as a lead by default. Required: first_name, last_name, email. Optional: phone, address fields (mailing_address, city, province, postal_code), birth_date (YYYY-MM-DD), gender, emergency contact and medical fields, and status (leave it out for a lead). This is the call behind the ready-made PHP snippet on the API page, meant to be added to a form handler you already have. No action is needed; it is the default.
find_member (GET or POST)
Finds members by one of member_id, email (exact), phone (digits are compared, so +61 4xx and 04xx match) or name (partial). Returns up to 25 people with their status, plan, last payment date and the date they are paid through. Only contact and membership details are returned, never medical information.
record_payment (POST)
Records a payment against one member, exactly as the Add Payment screen does. Required: member_id (or member_email when it belongs to one person) and amount, tax inclusive, in your academy currency. Recommended: square_payment_id, any transaction reference, which is shown on the payment, used to check refunds, and makes the call safe to retry: the same reference never creates a second payment. Optional: payment_method (defaults to square), payment_date, due_date, plan_id to assign a plan, tax_rate_ids to record the tax portion, note. Member status is never changed by this call.
list_plans and list_tax_rates (GET or POST)
Your membership plans, with price, type, description and whether each is marked to show on your website, and your active tax rates. Use them for the IDs the other calls accept, or to show memberships on your own site.
list_schedule (GET or POST)
Your active weekly timetable in day and time order: each class's ID, day, start and end time, title and description, plus your timezone and academy name. Only the base schedule is included, not holiday variants or one-off exceptions. Cache it for a few minutes on your side rather than fetching on every page view.
list_events (GET or POST)
Your published special events from Manage Special Events, such as seminars, competitions and camps. Each one carries its ID, title, plain-text description, start and end date, start and end time, an image_url ready for an image tag, the button text and link you set, and a registration block: whether the registration form is on, the type (free, pay in person or pay online), the price and currency, a price_options list when the event has more than one price (for example Kids and Adults, or One session and Both sessions: each with an option_id, label and price, in which case price is the lowest, for "From $30"), and a register_url pointing at the events section of your DojoMesh landing page, where the form and card payment live. Upcoming events come back by default, soonest first, with today worked out in your academy timezone. Add include_past=1 for every event newest first, event_id for a single event, or limit (up to 200). Cache it like the timetable. When an online-paid event is listed, a card_payments block gives the public values your page needs to mount a card form: the Stripe publishable key, or the Square application ID, location ID and environment.
register_event (POST)
Registers a person for a special event. Required: event_id, participant_name, email, phone, and option_id when the event lists price_options (the option's price is what gets charged; the reply echoes option_label). For an event that is paid online, also send the card token your page collected in the browser: stripe_payment_method from Stripe.js, or card_nonce from the Square Web Payments SDK. The event's own price is charged first, and nothing is saved if the card is declined (HTTP 402 with the reason). Free and pay-at-the-door events are recorded straight away. The reply carries the registration ID, payment status and gateway reference, and a message written for the participant. The academy gets the same email as it does from its landing page, and the registration shows under the event in Manage Special Events.
list_waivers (GET or POST)
The agreements set up under Settings, then Waivers, that are marked to show on signup: each one's waiver_id, version_id, title, full text (plain and HTML), whether it is required or optional, who it applies to (everyone, adults, under 18) and the checkbox wording. Render them on your own form, then send the answers with book_trial or create_member: waiver_accept[id]=1 for a required waiver, waiver_response[id]=yes or no for an optional one, waiver_version[id] with the version you displayed, waiver_signer_name (the typed full name is the signature) and waiver_signer_relationship (self, parent or guardian). A required waiver may carry several acknowledgment lines; tick each one with waiver_ack[id][n]=1 (n is the line's position in acknowledgments). When the participant is under the academy's age_of_majority and the waiver has a guardian_clause, send date_of_birth and waiver_guardian[id]=1 once the parent or guardian has ticked it. If any waiver field is sent, every applicable waiver must be answered; otherwise the call returns a message you can show the visitor. The signature is stored on the member's profile with the exact text version, the time and the IP address.
book_trial (POST)
Books a free class from your website. Required: first_name, email, phone. Optional: last_name, class_schedule_id from list_schedule, preferred_date, note. Creates a lead (or reuses the person with that email), adds a booking under Trial Bookings with the class details, and emails your academy address with reply-to set to the person. The message in the reply is written to be shown to them.
contact_message (POST)
A contact form. Required: name, email, message. Optional: phone. Creates or matches a lead, saves the message as a note on their record so it is never lost in an inbox, and emails you with reply-to set to the sender.
The API page in your dashboard shows every call above as a copy-and-paste cURL command already filled in with your endpoint, tenant and key, together with sample responses.
Recipe: your own website on DojoMesh data
This is how a standalone academy website runs entirely on the API, with no database of its own, so it can be hosted anywhere and edited over FTP safely.
- Keep the key in a small config file one level above the website's public folder, and load it from there.
- On each page view, read the timetable from a local cache. If the cache is older than five minutes, call list_schedule (and list_plans for memberships, list_events for seminars and competitions), save the reply, and render from it. If the call fails, keep showing the last good copy.
- Put a booking form on the page listing the classes from the cache, with the class ID as the option value. On submit, check your own spam protection first (a hidden field bots fill in, and a minimum few seconds between page load and submit), then send the fields to book_trial and show its message to the visitor.
- Do the same for a contact form with contact_message, and for seminar sign-ups with register_event: show the events from list_events, and for online-paid ones mount a card field with the key in card_payments, turn the card into a token in the browser, and send the token with the registration. The card number never touches your server.
That is the whole integration. The academy sees bookings, leads and messages in the dashboard within seconds, and changes a class once, in DojoMesh, for both the dashboard and the website. DojoMesh builds sites this way for academies on the managed website plan; see Your website and domain.
Recipe: Square Terminal sales onto member records
If you take in-person payments on a Square Terminal and want each sale to land on the right member without retyping it:
- In Square, set up a webhook for completed payments that points at a small script on your own server.
- When a payment arrives, identify the member. Match by the Square customer's email or phone using find_member, or keep your own mapping of Square customer IDs to DojoMesh member IDs.
- Call record_payment with the member ID, the amount, and the Square payment ID as square_payment_id. Because Square may deliver a webhook more than once, the payment ID keeps you from recording it twice.
- If you charge tax, pass the tax rate IDs from list_tax_rates so the tax portion is split out for your reports.
The payment then appears on the member's profile and in Manage Payments, and can be refunded from DojoMesh like any other.
Limits, errors and safety
- 120 calls per minute per academy. Above that you receive 429 until the minute passes. Repeated wrong keys from one address are blocked for ten minutes.
- A wrong key is 401 with "Invalid API key". A call that needs a generated key while you are on the default key is 403, and the message tells you to generate one.
- Validation failures are 400 and the message names the field, so you can show it to the person filling in a form.
- Every call is logged on our side with the academy, action and outcome, so if you ever wonder whether a key has been used, ask and we can tell you.
- Regenerating the key is instant and invalidates the old one immediately. Plan a minute of downtime for anything that uses it, or update the new key first and regenerate second where you can.
Common questions
Does the API cost extra?
No. It is included with every academy account at no charge.
Can it create a paying member, not just a lead?
create_member accepts a status field, but we recommend leaving people as leads and converting them in the dashboard once they have paid or signed a waiver, so your active count stays honest.
Can the API change a member's status, pause them or delete them?
Not today. Those are decisions with side effects (billing pauses, history rows) that we keep in the dashboard. Payments recorded through the API never change a member's status.
Can I get bookings or payments out, not just in?
Reads today are members, plans, tax rates and the schedule. If you need a report or export, the dashboard's export tools cover it; tell us what you are building if you need more from the API.
I am not a developer. Who can build this for me?
Any web developer can work from this page. If you would rather not involve one, the managed website plan includes a site built on the API for you.