Quickstart

This guide takes you from zero to a working API call. You'll get a key, make an authenticated request, and read your first page of data.

#1. Get an API key

Keys are issued per clinic. Clinic administrators mint and revoke keys from the SmileCloud app (Settings → Integrations → API keys). Each key is shown once at creation - copy it immediately and store it in your secret manager.

A key looks like this:

sk_live_4f8a2c9e1b7d6a3f0e5c8b2a9d4f7e1c

#2. Make your first request

Every request is a standard HTTPS call with your key in the Authorization header. Start with /v1/me - it introspects the calling key and needs no scopes.

curl https://api.smile-app.co.il/v1/me \
  -H "Authorization: Bearer sk_live_..."

sc whoami

{
  "data": {
    "clinic_id": "demo",
    "scopes": ["patients:read", "appointments:read", "catalog:read"]
  }
}

The scopes array tells you exactly what this key can read. If a call later returns 403, it's because the key is missing the required scope.

#3. Read some data

List the clinic's branches from the catalog. This needs the catalog:read scope.

curl https://api.smile-app.co.il/v1/catalog/branches \
  -H "Authorization: Bearer sk_live_..."

{
  "data": [
    { "id": "1", "name": "Downtown Branch", "phone": "+972-3-555-0100", "address": {}, "color": "#4f46e5" }
  ]
}

#4. Search and paginate

List endpoints accept filters and return an opaque cursor for the next page. Here we search patients by phone number.

curl -G https://api.smile-app.co.il/v1/patients \
  -H "Authorization: Bearer sk_live_..." \
  --data-urlencode "phone=0521234567" \
  --data-urlencode "limit=25"

{
  "data": [
    { "id": "8842", "first_name": "Dana", "last_name": "Levi", "phone": "0521234567" }
  ],
  "next_cursor": null
}

When next_cursor is non-null, pass it back as ?cursor=... to fetch the next page. See Pagination for the full pattern.

#What's next