SmileSense Integration API

Base URL

https://smilesense.gr/api/v1/integration

Authentication

All requests require an API key:

Authorization: Bearer sk_live_xxxxxxxxx

POSTPOST /integration/feedback

Submit feedback events

Request

{
  "store_code": "IR-ATH-01",
  "idempotency_key": "unique-request-id",
  "events": [
    {
      "sentiment": "happy",
      "timestamp": "2024-01-15T10:30:00Z",
      "source": "api"
    }
  ]
}

Prerequisites

• You must have an active store. The store_code must match an existing store in your team.
• Find your store code on the Trends page of the dashboard (shown next to the store name).
• Your API key must have the FEEDBACK_WRITE permission.

Rules

• Max 100 events per request
• idempotency_key is required. Idempotency keys are scoped per team.
• Timestamp must be within ±24 hours

Response

{
  "success": true,
  "status": "processed",
  "data": {
    "processed": 1,
    "skipped": 0
  },
  "idempotency_key": "unique-request-id"
}

GETGET /integration/stores/{storeId}/summary

Retrieve store analytics

Request

GET /integration/stores/123/summary?from=2024-01-01&to=2024-01-31

Query Parameters

• from, to: YYYY-MM-DD format
• timezone: optional (defaults to store timezone)
• Max range: 365 days

Response (example)

{
  "success": true,
  "data": {
    "store": {
      "id": 123,
      "code": "IR-ATH-01",
      "name": "Athens Store",
      "timezone": "Europe/Athens"
    },
    "period": {
      "from": "2024-01-01",
      "to": "2024-01-31",
      "timezone": "Europe/Athens"
    },
    "summary": {
      "total_feedback": 1250,
      "net_sentiment_score": 56,
      "happiness_ratio": 68,
      "dissatisfaction_index": 22,
      "sentiment_breakdown": {
        "happy": 850,
        "ok": 125,
        "not_happy": 75,
        "sad": 200
      },
      "sentiment_percentages": {
        "happy": 68,
        "ok": 10,
        "not_happy": 6,
        "sad": 16
      }
    },
    "daily_data": [...]
  }
}

Metrics

• net_sentiment_score = (very good + good − bad − very bad) / total × 100, range −100…+100
• happiness_ratio = very good / total × 100 (0–100)
• dissatisfaction_index = (bad + very bad) / total × 100 (0–100)

Since October 2026: happiness_ratio and dissatisfaction_index are percentages (0–100), not fractions; net_sentiment_score counts 'good' as positive; average_rating was removed. Values are rounded to 1 decimal and are null when there is no data.

Error Handling

All errors follow this format:

{
  "error": "Invalid date range",
  "code": "VALIDATION_ERROR",
  "details": {
    "message": "End date must be after start date"
  }
}

Common status codes:

Rate Limits

Simple & honest limits:

Limits may vary by plan.

What's Coming Next

• Webhooks for real-time alerts
• Higher limits & enterprise plans
• Advanced analytics endpoints