Grouthna CRM API

POST /api/v1/leads

A website form, landing page or another system. Upserts by phone: 201 when created, 200 when the number already exists. Ad fields (platform, campaign, ad, click ids, utm_*) credit the exact ad.

{
  "phone": "0551234567",
  "name": "Noura",
  "service_code": "LASER",
  "source": "website",
  "campaign": "Summer offer",
  "utm_source": "snapchat",
  "gclid": "…"
}

{
  "id": "lead-uuid",
  "created": true
}

GET /api/v1/leads

Newest first.

• updated_since — ISO date
• stage — stage key
• limit — 1–200 (50)
• before — ISO date, for paging

{
  "data": [
    {
      "id": "lead-uuid",
      "name": "Noura",
      "phone": "+966551234567",
      "stage": "new",
      "source": "website",
      "campaign": "Summer offer",
      "opted_out": false,
      "created_at": "2026-10-09T09:00:00Z"
    }
  ],
  "next_before": null
}

GET /api/v1/leads/{id}

The lead with its appointments.

{
  "id": "lead-uuid",
  "name": "Noura",
  "phone": "+966551234567",
  "stage": "booked",
  "appointments": [
    {
      "id": "appt-uuid",
      "start_at": "2026-10-12T07:00:00Z",
      "status": "booked",
      "doctor": "Dr. Sara",
      "service": "Cleaning"
    }
  ]
}

POST /api/v1/messages

Three shapes. A template goes any time (creates the lead if new). Text and files go into the client's open conversation: on the official number only if the client wrote in the last 24 hours; QR numbers, Telegram and website chat any time — otherwise 409 window_closed (send a template). Files are fetched once from a public HTTPS link (no redirects, 20 MB).

{
  "phone": "0551234567",
  "template": "invoice_ready",
  "params": [
    "Noura",
    "INV-1001"
  ],
  "header": {
    "link": "https://example.com/inv-1001.pdf",
    "filename": "invoice.pdf"
  },
  "buttons": [
    "ORD-1001"
  ]
}

{
  "phone": "0551234567",
  "text": "Your order is on its way"
}

{
  "phone": "0551234567",
  "media_url": "https://example.com/menu.pdf",
  "caption": "Our menu"
}

{
  "queued": true,
  "type": "text",
  "message_id": "msg-uuid",
  "conversation_id": "conv-uuid",
  "lead_id": "lead-uuid"
}

• 404 not_found — no approved template with this name
• 409 window_closed / opted_out / blocked
• 422 params count, media type or size

GET /api/v1/whatsapp/numbers

The business's QR-linked WhatsApp numbers and whether each is connected now — the number_id to send from.

{
  "data": [
    {
      "id": "number-uuid",
      "name": "Sales",
      "phone": "966551234567",
      "connected": true
    }
  ]
}

GET /api/v1/whatsapp/groups

The WhatsApp groups the number is in (connected numbers only).

• number_id — required

{
  "data": [
    {
      "id": "120363000000000001@g.us",
      "name": "VIP clients",
      "size": 48
    }
  ]
}

POST /api/v1/whatsapp/send

Send from one of your QR numbers to any number (no earlier conversation needed — it shows in the inbox) or to a group the number is in. One of text (optionally with up to 3 buttons, or a list), media_url (+caption, filename) or poll. Buttons and lists aren't officially allowed from QR numbers: they may not show and can get the number restricted — at your own risk. Paced by the number's own sending queue. 409 when the number isn't connected or the client is blocked.

{
  "number_id": "number-uuid",
  "to": "0551234567",
  "text": "Your order is ready ✅"
}

{
  "number_id": "number-uuid",
  "to": "120363000000000001@g.us",
  "media_url": "https://example.com/offer.jpg",
  "caption": "This week's offer"
}

{
  "number_id": "number-uuid",
  "to": "0551234567",
  "poll": {
    "question": "Which time suits you?",
    "options": [
      "Morning",
      "Evening"
    ],
    "multi": false
  }
}

{
  "number_id": "number-uuid",
  "to": "0551234567",
  "text": "Book your visit?",
  "buttons": [
    {
      "kind": "reply",
      "text": "Book now"
    },
    {
      "kind": "url",
      "text": "Our site",
      "url": "https://example.com"
    }
  ]
}

{
  "queued": true,
  "to": "966551234567",
  "message_id": "msg-uuid",
  "conversation_id": "conv-uuid"
}

• 404 not_found — no QR number with this id
• 409 not_connected / blocked
• 422 media type or size, poll options

GET /api/v1/conversations

Up to 10 conversations (newest first) with their latest messages, oldest → newest. Team notes are left out.

• phone — required
• limit — messages per conversation, 1–200 (50)
• before — ISO date, to page back

{
  "data": {
    "contact": {
      "id": "contact-uuid",
      "name": "Noura",
      "phone": "+966551234567",
      "opted_out": false,
      "blocked": false
    },
    "conversations": [
      {
        "id": "conv-uuid",
        "channel": {
          "type": "whatsapp",
          "name": "Main number"
        },
        "window_open": true,
        "messages": [
          {
            "id": "msg-uuid",
            "direction": "in",
            "kind": "text",
            "text": "Hello",
            "status": "received",
            "at": "2026-10-09T09:00:00Z"
          }
        ]
      }
    ]
  }
}

GET /api/v1/templates

WhatsApp templates and their status.

• status — APPROVED | PENDING | REJECTED | DRAFT | PAUSED

