# Authenticate
Source: https://docs.ziik.io/api-reference/auth/authenticate
/openapi.yaml post /authenticate
Authenticate with email and password. Returns a JWT.
# Renew token
Source: https://docs.ziik.io/api-reference/auth/renew-token
/openapi.yaml post /renew
Exchange the current JWT for a fresh token. Requires a valid (possibly expiring) JWT in the Authorization header.
# Archive a conversation
Source: https://docs.ziik.io/api-reference/conversations/archive-a-conversation
/openapi.yaml post /conversations/{conversation}/archive
Archives the conversation for the authenticated user and adds it to their blacklist so it no longer appears in the default list. The user must be a participant.
# Create a conversation
Source: https://docs.ziik.io/api-reference/conversations/create-a-conversation
/openapi.yaml post /conversations/create
Creates a new conversation or returns an existing one with the given recipients. For a single recipient, finds or creates a direct conversation. For multiple recipients, creates a group conversation.
# Create a new message in a conversation
Source: https://docs.ziik.io/api-reference/conversations/create-a-new-message-in-a-conversation
/openapi.yaml post /conversations/{conversation}/messages
Creates a new message in the given conversation for the authenticated user. Supports attaching files and replying to a parent message.
# Create conversation with first message
Source: https://docs.ziik.io/api-reference/conversations/create-conversation-with-first-message
/openapi.yaml post /conversations
Creates a new conversation (or uses existing one) with the given recipients and immediately adds the first message. Returns the created message resource.
# Delete a conversation
Source: https://docs.ziik.io/api-reference/conversations/delete-a-conversation
/openapi.yaml delete /conversations/{conversation}
Deletes the conversation. Only conversation admins can delete; other participants may leave instead. Executes full conversation deletion (messages, participants, etc.) for the current website.
# Delete a message in a conversation
Source: https://docs.ziik.io/api-reference/conversations/delete-a-message-in-a-conversation
/openapi.yaml delete /conversations/{conversation}/messages/{message}
Soft-deletes a message in the given conversation (marks as deleted, removes reactions, files, and voice data) and broadcasts the deletion to other participants.
# Finalize message update
Source: https://docs.ziik.io/api-reference/conversations/finalize-message-update
/openapi.yaml post /conversations/{conversation}/messages/{message}/finalize-update
Should be called by the client after all edit operations are complete. This broadcasts updates to conversation participants and returns the final message resource.
# Get a conversation
Source: https://docs.ziik.io/api-reference/conversations/get-a-conversation
/openapi.yaml get /conversations/{conversation}
Returns a single conversation by ID with participants, latest message, and related data. Requires view permission on the conversation.
# Get a single message in a conversation
Source: https://docs.ziik.io/api-reference/conversations/get-a-single-message-in-a-conversation
/openapi.yaml get /conversations/{conversation}/messages/{message}
Returns a single message in the given conversation with all related data (author, files, reactions, parent message, etc.).
# List conversations
Source: https://docs.ziik.io/api-reference/conversations/list-conversations
/openapi.yaml get /conversations
Returns a paginated list of conversations for the authenticated user. Can be filtered by status (normal, unread, archived), keyword (title or participant name), or exact participant set. Supports pagination via limit and page.
# List messages in a conversation
Source: https://docs.ziik.io/api-reference/conversations/list-messages-in-a-conversation
/openapi.yaml get /conversations/{conversation}/messages
Returns a cursor-paginated list of messages for the given conversation. Supports loading around a specific starter message, text search, and bi-directional cursor pagination.
# Unarchive a conversation
Source: https://docs.ziik.io/api-reference/conversations/unarchive-a-conversation
/openapi.yaml post /conversations/{conversation}/unarchive
Removes the archive flag for the authenticated user and removes the conversation from their blacklist so it appears again in the default list. The user must be a participant.
# Update a conversation
Source: https://docs.ziik.io/api-reference/conversations/update-a-conversation
/openapi.yaml patch /conversations/{conversation}
Updates conversation properties. Currently supports setting the conversation title; a system message is added to the conversation when the title is changed. Requires manage permission on the conversation.
# Update a message in a conversation
Source: https://docs.ziik.io/api-reference/conversations/update-a-message-in-a-conversation
/openapi.yaml patch /conversations/{conversation}/messages/{message}
Updates the text of an existing message in the given conversation. Important: see also Finalize message update
# Get counters
Source: https://docs.ziik.io/api-reference/counters/get-counters
/openapi.yaml get /counters
Get notification and conversation counters for the authenticated user
# Create a group
Source: https://docs.ziik.io/api-reference/groups/create-a-group
/openapi.yaml post /groups
Creates a new group and adds the authenticated user as an admin member.
# Delete a group
Source: https://docs.ziik.io/api-reference/groups/delete-a-group
/openapi.yaml delete /groups/{group}
Soft deletes a group and schedules background cleanup of associated content from feeds.
# Get a group
Source: https://docs.ziik.io/api-reference/groups/get-a-group
/openapi.yaml get /groups/{group}
Returns details about a single group. Private groups are only accessible to members.
# List groups
Source: https://docs.ziik.io/api-reference/groups/list-groups
/openapi.yaml get /groups
Returns a paginated list of groups visible to the authenticated user. The list can be filtered by membership mode, group type and sorting method.
# Search groups
Source: https://docs.ziik.io/api-reference/groups/search-groups
/openapi.yaml get /groups/search/{search}
Searches groups by name and returns a paginated list of matching groups visible to the authenticated user.
# Update a group
Source: https://docs.ziik.io/api-reference/groups/update-a-group
/openapi.yaml patch /groups/{group}
Updates the basic details of an existing group.
# List languages
Source: https://docs.ziik.io/api-reference/languages/list-languages
/openapi.yaml get /settings/languages
Get list of enabled languages keyed by abbreviation
# Create a post
Source: https://docs.ziik.io/api-reference/posts/create-a-post
/openapi.yaml post /content
Creates a new post and returns the created resource.
# Delete a post
Source: https://docs.ziik.io/api-reference/posts/delete-a-post
/openapi.yaml delete /content/{content}
Deletes a post.
# Get a post
Source: https://docs.ziik.io/api-reference/posts/get-a-post
/openapi.yaml get /content/{content}
Returns a single post with all related data.
# Get multiple posts by ID
Source: https://docs.ziik.io/api-reference/posts/get-multiple-posts-by-id
/openapi.yaml get /content/collection/{contentIDs}
Returns a map of requested content IDs to post objects (or null if not accessible).
# List global post IDs
Source: https://docs.ziik.io/api-reference/posts/list-global-post-ids
/openapi.yaml get /content/global/{type}/{sorting}
Returns an ordered list of post IDs for the global feed, filtered and sorted by type and sorting.
# List post IDs by group
Source: https://docs.ziik.io/api-reference/posts/list-post-ids-by-group
/openapi.yaml get /content/group/{group}/{type}/{sorting}
Returns an ordered list of post IDs for a specific group feed, filtered by type and sorting.
# List post IDs by user
Source: https://docs.ziik.io/api-reference/posts/list-post-ids-by-user
/openapi.yaml get /content/user/{user}/{type}
Returns an ordered list of post IDs shared with or authored by a specific user.
# Update a post
Source: https://docs.ziik.io/api-reference/posts/update-a-post
/openapi.yaml patch /content/{content}
Updates an existing post.
# List timezones
Source: https://docs.ziik.io/api-reference/timezones/list-timezones
/openapi.yaml get /settings/timezones
Get list of timezones
# Create unit
Source: https://docs.ziik.io/api-reference/units/create-unit
/openapi.yaml post /units
Creates a new unit and returns the created resource.
# Delete unit
Source: https://docs.ziik.io/api-reference/units/delete-unit
/openapi.yaml delete /units/{unit}
Deletes a unit.
# Get unit by ID
Source: https://docs.ziik.io/api-reference/units/get-unit-by-id
/openapi.yaml get /units/{unit}
Returns a single unit with related data.
# Get unit by reference
Source: https://docs.ziik.io/api-reference/units/get-unit-by-reference
/openapi.yaml get /units/reference/{unit}
Returns a single unit resolved by its reference value.
# List basic units
Source: https://docs.ziik.io/api-reference/units/list-basic-units
/openapi.yaml get /units/basic
Returns a list of units with only basic information (id and name).
# List units
Source: https://docs.ziik.io/api-reference/units/list-units
/openapi.yaml get /units
Returns a paginated list of units. Can be filtered by feature, user membership, and search keyword.
# Update unit
Source: https://docs.ziik.io/api-reference/units/update-unit
/openapi.yaml patch /units/{unit}
Updates an existing unit.
# Create user type
Source: https://docs.ziik.io/api-reference/user-types/create-user-type
/openapi.yaml post /usertypes
Creates a new user type (role) with optional name and reference.
# Delete user type
Source: https://docs.ziik.io/api-reference/user-types/delete-user-type
/openapi.yaml delete /usertypes/{userType}
Deletes a user type. Fails if any users are assigned to this role.
# Get user type
Source: https://docs.ziik.io/api-reference/user-types/get-user-type
/openapi.yaml get /usertypes/{userType}
Returns a single user type by ID, including permissions and distinct user count.
# List basic user types
Source: https://docs.ziik.io/api-reference/user-types/list-basic-user-types
/openapi.yaml get /usertypes/basic
Returns a minimal list of user types (id and name) for the current website.
# List user types
Source: https://docs.ziik.io/api-reference/user-types/list-user-types
/openapi.yaml get /usertypes
Returns user types (roles) visible to the authenticated user.
# Update user type
Source: https://docs.ziik.io/api-reference/user-types/update-user-type
/openapi.yaml patch /usertypes/{userType}
Updates an existing user type. Can change name and reference.
# Add unit membership
Source: https://docs.ziik.io/api-reference/user-unit-memberships/add-unit-membership
/openapi.yaml post /users/{user}/units
Creates or updates a unit membership for the user (unit, department, user types). Returns the membership and sets Location header.
# List user unit memberships
Source: https://docs.ziik.io/api-reference/user-unit-memberships/list-user-unit-memberships
/openapi.yaml get /users/{user}/units
Returns all unit memberships (unit, department, user types) for the given user.
# Remove unit membership
Source: https://docs.ziik.io/api-reference/user-unit-memberships/remove-unit-membership
/openapi.yaml delete /users/{user}/units/{unit}
Deletes a unit membership for the user. User must have at least one remaining membership.
# Update unit membership
Source: https://docs.ziik.io/api-reference/user-unit-memberships/update-unit-membership
/openapi.yaml patch /users/{user}/units/{unit}
Updates an existing unit membership for the user (e.g. department, user types, or move to another unit).
# Deactivate user
Source: https://docs.ziik.io/api-reference/users/deactivate-user
/openapi.yaml post /users/{user}/deactivate
Deactivate a user by ID
# Delete user
Source: https://docs.ziik.io/api-reference/users/delete-user
/openapi.yaml delete /users/{user}
Delete a user by ID
# Get collection of users by IDs
Source: https://docs.ziik.io/api-reference/users/get-collection-of-users-by-ids
/openapi.yaml get /users/collection/{userIDs}
# Get user by ID
Source: https://docs.ziik.io/api-reference/users/get-user-by-id
/openapi.yaml get /users/{userId}
Get user by ID
# Get user by reference
Source: https://docs.ziik.io/api-reference/users/get-user-by-reference
/openapi.yaml get /users/reference/{reference}
# Get users
Source: https://docs.ziik.io/api-reference/users/get-users
/openapi.yaml get /users
# Post users
Source: https://docs.ziik.io/api-reference/users/post-users
/openapi.yaml post /users
# Reactivate user
Source: https://docs.ziik.io/api-reference/users/reactivate-user
/openapi.yaml post /users/{user}/reactivate
Reactivate a user by ID
# Update user
Source: https://docs.ziik.io/api-reference/users/update-user
/openapi.yaml patch /users/{user}
Update a user by ID
# User birthdays
Source: https://docs.ziik.io/api-reference/users/user-birthdays
/openapi.yaml get /users/birthdays
Get users with birthdays in range
# Introduction
Source: https://docs.ziik.io/index
Welcome to the Ziik API docs. You can use the API to access Ziik API endpoints, fetching and supplying data from your Ziik system.
## Getting Started
The Ziik API is a RESTful API that can be used to access the data in your Ziik system.
Learn how to authenticate with the API.
Things to be aware of.
Learn about the entities in Ziik.
Example use cases for the system.
Take me to the endpoints...
## Missing anything?
These API docs contain support for the most common use cases, if you are looking for more customization or advanced features - feel free to contact us!
# Authentication
Source: https://docs.ziik.io/pages/authentication
To authorize, you will need to authenticate with the service to get an access token for use with the API.
## Find your API URL
To find your API URL, simply log in to Ziik via the browser, copy the URL and append /api.
Should look something like this: [https://your-identifier.ziik.io/api](https://your-identifier.ziik.io/api)
## Get an accesstoken
To get an accesstoken, call the authenticate endpoint with your username and password:
```curl theme={null}
curl "https://example.ziik.io/api/authenticate"
-d '{"username":"example@example.com","password":"thisIsMyPassword"}'
```
The above command returns JSON structured like this:
```json theme={null}
[
{
"jwt": "aaaaaaaaaa.bbbbbbbbbbb.cccccccccccc",
"expires": 12345678
}
]
```
"expires" is the Unix timestamp of when the accesstoken is no longer valid.
## Set Authorization header
The API expects the accesstoken to be included in all following API requests:
`Authorization: Bearer aaaaaaaaaa.bbbbbbbbbbb.cccccccccccc`
## Renew an accesstoken
To renew the accesstoken, simply call the renew endpoint and use the renewed token for future calls.
```
curl "https://example.ziik.io/api/renew"
-H "Authorization: Bearer aaaaaaaaaa.bbbbbbbbbbb.cccccccccccc"
```
# Best practices
Source: https://docs.ziik.io/pages/best-practices
Common best practices for using REST APIs effectively and reliably.
## Use HTTPS
Always call the API over HTTPS. Never send credentials or sensitive data over plain HTTP.
## Handle errors and status codes
* Check the HTTP status code on every response (e.g. 2xx success, 4xx client error, 5xx server error).
* Read the response body on errors; it often contains a message or error code to help you retry or fix the request.
* Implement retries with backoff for transient failures (e.g. 429 Too Many Requests, 503 Service Unavailable).
## Respect rate limits
* Throttle your requests and avoid bursts; use exponential backoff when you hit limits.
* Cache responses where it makes sense to reduce the number of calls.
## Authenticate correctly
* Store tokens securely (e.g. environment variables or a secrets manager) and never commit them to source control.
* Send the token in the `Authorization` header as specified (e.g. `Bearer `).
* Refresh or renew tokens before they expire to avoid failed requests.
## Use pagination
* For list endpoints, use the provided pagination parameters (e.g. `page`, `limit`, or cursor) instead of fetching everything at once.
* Follow the documented page size limits to avoid timeouts and unnecessary load.
## Use appropriate HTTP methods and URLs
* Use `GET` for reading, `POST` for creating, `PUT`/`PATCH` for updating, and `DELETE` for removing resources.
* Prefer resource-oriented URLs (e.g. `/users/123`) and avoid unnecessary query parameters for identifiers.
## Logging and monitoring
* Log request/response metadata (e.g. endpoint, status code, request ID) for debugging, without logging full credentials or sensitive payloads.
* Monitor success rates, latency, and error types so you can react to issues quickly.
# Error handling
Source: https://docs.ziik.io/pages/errorhandling
?
## Error codes
The API uses standard HTTP error codes:
| Error Code | Title | Meaning |
| ---------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| 400 | Bad Request | Your request could not be understood |
| 401 | Unauthorized | Missing or invalid API token sent |
| 403 | Forbidden | You lack the privileges needed to perform the requested action |
| 404 | Not Found | The specified content could not be found |
| 405 | Method Not Allowed | You tried to access a resource with a method (GET, POST, PATCH, DELETE, etc.) that is not supported for the requested action |
| 406 | Not Acceptable | Your request could not be understood |
| 410 | Gone | The content requested has been removed from our servers |
| 422 | Unprocessable Entity | The parameters given are invalid or in an invalid combination to process the request |
| 429 | Too Many Requests | Slow down! |
| 500 | Internal Server Error | We have a problem with our server for the given request. Try again later and contact customer support if the error persists. |
| 503 | Service Unavailable | We're temporarially offline for maintenance. Please try again later. |
## Error format
The format of an error looks like this.
```json theme={null}
{
"error": {
"code": "",
"message": "",
"is_ziik_error": boolean
}
}
```
Where `error_code` can be a unique string identifiyng the cause of the error, followed by an optional message. The `is_ziik_error` boolean indicates if this was a custom error thrown by the API.
# Managing unit memberships
Source: https://docs.ziik.io/pages/managing-unit-memberships
Assign users to units and manage department and user types per membership.
Unit memberships define which users belong to which units (and department and user types within that unit).
Use these endpoints:
* **List a user's memberships** – `GET /users/{user}/units`.
* **Add a membership** – `POST /users/{user}/units` (body specifies unit, department, user types).
* **Update a membership** – `PATCH /users/{user}/units/{unit}` (e.g. change department, user types, or move to another unit).
* **Remove a membership** – `DELETE /users/{user}/units/{unit}`. The user must have at least one remaining membership.
Use the user's Ziik ID (or resolve it via `GET /users/reference/{reference}`) and the unit ID (or resolve via `GET /units/reference/{unit}`) when managing memberships from your system.
# Managing units
Source: https://docs.ziik.io/pages/managing-units
Create, read, update, and delete units (departments, locations, teams) via the API.
Units represent departments, locations, or teams in Ziik. You can manage them fully via the API:
* **List units** – `GET /units` (with optional filters: feature, user membership, search).
* **Create a unit** – `POST /units` with `name` and optional `reference` and `parent` (for hierarchy).
* **Get a unit** – by ID (`GET /units/{unit}`) or by your external key (`GET /units/reference/{unit}`).
* **Update a unit** – `PATCH /units/{unit}` (e.g. name, reference).
* **Delete a unit** – `DELETE /units/{unit}`.
Set a **reference** on units to map them to your own org structure (e.g. cost center or department code) and use `GET /units/reference/{unit}` for lookups.
# Pagination
Source: https://docs.ziik.io/pages/pagination
How list endpoints return paginated data with links and meta.
List endpoints return paginated responses. Each response includes a `links` object for navigation URLs and a `meta` object with pagination details.
## Example response
```json theme={null}
{
"data": [...],
"links": {
"first": "http://.../api/users/search?page=1",
"last": "http://.../api/users/search?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": null,
"last_page": 1,
"links": [
{
"url": null,
"label": "« Previous",
"page": null,
"active": false
},
{
"url": "http://.../api/users/search?page=1",
"label": "1",
"page": 1,
"active": true
},
{
"url": null,
"label": "Next »",
"page": null,
"active": false
}
],
"path": "http://.../api/users/search",
"per_page": 2,
"to": null,
"total": 0
}
}
```
## Links (top-level)
| Attribute | Description |
| --------- | ----------------------------------------------------------------------------------- |
| **first** | URL for the first page. Always present. |
| **last** | URL for the last page. Always present. |
| **prev** | URL for the previous page. `null` when on the first page. |
| **next** | URL for the next page. `null` when on the last page or when there is only one page. |
Use these URLs to move between pages without building query strings yourself.
## Meta
| Attribute | Description |
| ----------------- | --------------------------------------------------------------------------------------- |
| **current\_page** | 1-based index of the current page. |
| **from** | 1-based index of the first item on the current page. `null` when the page has no items. |
| **last\_page** | Total number of pages. |
| **path** | Base URL of the endpoint (without `page` or other query params). |
| **per\_page** | Number of items per page (page size). |
| **to** | 1-based index of the last item on the current page. `null` when the page has no items. |
| **total** | Total number of items across all pages. |
## Meta.links
`meta.links` is an array of page navigation entries. Each entry has:
| Attribute | Description |
| ---------- | ---------------------------------------------------------------------------------------- |
| **url** | Full URL for that page, or `null` when the link is disabled (e.g. "Previous" on page 1). |
| **label** | Display label (e.g. `"1"`, `"« Previous"`, `"Next »"`). |
| **page** | Page number, or `null` for prev/next links. |
| **active** | `true` for the current page, `false` otherwise. |
Use `meta.links` to render a page navigator (e.g. « Previous, 1, 2, 3, Next ») and `meta.total` / `meta.last_page` to show “Page X of Y” or “Showing N of M results”.
# Entity overview
Source: https://docs.ziik.io/pages/structure
The entities in the Ziik space.
## Entity overview
The API is built around these main entities (defined in the OpenAPI spec):
* **User** — People in the space. Full profile with name, unit, user types, permissions, avatar, and optional extras (department, groups, specialties).
* **Unit** — Organizational units in a tree (e.g. departments, locations). Have `id`, `name`, optional `reference`, `parent_id`, and can include departments, features, stats, and addresses.
* **Group** — Collaboration spaces. Have `name`, `type` (public/private), optional description. Users are members or admins.
* **Content** — Posts in feeds (news, debate, event). Include title, body, publish/visibility, comments, files, polls, and event data.
* **Conversation** — Direct or group chats. Have participants, optional title, latest message, and unread state. **Message** is a single message in a conversation (text, author, reactions, attachments).
* **User types** — Roles with optional permissions (abilities). Users are assigned one or more user types per unit.
* **Alerts** — Active alerts with id, message, type (info/warning/danger), and optional rich content.
* **Counters** — Simple counts such as unread notifications and unread conversations (plus a timestamp).
# Sync Ziik users with your own system
Source: https://docs.ziik.io/pages/sync-users
Two-way sync using the reference field to link Ziik users to your external system.
Use the **reference** field to link Ziik users to records in your own system (e.g. employee ID, HR system key). This enables two-way sync:
* **Your system → Ziik:** When creating or updating users via the API, set `reference` to your external identifier. You can later look up that user in Ziik with `GET /users/reference/{reference}`.
* **Ziik → your system:** When listing or fetching users from Ziik, each user's `reference` is returned. Use it to match and update the corresponding record in your system.
Keep `reference` unique and stable so you can reliably resolve users in both directions and avoid duplicates.