Quickstart

Get a key

The owner of your Maalam workspace goes to Settings → API and creates a key. Give it a name that says what it is for — "CMS sync", "Website" — because that name is what shows in the list later, and in Maalam's audit trail beside anything the key does.

The key is shown once. It looks like this:

mlm_live_Ab3xQ2p7vL9mN4rT8wY1zC5hK0jF3gD6sB2xV9nM4kP7qR1tW8yZ5c9f2k

Keep it as you would a password. Maalam stores only a hash of it; if it is lost, revoke it and make another.

Check it works

curl https://api.maalam.sa/v1/integration/me \
  -H "Authorization: Bearer mlm_live_…"

{
  "organization": { "id": "d0000000-…", "slug": "demo", "name": "Demo Developer" },
  "key": { "id": "a0000000-…", "name": "CMS sync", "prefix": "mlm_live_Ab3x" }
}

A 401 means the key is wrong or revoked; a 403 with reason: "suspended" means your workspace is suspended and someone at Maalam needs to hear from you.

Push a project

Projects are addressed by slug: lowercase letters, digits and single dashes, and it becomes part of the storefront URL, so choose something that reads.

curl -X PUT https://api.maalam.sa/v1/integration/projects/alasala \
  -H "Authorization: Bearer mlm_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "مساكن الأصالة",
    "nameEn": "Alasala Residences",
    "city": "الرياض",
    "developerName": "Demo Developer",
    "description": "Phase 2, handover 2027"
  }'

201 Created the first time. Run the very same request again and it is 200 OK, with the project unchanged. That is the contract for every PUT here.

Push a unit

Units are addressed by project slug and unit code. The code is whatever your system calls the unit; it only has to be unique within the project.

curl -X PUT https://api.maalam.sa/v1/integration/projects/alasala/units/A-101 \
  -H "Authorization: Bearer mlm_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "apartment",
    "areaSqm": 150,
    "priceSar": 950000,
    "vatIncluded": true,
    "bedrooms": 3,
    "bathrooms": 2,
    "deliveryYear": 2027,
    "description": "Corner unit, north facing",
    "images": [
      "https://cdn.example.com/alasala/a-101/front.jpg",
      "https://cdn.example.com/alasala/a-101/kitchen.jpg"
    ],
    "files": [
      { "name": "Brochure", "url": "https://cdn.example.com/alasala/a-101/brochure.pdf" }
    ]
  }'

The response is the unit as Maalam now has it — including depositPercent, which fell back to your workspace's default because the request did not say.

Send a buyer

Every unit has a booking link, and it is the same shape for all of them:

https://app.maalam.sa/book/{organization slug}/{unit code}

For the unit above, that is https://app.maalam.sa/book/demo/A-101. Put it behind the "Reserve" button on your own unit page; nothing else has to be integrated for a buyer to book.

Hear back

Register a webhook under Settings → API with the events you care about, and Maalam will POST to it when the unit is held, reserved or sold. Webhooks has the payload and how to verify the signature.