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/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. Grouthna makes the code unless you send one.

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

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

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
}