✦ API для розробників · v1.0

MeetGrade API

Чистий REST API, щоб витягувати оцінені дзвінки, результати QA та чек-листи в будь-яку систему — і отримувати вебхук одразу після оцінки дзвінка.

REST · JSON Bearer-авторизація 120 req/min Лише читання (v1.0)

Вступ

MeetGrade API — це REST API, що працює з JSON через HTTPS. Усі запити йдуть на базовий URL нижче. Кожна відповідь — JSON у UTF-8; часові мітки у форматі ISO 8601.

БАЗОВИЙ URL https://app.meetgrade.com/api/v1

Версія 1.0 лише для читання — вона дозволяє експортувати дані та реагувати на події. Ендпоінтів запису в цій версії немає.

Автентифікація

Автентифікуйте кожен запит Bearer-токеном у заголовку Authorization. Створіть ключі в застосунку: Налаштування → API-ключі.Authorization header. Create keys in the app under Налаштування → API-ключі.

Authorization: Bearer mg_live_xxxxxxxxxxxxxxxxxxxxxxxx
🔑 Показується один раз

Секрет ключа показується лише раз — при створенні. Скопіюйте одразу: ми зберігаємо тільки хеш і не зможемо показати його знову.

⛔ Тримайте ключі на сервері

Ніколи не світіть ключ у браузерному коді, мобільних застосунках чи публічних репозиторіях. Ставтеся до нього як до пароля; відкликайте й ротуйте при витоку.

Ліміти запитів

Кожен API-ключ обмежений 120 запитами на хвилину. Перевищення повертає HTTP 429 — зробіть паузу й повторіть.120 requests per minute. Exceeding it returns HTTP 429 — back off and retry after a short pause.

GET /api/v1/calls

Список ваших дзвінків, новіші першими. Для пагінації використовуйте limit та offset.limit and offset to paginate.

ПараметрТипОпис
limitintegerМакс. елементів, ≤ 200. За замовчуванням 50.
offsetintegerСкільки пропустити. За замовчуванням 0.
cURL
curl https://app.meetgrade.com/api/v1/calls?limit=50 \
  -H "Authorization: Bearer mg_live_xxx"
Python
import requests

r = requests.get(
    "https://app.meetgrade.com/api/v1/calls",
    headers={"Authorization": "Bearer mg_live_xxx"},
    params={"limit": 50, "offset": 0},
    timeout=10,
)
data = r.json()
Приклад відповіді
{
  "data": [
    {
      "bot_id": "call_8f21ab",
      "manager": "anna@acme.com",
      "total_score": 87,
      "checklist_id": "sales_phone_adult",
      "key_result_achieved": true,
      "created_at": "2026-06-22T14:05:11Z"
    }
  ],
  "total": 1284,
  "limit": 50,
  "offset": 0
}
GET /api/v1/calls/{id}

Отримати один дзвінок із повним результатом QA: оцінка, розбивка по критеріях, підсумок, сильні сторони та проблеми.

cURL
curl https://app.meetgrade.com/api/v1/calls/call_8f21ab \
  -H "Authorization: Bearer mg_live_xxx"
Python
import requests

cid = "call_8f21ab"
r = requests.get(
    f"https://app.meetgrade.com/api/v1/calls/{cid}",
    headers={"Authorization": "Bearer mg_live_xxx"},
    timeout=10,
)
call = r.json()
Приклад відповіді
{
  "bot_id": "call_8f21ab",
  "manager": "anna@acme.com",
  "created_at": "2026-06-22T14:05:11Z",
  "qa": {
    "total_score": 87,
    "checklist_id": "sales_phone_adult",
    "checklist_name": "Sales · phone",
    "key_result_achieved": true,
    "criteria": {
      "greeting":        { "score": 100, "comment": "Warm, on-brand opening." },
      "needs_discovery": { "score": 70,  "comment": "Probe needs earlier." }
    },
    "summary": "Strong rapport; closing step was vague.",
    "strengths": ["Active listening", "Clear pricing"],
    "issues":    ["No confirmed next step"]
  }
}
ℹ criteria — це об'єкт із ключами за назвами критеріїв — { key: { score, comment } } — не масив. У старих дзвінків checklist_id може бути null.{ key: { score, comment } } — not an array. On legacy calls checklist_id may be null.
GET /api/v1/checklists

Список ваших чек-листів оцінювання з їхніми критеріями та вагами.

cURL
curl https://app.meetgrade.com/api/v1/checklists \
  -H "Authorization: Bearer mg_live_xxx"
Python
import requests

r = requests.get(
    "https://app.meetgrade.com/api/v1/checklists",
    headers={"Authorization": "Bearer mg_live_xxx"},
    timeout=10,
)
checklists = r.json()["data"]
Приклад відповіді
{
  "data": [
    {
      "checklist_id": "sales_phone_adult",
      "name": "Sales · phone",
      "criteria": [
        { "key": "greeting",        "weight": 15 },
        { "key": "needs_discovery", "weight": 25 },
        { "key": "next_step",       "weight": 30 }
      ]
    }
  ]
}

Помилки

API використовує стандартні HTTP-коди. Тіло помилки — JSON із зрозумілим полем detail.detail field.

СтатусЗначення
401Відсутній, некоректний або відкликаний API-ключ.
404Запитаний дзвінок чи ресурс не існує (або не належить вам).
429Перевищено ліміт — понад 120 запитів/хв. Зробіть паузу й повторіть.
 
{ "detail": "Invalid or revoked API key." }

Вебхуки

Замість опитування дозвольте MeetGrade надсилати дані вам. Коли дзвінок оцінено, ми відправляємо подію qa_completed і POST-запит із JSON на ваш URL.qa_completed event and POST a JSON payload to your configured URL.

⚙ Налаштуйте URL ендпоінта й секрет у застосунку: Налаштування → Інтеграції.Settings → Integrations.

Подія: qa_completedqa_completed

Payload
{
  "bot_id": "call_8f21ab",
  "score": 87,
  "manager_email": "anna@acme.com",
  "phone": "+380**********",
  "checklist_id": "sales_phone_adult",
  "key_result_achieved": true,
  "call_url": "https://app.meetgrade.com/call/call_8f21ab"
}

Перевірка підпису

Кожна доставка містить заголовок X-StudyLess-Signature — HMAC-SHA256 від сирого тіла запиту з вашим секретом вебхука. Перерахуйте та звірте перш ніж довіряти payload.X-StudyLess-Signature header — an HMAC-SHA256 of the raw request body, keyed with your webhook secret. Recompute it and compare before trusting the payload.

X-StudyLess-Signature: sha256=4f1c...e9a2
Python (Flask)
import hmac, hashlib
from flask import request, abort

WEBHOOK_SECRET = b"your_webhook_secret"

def verify(req):
    sig = req.headers.get("X-StudyLess-Signature", "")
    expected = "sha256=" + hmac.new(
        WEBHOOK_SECRET, req.get_data(), hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(sig, expected)

@app.post("/webhooks/meetgrade")
def handler():
    if not verify(request):
        abort(401)
    event = request.get_json()
    # ... handle qa_completed ...
    return "", 200

Плани

🧭

Незабаром з'являться нові ендпоінти — зокрема аналітика по командах і менеджерах (агреговані оцінки, тренди, топ-помилки). Потрібен ранній доступ? Напишіть нам.analytics (aggregate scores, trends, top mistakes). Want early access? Email us at hello@meetgrade.com.