Smileline Developers

Getting started.

From an empty account to an app a practice can connect, in six steps.

  1. Create an app

    Sign in with your email: each sign-in sends a link, there is no password, and you don't need a Smileline practice. Name the app. Its client id (app_…) is public; the client secret (sl_cs_…) is shown once, so store it before you close the dialog. Regenerating it replaces it at once in every region.

    Sign in
  2. Set redirect URIs and scopes

    Redirect URIs must match exactly and use HTTPS; plain HTTP works on localhost only. Ask for areas of practice data as .read or .write (write includes read), plus offline_access for a refresh token. Practices see exactly that list.

    patients.read appointments.write offline_access
    Scopes
  3. Send a practice to authorise

    Send an owner or manager to the authorise URL with your client id, redirect URI, scopes, a state and a PKCE challenge (S256 is mandatory).

    https://developer.smileline.io/oauth/authorize
      ?response_type=code
      &client_id=app_c1i2e3n4t5
      &redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth%2Fcallback
      &scope=patients.read%20appointments.write%20offline_access
      &state=8f3a…
      &code_challenge=E9Melhoa…
      &code_challenge_method=S256

    They choose UK & Europe or United States, sign in, pick the practice and review the scopes. Add region=eu or region=us to skip the question.

    OAuth 2.0
  4. Exchange the code, then call the API

    Exchange the code at the token URL; the region is resolved from the code.

    curl -X POST https://developer.smileline.io/oauth/token \
      -d grant_type=authorization_code \
      -d client_id=app_c1i2e3n4t5 \
      -d client_secret=$CLIENT_SECRET \
      -d code=$CODE \
      -d code_verifier=$PKCE_VERIFIER \
      -d redirect_uri=https://app.example.com/oauth/callback

    Keep api_base_url and organization_id from the response: every request for this practice goes to that base URL.

    curl "$API_BASE_URL/patients?limit=10" \
      -H "Authorization: Bearer sl_oat_…"

    Access tokens last an hour; refresh tokens last 30 days and rotate on every use.

    API reference
  5. Receive webhooks

    Give the app one HTTPS delivery URL and choose its events. Within about five minutes of a practice connecting, Smileline sends a challenge with an X-Hook-Secret header; reply 2xx with the same header and value. Delivery starts after that echo, so backfill anything earlier from the list endpoints.

    X-SmileLine-Timestamp: 1760870400
    X-SmileLine-Delivery-Id: 7c0f…
    X-SmileLine-Signature: v1=<hex>
    
    v1 = hex(HMAC-SHA256(signing_secret, timestamp + '.' + deliveryId + '.' + rawBody))
    App webhooks
  6. Submit for approval

    Until then the app is live in both regions, capped at 25 connected practices per region and marked unreviewed on the consent screen. Submitting needs a redirect URI, a permission area, a privacy policy URL and a support email; approval lifts the cap and the notice.

    Approval