Open API
Mahjoz Open API
Integrate your systems with Mahjoz. Manage orders, customers, services, staff, and availability programmatically.
https://api.mahjoz.io/api/open/v1Authentication
The Open API uses OAuth2 Client Credentials flow. Get your credentials from the Mahjoz dashboard.
1
Get Your Credentials
Create an API client from your Mahjoz dashboard. Save the client_id and client_secret β the secret is only shown once.
Open API Settings2
Get Access Token
POST /oauth/token
Content-Type: application/json
{
"grant_type": "client_credentials",
"client_id": "<client_id>",
"client_secret": "<client_secret>",
"scope": ""
}3
Use the Token
Authorization: Bearer <access_token>Rate Limiting
Requests are rate-limited per client. Default: 60 requests/minute. When exceeded, the API returns 429 Too Many Requests with a Retry-After header.
Scopes
| Scope | Description |
|---|---|
orders:read | Read orders |
orders:write | Create orders and check availability |
customers:read | Read customers |
customers:write | Create customers |
items:read | Read items (services and products) |
staff:read | Read staff and their services |
branches:read | Read branches |
categories:read | Read categories |
* | All scopes |
Pagination
List endpoints return paginated results. Use per_page (default 25, max 100) and page parameters.
{
"data": [...],
"links": { "first": "...", "last": "...", "prev": null, "next": "..." },
"meta": { "current_page": 1, "last_page": 5, "per_page": 25, "total": 120 }
}Error Handling
| HTTP Code | Error Code | Description |
|---|---|---|
| 401 | authentication_failed | Missing, invalid, or expired token |
| 403 | insufficient_scope | Token lacks required scope |
| 403 | feature_disabled | Open API not available on current plan |
| 422 | validation_error | Invalid request data |
| 422 | timeslot_unavailable | Requested time slot is not available |
| 429 | β | Rate limit exceeded |
| 502 | availability_check_failed | Booking service unreachable |
API Endpoints
| Method | Endpoint | Scope |
|---|---|---|
| GET | /orders | orders:read |
| GET | /orders/{uuid} | orders:read |
| POST | /orders | orders:write |
| POST | /availability | orders:write |
| GET | /customers | customers:read |
| GET | /customers/{uuid} | customers:read |
| GET | /customers/phone | customers:read |
| POST | /customers | customers:write |
| GET | /items | items:read |
| GET | /items/{uuid} | items:read |
| GET | /staff | staff:read |
| GET | /staff/{uuid} | staff:read |
| GET | /branches | branches:read |
| GET | /categories | categories:read |
Ready to integrate?
Create your API client and start building with the Mahjoz Open API today.
Get API Credentials