{
  "data": [
    {
      "name": "invoice_ready",
      "category": "UTILITY",
      "language": "ar",
      "status": "APPROVED",
      "body": "Hi {{1}}, your invoice {{2}} is ready.",
      "variables": 2,
      "header": {
        "type": "DOCUMENT"
      },
      "buttons": [
        {
          "type": "URL",
          "text": "Pay",
          "url": "https://pay.example.com/{{1}}",
          "dynamic": true
        }
      ]
    }
  ]
}

GET /api/v1/templates/{name}

One template, with the rejection reason when WhatsApp rejected it.

{
  "data": {
    "name": "invoice_ready",
    "status": "PENDING",
    "rejected_reason": null
  }
}

POST /api/v1/templates

Created and sent to WhatsApp for approval (submit: false keeps it a draft). Variables are {{1}}, {{2}}… with one example each. A media header is fetched from header.link (JPG/PNG 5 MB, MP4 16 MB, PDF 20 MB).

{
  "name": "invoice_ready",
  "category": "UTILITY",
  "language": "ar",
  "body": "Hi {{1}}, your invoice {{2}} is ready.",
  "examples": [
    "Noura",
    "INV-1001"
  ],
  "footer": "Thank you",
  "header": {
    "type": "DOCUMENT",
    "link": "https://example.com/sample.pdf",
    "filename": "invoice.pdf"
  },
  "buttons": [
    {
      "type": "URL",
      "text": "Pay",
      "url": "https://pay.example.com/{{1}}"
    }
  ]
}

{
  "data": {
    "name": "invoice_ready",
    "status": "PENDING"
  }
}

• 409 conflict — same name and language
• 422 invalid_template — the builder's checks

GET /api/v1/services

Active services with price, duration and doctors (for booking widgets).

{
  "data": [
    {
      "id": "svc-uuid",
      "code": "CLEAN",
      "name": "Cleaning",
      "price_sar": 250,
      "duration_min": 30,
      "doctors": [
        {
          "id": "doc-uuid",
          "name": "Dr. Sara",
          "accepts_new": true
        }
      ]
    }
  ]
}

GET /api/v1/slots

Free times per doctor (Riyadh dates).

• service_id — required
• from — YYYY-MM-DD
• days — 1–14 (7)

{
  "data": [
    {
      "doctor_id": "doc-uuid",
      "doctor": "Dr. Sara",
      "accepts_new": true,
      "slots": [
        {
          "start_at": "2026-10-12T07:00:00Z",
          "date": "2026-10-12",
          "label": "10:00 ص"
        }
      ]
    }
  ]
}

GET /api/v1/appointments

Appointments between two dates (62 days max).

• from — ISO date
• to — ISO date

{
  "data": [
    {
      "id": "appt-uuid",
      "lead_id": "lead-uuid",
      "client": "Noura",
      "phone": "+966551234567",
      "status": "confirmed"
    }
  ]
}

POST /api/v1/otp

A code on WhatsApp through the business's approved verification template (the default «verify_code», or one of its own authentication templates built in Settings → Templates, by name). Grouthna makes the code unless you send one.

{
  "phone": "0551234567",
  "ttl_minutes": 5
}

{
  "phone": "0551234567",
  "template": "login_code",
  "code": "482913"
}

{
  "sent": true,
  "otp_id": "otp-uuid",
  "expires_at": "2026-10-09T09:05:00Z"
}

POST /api/v1/campaigns

An approved template to a list of numbers (up to 5000), from your official number or a QR number (channel_id, else the campaign's default). Unknown numbers become leads. Each row may carry its own values for the template's variables (params per row) — else the campaign's params go to everyone ({name} = the client's first name). Optional fallbacks: an SMS text id when WhatsApp fails for good, then an email. Runs at once, or at schedule_at. 202 with the campaign id.

{
  "name": "October offer",
  "template": "monthly_offer",
  "channel_id": "channel-uuid",
  "params": [
    "{name}"
  ],
  "phones": [
    {
      "phone": "0551234567",
      "name": "Noura"
    },
    {
      "phone": "0559876543",
      "params": [
        "Sara"
      ]
    }
  ],
  "schedule_at": "2026-10-20T07:00:00Z",
  "email_fallback": {
    "subject": "October offer",
    "text": "Hi {{name}}, …"
  }
}

{
  "id": "campaign-uuid",
  "status": "sending",
  "recipients": 2,
  "skipped": 0
}

• 404 not_found — no approved template with this name / no such channel
• 422 unprocessable — params count, empty list, plan limit

GET /api/v1/campaigns/{id}

Where it stands: counts per state and the delivery numbers.

{
  "id": "campaign-uuid",
  "name": "October offer",
  "status": "done",
  "started_at": "2026-10-20T07:00:00Z",
  "finished_at": "2026-10-20T07:03:00Z",
  "recipients": 2,
  "sent": 2,
  "delivered": 2,
  "read": 1,
  "replied": 0,
  "failed": 0,
  "pending": 0,
  "sms_fallback": 0,
  "email_fallback": 0
}

POST /api/v1/campaigns/{id}/cancel

What wasn't sent yet is skipped; what went stays.

{
  "cancelled": true
}

POST /api/v1/otp/verify

Valid once, until it expires; 5 tries per code. A wrong code: { valid: false, reason, attempts_left }.

{
  "phone": "0551234567",
  "code": "4821"
}

{
  "valid": true
}

POST /api/v1/calls

Any phone system reports a finished call. It lands on the client's card; a missed incoming call alerts the owner. Idempotent per (source, external_id).

{
  "phone": "0551234567",
  "direction": "in",
  "status": "answered",
  "duration_sec": 134,
  "extension": "101",
  "source": "grandstream",
  "external_id": "1696512345.12"
}

{
  "id": "call-uuid",
  "lead_id": "lead-uuid",
  "duplicate": false
}