Before you start #
- The organization needs the API add-on in Kaddio.
- You need a basic understanding of how Kaddio works. See Concepts and entities and the help center.
How the API works #
The API lets you do what a regular Kaddio user can do, and every request runs as a specific user. For example, you do not pass the practitioner's ID to createContact. You call createContact as that practitioner, just as they would in Kaddio.
The API gives access to health data, so store as little of it as you can.
Endpoint #
Every organization has its own address, YOUR_ORG.kaddio.com. Send every request to its /graphql endpoint:
POST https://YOUR_ORG.kaddio.com/graphql
The body is JSON with the GraphQL document in query and, optionally, its variables:
{
"query": "query Contact($id: ID!) { findContact(id: $id) { _id date } }",
"variables": { "id": "CONTACT_ID" }
}
Results come back under data, and any errors under errors, as in any GraphQL API.
The full schema is available as SDL without authentication:
GET https://YOUR_ORG.kaddio.com/graphql/schema
Authentication #
Send a token in the Authorization header, as it is, without Bearer:
{
"Content-Type": "application/json",
"Authorization": "YOUR_API_TOKEN"
}
Tokens are created under Settings → API by a user with API admin access, and every request runs as the user who created the token. Give each token a name and, if you like, limit it to the operations it needs: the root Query and Mutation fields, such as findUsers or createContact. The token is shown once, and you can see when it was last used and revoke it at any time. Use one token per integration and keep tokens out of code and logs.
A full request:
curl https://YOUR_ORG.kaddio.com/graphql \
-H 'Content-Type: application/json' \
-H 'Authorization: YOUR_API_TOKEN' \
-d '{"query":"{ __typename }"}'
Acting as another user #
A token created by an organization admin can run a request as another user in the same organization by adding their ID:
{
"Authorization": "YOUR_API_TOKEN",
"ImpersonationId": "USER_ID"
}
Identifiers #
Fields ending in Id, such as clientId, contactTypeId and invoiceId, take Kaddio's internal _id: the string returned by find queries. They are never external identifiers such as personal identity numbers, BAS account numbers or reference codes.
A bookkeeping account's _id looks like ko9gE9dDcvTvumXq6, not 1920. Always use IDs you have read from Kaddio.
Rate limits #
The API is rate limited per organization, both in how many requests can run at the same time and in how much execution time they use. For large batch jobs, pause between requests. Ask only for the fields you use, and use webhooks instead of polling for changes. Contact support if your use case needs higher limits.
What you can do #
The schema lists every Query and Mutation field with its arguments and return type. Browse it in the playground or fetch it as SDL. The API covers:
- Users and clients: find, create and update profiles
- Journal: create contacts, add notes, diagnoses and measures
- Booking: bookable times, booking suggestions, reservations, bookings and booking types
- Invoicing: invoices, bookkeeping accounts and payments
- Communication: messages and chat groups
- Forms: forms and submitted answers
- Cases: case templates and cases
- Letters: referrals, certificates and other generated documents
- Transcriptions: speech-to-text transcripts
- Reference data: ICD codes, municipalities, places, contact types and note types
- Organization: settings and single sign-on links
- Webhooks: see Webhooks
Playground #
Open https://YOUR_ORG.kaddio.com/graphql in your browser to explore the schema and try queries.
- Open the HTTP Headers panel and add
{ "Authorization": "YOUR_API_TOKEN" }. - Use the Docs panel to browse queries, mutations, arguments and return types.
- Run
query { __typename }to check the connection.
Common errors:
- Not authorized: the token is missing or invalid, or the organization does not have the API add-on.
- HTTP 400: the request body or the GraphQL syntax is malformed.
Examples #
Mutations return an ID, for example { "data": { "clientArrived": "Hd6jK9mN2pQ5rS8tU" } }.
List practitioners #
query {
findUsers(filter: { isHost: { EQ: true } }) {
_id
firstname
}
}
Response:
{
"data": {
"findUsers": [
{ "_id": "Xb7kQ2mN9pR4sT6vW", "firstname": "Anna" },
{ "_id": "Lc3dF8gH1jK5mN0pQ", "firstname": "Erik" }
]
}
}
Find a journal contact with related data #
query {
findContact(id: "CONTACT_ID") {
_id
date
client {
_id
firstname
lastname
}
contactType {
_id
name
}
}
}
Response:
{
"data": {
"findContact": {
"_id": "F8vC8R3egRDv7XDzX",
"date": "2026-07-08T09:00:00.000Z",
"client": { "_id": "NTFeo9LR2vkdf8WHL", "firstname": "Erik", "lastname": "Svensson" },
"contactType": { "_id": "Pq4rS7tU0vW3xY6zA", "name": "Follow-up" }
}
}
}
Book an appointment #
Find a free time, reserve it, then book the reservation with the client's details.
query {
findBookingSuggestions(
from: "2026-07-01T00:00:00.000Z"
to: "2026-07-07T23:59:59.000Z"
limit: 5
) {
_id
start
end
host {
_id
firstname
lastname
}
bookingType {
_id
name
}
}
}
Response, with one suggestion shown:
{
"data": {
"findBookingSuggestions": [
{
"_id": "Rk8sT1uV4wX7yZ0aB",
"start": "2026-07-02T08:00:00.000Z",
"end": "2026-07-02T08:45:00.000Z",
"host": { "_id": "Xb7kQ2mN9pR4sT6vW", "firstname": "Anna", "lastname": "Lind" },
"bookingType": { "_id": "Bt2cD5eF8gH1jK4mN", "name": "First visit" }
}
]
}
}
Pass the suggestion's _id to reserveBookingSuggestion, which returns a reservation ID for bookReservation.
mutation {
reserveBookingSuggestion(bookingSuggestionId: "SUGGESTION_ID")
}
mutation {
bookReservation(
reservationId: "RESERVATION_ID"
firstname: "Erik"
lastname: "Svensson"
email: "erik@example.com"
phone: "+46701234567"
)
}
Mark a client as arrived #
mutation {
clientArrived(bookingId: "BOOKING_ID")
}
Create a journal contact and add a note #
createContact creates the contact as the user making the request.
mutation {
createContact(clientId: "CLIENT_ID", contactTypeId: "CONTACT_TYPE_ID")
}
mutation {
createNote(
noteTypeId: "NOTE_TYPE_ID"
contactId: "CONTACT_ID"
content: "The client reports pain in the right shoulder"
)
}
Send an invoice in the chat #
mutation {
createInvoiceAndSendInChat(
clientId: "CLIENT_ID"
dueDays: 30
items: [
{ label: "Consultation", price: 300, count: 1 }
{ label: "ECG", price: 150, count: 1 }
]
)
}
Open bookable time #
mutation {
createBookableTime(
start: "2026-07-08T08:00:00.000Z"
end: "2026-07-08T17:00:00.000Z"
hostId: "HOST_ID"
bookableBookingTypeIds: ["BOOKING_TYPE_ID"]
)
}
Single sign-on links #
Let users move from your system into Kaddio without signing in again. A token created by an organization admin can create a short-lived, one-time login token for a user:
mutation {
createSSOToken(userId: "USER_ID")
}
Send the user to https://YOUR_ORG.kaddio.com/sso-switch?ssoLoginToken=TOKEN&next=/calendar, where next is the page they land on. The organization must have single sign-on turned on.