How do I connect Cliniko or Nookal?

Cliniko is available; Nookal is currently disabled. Australian practices can connect Cliniko today. Nookal is switched off at the platform level in both deployments ahead of its activation approvals, so it will not appear in Settings → Integrations yet; its instructions below cover the day it returns. The United Kingdom deployment’s sign-up is not open yet, so no UK practice has connected either one.

Whichever you connect, it writes into your practice-management account — and that account has to sit in a region approved for your deployment, checked in code, so what you send stays inside the same residency envelope as the rest of your record.

You connect your practice software once, then choose the exact appointment and patient each time you record. Akoua reads your diary only when you ask it to, never mirrors your patient list in the background, and writes nothing into your practice software until you confirm a note or a letter.

Each integration is switched on per deployment. If Settings → Integrations doesn’t list yours, it isn’t enabled for your practice yet — everything below waits until it is.

The two are set up differently. Cliniko uses your own personal API key, so each clinician connects themselves. Nookal uses one credential for the whole organisation, so a practice admin connects it once and then maps each clinician. Read the half that applies to you.

Before you start

Your Akoua account is signed in, and you can reach Settings → Integrations.
Your practice-software account sits in a region approved for your Akoua deployment — Australia for the Australian service, the UK or EU for the United Kingdom one. Akoua checks this in code and refuses credentials from anywhere else.
For Nookal, you are the organisation owner or an integration administrator, and you can complete a second sign-in check — your authenticator code, your Akoua password, or a passkey.

Cliniko

1. Create a key in Cliniko

In Cliniko, open My info, turn on API keys if they aren’t already available, choose Manage API keys, and create one named Akoua.

A Cliniko key is password-equivalent. It can reach everything your Cliniko user can see. Create your own, never paste a colleague’s, and archive it in Cliniko if you ever stop using Akoua.

2. Paste it into Akoua

Go to Settings → Integrations → Cliniko and paste the key into Cliniko API key.

Akoua encrypts the key on its own server and never shows it again — not to you, not to anyone else in your practice. The page then displays the Cliniko practitioner the key belongs to. If that name is not you, disconnect: the key is the wrong one.

To rotate a key later, use Replace API key on the same page. To remove Akoua’s copy, use Disconnect; that removes Akoua’s copy only, so archive the key in Cliniko too if you want it dead at source.

3. Choose a draft note template

Choose Load templates, then pick the Cliniko treatment-note template Akoua should write into.

The template must have exactly one section containing exactly one paragraph question. Anything else is listed as incompatible with the reason why, so build a purpose-made template in Cliniko rather than reusing a clinical one. Akoua re-checks that structure before every single delivery — if you edit the template in Cliniko afterwards, Akoua stops rather than writing into a shape it no longer recognises.

4. Link a patient, then start the consult

Set a date range of up to 31 days and choose Sync appointments. Akoua fetches your own practitioner diary on demand and does not keep the list after you leave the page.

Pick an appointment to preview the Cliniko patient. Akoua suggests local matches on exact name and date of birth, but nothing is linked automatically — you either confirm an existing Akoua patient or add a new one from the minimum demographics (name, date of birth, sex). No clinical history is copied in either direction.

With the patient linked, start the consult from that appointment. Akoua freezes the destination server-side before recording begins.

Nookal

1. Create an API v3 OAuth client in Nookal

In Nookal, create a dedicated API v3 OAuth client for Akoua, granting only the locations, queries and mutations your practice has agreed to. Use a separate client for Akoua — never reuse one built for another product.

Grant the least you can. Akoua asks Nookal only for locations, staff, clients, appointments and clinical notes, and — for note filing — the one exact treatment-note function. A wider grant is a wider blast radius if the credential is ever misused.

2. Connect it as the practice

Go to Settings → Integrations → Nookal. Only an organisation owner or integration administrator sees the connect form.

Fill in:

Client label — what your practice calls this connection. For your reference only.
Client ID — for your reference only. Akoua does not authenticate with it.
Basic Key — the password-equivalent secret. Akoua encrypts it server-side and never returns it.

You’ll be asked to prove it’s you a second time before the credential is stored. Akoua also refuses a credential that is already connected to a different Akoua organisation.

3. Map each clinician

A credential on its own never lets every Akoua user act as every Nookal practitioner. Under Clinician authority, map each participating clinician to one Nookal practitioner and one location.

Unmapped clinicians see “your Nookal practitioner and location have not been mapped yet” and can go no further. If a practitioner or location later disappears from Nookal, Akoua drops the mapping rather than quietly acting on a stale one, and an admin re-maps it.

4. Set the draft-note template

Under Draft-note template, enter the reviewed Nookal Template name, Template ID and Text field ID.

Akoua always writes the note as a Draft and reads the created record back to confirm it landed on the exact patient, case, appointment and practitioner it was aimed at.

5. Link a patient, then start the consult

Each clinician opens their own Nookal diary for their mapped practitioner and location, picks an appointment, previews the Nookal client, and explicitly links or imports the Akoua patient — the same explicit step as Cliniko, and again with no clinical history copied.

What Akoua sends back, and when

Akoua writes nothing on its own. Reading your diary is something you ask for; writing into a patient’s record is something you confirm.

A note reaches your practice software only after you confirm it and then acknowledge the exact patient a second time on the delivery card.
It is written as a draft in your practice software. It is a document to check and sign there, not a finished record.
A letter is filed as a copy on the patient’s record. Filing it is not sending it: the recipient still receives the letter the way they always have.
Later edits in Akoua are never described as the version that was delivered. If you change the note after sending, Akoua says so rather than implying the two match.

When something goes wrong

Akoua would rather stop than guess.

“Not available” — the integration isn’t switched on for your deployment.
A template is listed as incompatible — the reason is shown next to it. Fix the template in your practice software, then load the list again.
The target changed — the mapping, template or patient link moved after your consult started. Start a new linked consult rather than sending into a destination that has shifted.
A delivery is uncertain — a lost connection can leave Akoua unable to prove whether the write landed. It will not silently try again, because a retry could create a second clinical record. Check the record in your practice software, then contact us if you need the state cleared.

A stopped delivery is not a lost note. The confirmed note is still in Akoua, and it still exports as clean text and PDF/A — see getting a note into your practice software.

Turning it off

Use Disconnect on the integration’s own page. For Cliniko that removes Akoua’s copy of your personal key; for Nookal it removes the organisation credential and the mappings that hung off it. Then archive or revoke the credential in your practice software as well, so it is dead at source and not merely unused.

If any delivery is still in an uncertain state, Akoua asks you to resolve it first — disconnecting would throw away the only record of what may have been written.