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 eight 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.
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), 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.
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.