> ## Documentation Index
> Fetch the complete documentation index at: https://docs.routiq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Nookal Integration

> Connect your Nookal account to Routiq in under 5 minutes via Nookal's v2 REST API.

<Info>
  **Why this matters.** Nookal is a leading practice management system
  for AU/NZ allied health (physio, chiro, podiatry, osteo). Routiq's
  integration uses Nookal's official v2 REST API, with the same
  capability surface as our Cliniko integration — read patients, book
  appointments, look up history, all in real time.
</Info>

## What Robyn can do with Nookal

* **Read patients** — recognise returning callers by phone, look up history, capture new-patient records
* **Read availability** — pulled from Nookal's appointment-types and practitioner schedules
* **Book, reschedule, cancel** — Robyn writes appointments directly into Nookal
* **Read practitioners and locations** — for routing decisions and per-practitioner escalations
* **Read invoices and treatment notes** — for invoice chasing and patient-context-aware conversations
* **Pagination-aware sync** — handles large patient databases efficiently

## Before you start

You'll need:

* **Administrator access** to your Nookal account
* **API access enabled** (available on all paid Nookal plans)
* The locations you want Robyn to access (Nookal API keys are scoped per location)

## Setup

<Steps>
  <Step title="Generate a Nookal API key">
    1. Log into Nookal as an administrator
    2. Go to **Practice** → **Setup** → **API Keys** (older Nookal accounts: **Setup** → **Connections** → **API Keys**)
    3. Click **Generate API Key**
    4. **Select the locations** this key should have access to — at minimum, every location Robyn needs to book into
    5. Toggle **Status** to enabled
    6. In the **Note** field, enter `Routiq Integration` so you know what the key is for later
    7. Click **Save Changes**
    8. **Copy the API key** to your clipboard

    <Warning>
      The API key gives full access to the locations you scoped it to. Treat it like a password. Use a separate key for each integration so you can revoke individually if needed.
    </Warning>
  </Step>

  <Step title="Connect in Routiq">
    1. In Routiq: **Setup** → **Connect Nookal** (or **Settings** → **Integrations** → **Nookal**)
    2. Paste your Nookal API key
    3. Click **Connect and Sync**

    Routiq verifies the key against Nookal's `/verify` endpoint, fetches your scoped locations and practitioners, and starts the initial sync.
  </Step>

  <Step title="Wait for the initial sync">
    Sync time depends on database size:

    | Practice size        | Estimated time |
    | -------------------- | -------------- |
    | \< 500 patients      | 1–2 minutes    |
    | 500–2,000 patients   | 5–10 minutes   |
    | 2,000–5,000 patients | 10–20 minutes  |
    | > 5,000 patients     | 20–30 minutes  |

    Nookal's API paginates at 100 records per page (max 200), so sync is rate-limit-aware. You can navigate away — sync continues in the background.
  </Step>

  <Step title="Verify the connection">
    Once sync completes:

    1. Go to **Patients** in Routiq — your Nookal patient list should appear
    2. Open a patient — appointment history should match Nookal
    3. Try a test booking from the **Test Robyn** screen

    <Check>Nookal is connected. Robyn can now book, reschedule, and identify patients from Nookal data.</Check>
  </Step>
</Steps>

## What gets synced

<CardGroup cols={2}>
  <Card title="Patient data">
    Patient ID, name, email, phone, DOB, gender, address, status, deceased flag, contact details
  </Card>

  <Card title="Appointment data">
    Appointment ID, date/time, practitioner, service type, location, status (`Cancelled` / `DNA` / `Completed` / `Uninvoiced`), notes
  </Card>

  <Card title="Practice data">
    Locations (scoped to your API key), practitioners, services, classes, waiting list
  </Card>

  <Card title="Financial data">
    Invoices, payments — for invoice-chasing and patient-context awareness
  </Card>
</CardGroup>

## How auth works

Nookal uses a single API key per clinic (no separate vendor key, no OAuth). The key is sent inline with each API request to `https://api.nookal.com/production/v2/{method}`.

**Multi-tenant model.** Each clinic generates their own key in their Nookal admin and pastes it into Routiq. There's no Routiq-wide "partner" credential — same model as Cliniko and most other PMSes Routiq integrates with.

**v3 GraphQL note.** Nookal has a private v3 GraphQL endpoint that powers their own web/mobile app. Routiq uses the public, supported v2 REST API rather than the undocumented v3 to avoid breaking when Nookal makes internal changes. We'll evaluate v3 if and when Nookal publishes it as a partner surface.

## Sync schedule

* **Initial sync** on connect — full pull of patients, appointments (last 24 months), practitioners, locations, services
* **Incremental sync** every 15 minutes — uses Nookal's `last_modified` filter to fetch only changed records
* **Daily reconciliation sync** at 02:00 in your practice timezone — full re-sync to catch anything incremental missed

Nookal's REST API does not currently support webhooks, so changes made in Nookal reach Routiq with up to 15 minutes' delay (vs. seconds for Cliniko's webhook-based integration).

## Troubleshooting

<AccordionGroup>
  <Accordion title="'Invalid API key' or 'API key disabled' error">
    Check in Nookal under **Practice → Setup → API Keys** that your key is toggled to **Status: Enabled**. If recently re-enabled, wait \~30 seconds and try again.
  </Accordion>

  <Accordion title="Some locations are missing from Routiq">
    Nookal API keys are scoped per location. Edit your key in Nookal's API Keys page and tick the locations Robyn should access, then save.
  </Accordion>

  <Accordion title="Patients aren't appearing">
    Initial sync may still be running — check the dashboard progress indicator. If complete, verify the patient is **Alive** (not deceased) in Nookal — Routiq filters deceased patients by default in the active patient list.
  </Accordion>

  <Accordion title="Bookings aren't appearing in Nookal">
    Robyn writes to the same calendar as your team. If a booking doesn't appear, check that Robyn isn't blocked from the relevant practitioner/service combo — both must exist on the API key's scoped location and be enabled for online booking.
  </Accordion>

  <Accordion title="Changes in Nookal take a while to reach Robyn">
    Nookal's API doesn't support webhooks, so Routiq polls every 15 minutes for changes. If you need a faster sync after a bulk update, use **Settings → Integrations → Nookal → Sync Now** to force an immediate refresh.
  </Accordion>
</AccordionGroup>

## Managing the integration

### Rotating the API key

1. Generate a new key in Nookal (same flow as setup step 1)
2. In Routiq: **Settings** → **Integrations** → **Nookal** → **Update API Key**
3. Paste, save
4. Disable the old key in Nookal once the new one is verified

### Disconnecting

<Warning>
  Disconnecting Nookal stops Robyn from booking, halts all outbound sequences, and pauses every active recall campaign for this integration.
</Warning>

**Settings** → **Integrations** → **Nookal** → **Disconnect**. Patient data is retained for 30 days post-disconnect for compliance and recovery, then deleted.

### Manual resync

If you've imported patients in bulk into Nookal and don't want to wait for the next 15-minute sync:

**Settings** → **Integrations** → **Nookal** → **Sync Now**.

## Next

<CardGroup cols={2}>
  <Card title="Set up the calls channel" icon="phone" href="/channels/calls">
    Forward your clinic line to Robyn and start handling calls.
  </Card>

  <Card title="Turn on lapsed-patient reactivation" icon="rotate-right" href="/outbound/lapsed-patient-reactivation">
    Bring dormant Nookal patients back with multi-touch sequences.
  </Card>
</CardGroup>