API documentation For developers

API quick start

Base URL, authentication, limits and your first request with cURL or Postman.

The Miaalo API lets a website or back-end system add contacts to a Miaalo account, and create sources. This page covers what you need before your first call. Every field and error is in the API reference.

Overview

Base URLhttps://miaalo.com/api
ProtocolHTTPS, POST only
Request bodyJSON (Content-Type: application/json) or normal form fields
Response bodyJSON with a status field: 1 = success, -1 = failure
CORSAllowed from any origin, so browser code can call the API directly
Public endpointsPOST /save-number, POST /create-group

Authentication

There are no auth headers or tokens to exchange. You send a key in the request body:

FieldKeyUsed byExposure
api_keySource API keysave-numberPublic. It can only add contacts to its sources.
user_keyUser API keycreate-groupSecret. Server-side only.

The account owner finds both keys on the API Keys page in Miaalo. A source API key is created automatically for every new source. See API keys, explained.

Headers

Content-Type: application/json
Accept: application/json

Send Accept: application/json so that rate-limit errors also come back as JSON.

Your first request

cURL

curl -X POST https://miaalo.com/api/save-number \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"api_key":"YOUR_SOURCE_KEY","name":"Test Contact","phone":"9876543210"}'

Expected reply:

{ "status": 1, "data": { "message": "Success" } }

Postman

  1. Create a new request and set the method to POST.
  2. URL: https://miaalo.com/api/save-number
  3. Open Body, choose raw, and set the type to JSON.
  4. Paste {"api_key":"YOUR_SOURCE_KEY","name":"Test Contact","phone":"9876543210"} and click Send.
  5. Check the contact appears under Contacts in Miaalo.

JavaScript (browser)

const res = await fetch("https://miaalo.com/api/save-number", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Accept": "application/json" },
  body: JSON.stringify({ api_key: "YOUR_SOURCE_KEY", name: "Test Contact", phone: "9876543210" })
}).then(r => r.json());

if (res.status !== 1) console.error(res.data.message);

PHP (server)

$ch = curl_init("https://miaalo.com/api/create-group");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Content-Type: application/json", "Accept: application/json"],
    CURLOPT_POSTFIELDS => json_encode(["user_key" => getenv("MIAALO_USER_KEY"), "group_name" => "Website enquiry"]),
]);
$res = json_decode(curl_exec($ch), true);
$sourceKey = $res["status"] === 1 ? $res["key"] : null;

Errors

Application errors come back with HTTP 200 and "status": -1. Always check status, not the HTTP code. data.message explains the problem. See the error table.

Rate limits

Each IP address can make 60 requests per minute. Every response includes X-RateLimit-Limit and X-RateLimit-Remaining headers. If you go over the limit you get HTTP 429 Too Many Requests and a Retry-After header (in seconds). Wait that long, then retry.

Behaviour to know

  • Phone numbers must be Indian mobiles (10 digits starting 6 to 9). +91, 91, 0 and spaces are stripped.
  • Idempotent by phone. Sending the same number again doesn't create a duplicate. The existing contact is added to the key's sources, and its saved name and email are kept.
  • create-group is idempotent by name. The same name returns the same source and key.
  • In the API, a source is called a group (create-group, group_name). The two words mean the same thing.

Not available

  • Webhooks: Miaalo doesn't send events to your server.
  • Reading, updating or deleting contacts through the API isn't supported.
  • Other paths under /api are internal and may change without notice. Don't use them.