العربية Log in Request a demo

Open API

Connect your systems to Mahjoz.

An open API and webhooks: read orders, customers, services, staff and branches, and create orders and customers from your own systems.

Open API referenceGet your credentials

Mahjoz Open API

Base URL
https://api.mahjoz.io/api/open/v1
Authentication
OAuth2 Client Credentials
Events
Order webhooks, signed with HMAC-SHA256
Rate limit
60 requests per minute per API client
Availability
Business plan

What you can build with the API.

  • Create orders from your system

    Check available times, then create the order in Mahjoz from your website or app.

  • Sync customers

    Read customers, search by mobile number, and add new customers from your systems.

  • Receive order events

    Get an instant notification when an order is created, changes status, is invoiced or has its payment accepted.

  • Show your services and team

    Read items, categories, staff and branches to display them in your own interfaces.

Two ways to connect: with code or with chat.

  • Business plan

    Open API and webhooks

    For developers and tech teams: connect Mahjoz to your systems via OAuth, with specific scopes for each API client.

    Compare plans
  • Growth and Business plans

    Connect Claude and ChatGPT

    For business owners: run your business by chatting inside Claude or ChatGPT via the MCP protocol, no coding needed.

    About the AI assistant

Get started in three steps.

Authentication uses OAuth2 Client Credentials.

  1. 1

    Create an API client

    From the dashboard, go to Settings, then API integration. You'll see your client_id and client_secret. The secret is shown only once, so save it right away.

    Open API settings
  2. 2

    Get an access token

    Send your credentials with the client_credentials grant type to get a Bearer token.

    POST /oauth/token
  3. 3

    Use the token

    Add the token to the header of every request.

    Authorization: Bearer <access_token>

Fine-grained scopes for each API client.

An API client gets only the scopes it needs.

API scopes
ResourceScopesWhat they allow
Ordersorders:read orders:writeRead orders, create them, and check availability
Customerscustomers:read customers:writeRead customers, search by mobile number, and add customers
Itemsitems:readRead services and products
Staffstaff:readRead staff, their services and their working hours
Branches and categoriesbranches:read categories:readRead branches and categories
Payment methodspayment_methods:read payment_methods:writeRead and create payment methods
Transactionstransactions:read transactions:writeRead transactions and record order payments
Webhookswebhooks:read webhooks:writeManage webhook subscriptions

The * scope grants all scopes. Full details for every endpoint, with request and response examples, are in the reference.

Open API reference

Limits, events and errors.

All errors share the same shape: an error field and a message field.

  • Rate limit

    60 / minute

    Per API client. If you go over, you get a 429 code with a Retry-After header.

  • Webhooks

    3 per account

    Signed with HMAC-SHA256 in the Signature header, with 3 retries on failure.

  • Token validity

    1 year

    expires_in: 31536000 seconds.

Order events

  • order.created
  • order.updated
  • order.deleted
  • order.status_changed
  • order.invoice_created
  • order.payment_accepted

Error handling

Error codes
StatusError codeMeaning
401authentication_failedMissing, invalid, or expired token
403insufficient_scopeToken lacks the required scope
403feature_disabledThe API is not available on your current plan
422validation_errorInvalid request data
422timeslot_unavailableRequested time slot is not available
429—Rate limit exceeded
502availability_check_failedBooking service unreachable

Developer support.

Need help with your integration?

If you use Mahjoz for your business, contact the support team.

Help center

Sell anything.Run everything.Grow every customer.

  1. WebsiteFor your customers

  2. DashboardFor you

  3. Staff appFor your team

  4. POSFor your team

  5. Customer appFor your customers

Run your whole business on one platform. Talk to our sales team and we'll show you Mahjoz working the way it would in your business.

  • Free demo
  • No commitment
  • No commission on your sales
Request a demo Chat on WhatsApp

+966 58 150 4066 · info@mahjoz.io