Home Integration API reference
REST API for integrations and external apps
Productivity tools
These endpoints map to the Essentials Productivity tools area (dashboard widget counts, todos, documents and memos, reminders, internal messages, and knowledge base). Every route is prefixed with /api/v1/integration.
All of them call ensureEssentialsModule first: the Essentials package must be installed, the business subscription must include essentials_module, and Essentials must be enabled for the business. Otherwise the API returns 403 with an explanatory message. Demo mode blocks mutating calls with 403 and disabled_in_demo where applicable.
Returns the same style of productivity counts shown on the web Essentials dashboard: todos (scoped to the user unless they are a business admin), documents and memos owned by the user, reminders for the user, visible knowledge-base roots, and a message count when the user may view or create messages.
| Property | Value |
|---|---|
| Method | GET |
| Path | /api/v1/integration/essentials/dashboard |
| Authentication | Bearer token or API key + secret required. |
| Extra permission | None beyond Essentials module gate. |
| Success response | 200 with data.counts (todos, documents, memos, reminders, knowledge_bases, messages) and meta.business_id, meta.is_admin. |
| Status | When it happens |
|---|---|
200 | Counts were computed successfully. |
403 | Essentials not installed, not in subscription, or not enabled for the business. |
Lists todos for the current business. Non-admin users only see todos they created or are assigned to. Admins may optionally filter by assignee using user_id.
| Property | Value |
|---|---|
| Method | GET |
| Path | /api/v1/integration/essentials/todos |
| Permission (list/show) | Superadmin, or the business subscription includes essentials_module. |
| Success response | 200 with paginated list rows (list shape: id, task_id, task, dates, status, priority, assignees, etc.). |
| Parameter | Type | Description |
|---|---|---|
per_page, page | integer | Pagination; per_page 1–100, default 20. |
priority | string | low, medium, high, urgent. |
status | string | new, in_progress, on_hold, completed. |
user_id | integer | Restrict to todos assigned to this user (via pivot). |
start_date, end_date | date | Both required together; filters by todo date. |
q | string | Search; minimum 2 characters when sent. |
sort | string | date, end_date, created_at, updated_at, status, priority, task_id. |
direction | string | asc or desc. |
Creates a todo. date (and optional end_date) are parsed using the business date/time format. Assignees require essentials.assign_todos; otherwise the creator is the only assignee. A task_id reference is generated from business Essentials settings.
| Property | Value |
|---|---|
| Method | POST |
| Path | /api/v1/integration/essentials/todos |
| Permission | Superadmin, subscription essentials_module, or essentials.add_todos. |
| Success response | 201 with detail payload (includes description, comments, media when loaded). |
| Field | Required | Description |
|---|---|---|
task | Yes | Task title. |
date | Yes | Start datetime string (business format). |
description, estimated_hours, priority, status, end_date | No | Optional fields; default status new. |
assigned_user_ids | No | Array of user ids (business staff); honored only with essentials.assign_todos. |
Returns one todo if it exists in the caller’s scoped query (same visibility rules as the list).
| Property | Value |
|---|---|
| Method | GET |
| Path | /api/v1/integration/essentials/todos/{id} |
| Permission | Same list/show gate as List Essentials todos. |
| Success response | 200 with data detail object. |
Updates a todo. Send only_status: true with status to change status only; otherwise task, date, and status are required in the full update path. assigned_user_ids syncs assignees when the user has essentials.assign_todos and only_status is not set.
| Property | Value |
|---|---|
| Method | PUT / PATCH |
| Path | /api/v1/integration/essentials/todos/{id} |
| Permission | Superadmin, subscription, or essentials.edit_todos. |
| Success response | 200 with updated detail object. |
Deletes a todo. Non-admin users may only delete todos they created.
| Property | Value |
|---|---|
| Method | DELETE |
| Path | /api/v1/integration/essentials/todos/{id} |
| Permission | Superadmin, subscription, or essentials.delete_todos. |
| Success response | 200 with { "message": "OK" }. |
Lists uploaded files (type=document) or text memos (type=memos) visible to the user: owned by the user or shared with their user id or business role.
| Property | Value |
|---|---|
| Method | GET |
| Path | /api/v1/integration/essentials/documents |
| Permission | Superadmin or subscription essentials_module. |
| Success response | 200 with paginated document rows (name is a friendly display name for files; storage_name holds the internal filename when type is document). |
| Parameter | Required | Description |
|---|---|---|
type | Yes | document or memos. |
per_page, page | No | Pagination. |
start_date, end_date | No | Both required together; filter by created_at date. |
q | No | Search name/description; min 2 characters when sent. |
sort | No | created_at or name. |
direction | No | asc or desc. |
multipart/form-data: for type=document upload file; for type=memos send name (required) and optional description.
| Property | Value |
|---|---|
| Method | POST |
| Path | /api/v1/integration/essentials/documents |
| Permission | Superadmin or subscription essentials_module. |
| Success response | 201 with detail payload including share id arrays when expanded. |
Returns one document or memo if the user can see it (owner or share).
| Property | Value |
|---|---|
| Method | GET |
| Path | /api/v1/integration/essentials/documents/{id} |
| Success response | 200 with data including shared_user_ids and shared_role_ids. |
Streams the binary file for a document row when the user is the owner or has a user/role share. Memos are not downloadable through this route.
| Property | Value |
|---|---|
| Method | GET |
| Path | /api/v1/integration/essentials/documents/{id}/download |
| Success response | File download response (not JSON). |
Replaces share lists for a document: only the owner may call this. Empty arrays clear shares of that type. New user shares can notify the target users.
| Property | Value |
|---|---|
| Method | PUT / PATCH |
| Path | /api/v1/integration/essentials/documents/{id}/shares |
| JSON body | Optional shared_user_ids and shared_role_ids arrays of integers (business users / business roles). |
| Success response | 200 with data.document_id and the effective id lists. |
Deletes a document or memo. Only the owner may delete. File rows also remove the stored file and all share rows.
| Property | Value |
|---|---|
| Method | DELETE |
| Path | /api/v1/integration/essentials/documents/{id} |
| Success response | 200 with { "message": "OK" }. |
Either returns a calendar payload when both calendar_start and calendar_end are sent (Y-m-d), or a paginated list of the current user’s reminders.
| Parameter | Description |
|---|---|
calendar_start, calendar_end | Both required together; switches response to calendar mode via Reminder::getReminders. |
start_date, end_date | Both required together; filters list mode by reminder date. |
per_page, page, q, sort, direction | List mode only; sort one of date, time, name, created_at, updated_at, repeat. |
| Property | Value |
|---|---|
| Method | GET |
| Path | /api/v1/integration/essentials/reminders |
| Permission | Superadmin or subscription essentials_module. |
date uses the business date_format; time / end_time use 12h or 24h based on business time_format. repeat is one of one_time, every_day, every_week, every_month.
| Property | Value |
|---|---|
| Method | POST |
| Path | /api/v1/integration/essentials/reminders |
| Success response | 201 with serialized reminder. |
| Property | Value |
|---|---|
| Method | GET |
| Path | /api/v1/integration/essentials/reminders/{id} |
| Scope | Current user’s reminders only. |
Partial update; at least one field required or 422 with No fields to update.
| Property | Value |
|---|---|
| Method | PUT / PATCH |
| Path | /api/v1/integration/essentials/reminders/{id} |
| Property | Value |
|---|---|
| Method | DELETE |
| Path | /api/v1/integration/essentials/reminders/{id} |
| Success response | 200 with { "message": "OK" }. |
Lists internal Essentials messages for the business, scoped by the user’s permitted locations (or all locations for unrestricted users). Optional since filters by created_at; others_only excludes the caller’s own messages.
| Property | Value |
|---|---|
| Method | GET |
| Path | /api/v1/integration/essentials/messages |
| Permission | essentials.view_message or essentials.create_message. |
| Success response | 200 with paginated rows (message is HTML with line breaks converted). |
| Parameter | Description |
|---|---|
per_page | Default 50, max 100. |
since | Parseable date; returns messages with created_at greater than this instant. |
others_only | Boolean; when true, excludes rows where user_id is the caller. |
sort, direction | Sort field currently created_at only. |
Posts a message; body is trimmed and converted with nl2br. Optional location_id must belong to the business and be permitted for the user. Notifications go to other users (all business users for global messages, or users with the location permission when scoped).
| Property | Value |
|---|---|
| Method | POST |
| Path | /api/v1/integration/essentials/messages |
| Permission | essentials.create_message. |
| JSON body | message (required string), location_id (optional integer). |
| Success response | 201 with serialized message. |
Deletes a message the user posted. Requires essentials.create_message (same check as create).
| Property | Value |
|---|---|
| Method | DELETE |
| Path | /api/v1/integration/essentials/messages/{id} |
| Success response | 200 with { "message": "OK" }. |
Paginates knowledge-base root nodes (kb_type=knowledge_base, no parent) the user may see: explicit shares, creator, or share_with=public. Each root includes nested children (sections and articles) the viewer can access.
| Property | Value |
|---|---|
| Method | GET |
| Path | /api/v1/integration/essentials/knowledge-base |
| Permission | Superadmin or subscription essentials_module. |
| Query | q (min 2 chars), per_page, page. |
Creates a root, section, or article. Hierarchy rules: roots have no parent_id; sections attach to a knowledge_base parent; articles attach to a section. For new roots, share_with may be public, private, or only_with (with shared_user_ids synced when only_with).
| Property | Value |
|---|---|
| Method | POST |
| Path | /api/v1/integration/essentials/knowledge-base |
| JSON body | title required; optional content, kb_type, parent_id, share_with, shared_user_ids. |
| Success response | 201 with nested node tree. |
Returns one node by id when visible to the user (inherits visibility from parents for nested content).
| Property | Value |
|---|---|
| Method | GET |
| Path | /api/v1/integration/essentials/knowledge-base/{id} |
| Not found | 404 when missing or not visible (same message shape as other routes). |
Partial update on visible nodes. For roots, changing share_with away from only_with clears attached users; when setting only_with, supply shared_user_ids to sync.
| Property | Value |
|---|---|
| Method | PUT / PATCH |
| Path | /api/v1/integration/essentials/knowledge-base/{id} |
Deletes a node the user can see; detaches direct user shares first.
| Property | Value |
|---|---|
| Method | DELETE |
| Path | /api/v1/integration/essentials/knowledge-base/{id} |
| Success response | 200 with { "message": "OK" }. |
| Status | Meaning |
|---|---|
403 | Unauthorized when a feature-specific permission or ownership check fails; or Essentials gate messages for module/subscription/disable. |
404 | Not found for missing ids or invisible rows. |
422 | Validation errors, date range pairing rules, empty KB update, or invalid share/user payloads. |