Skip to main content

​
October 11, 2026

  • Enhancement: PUT /api/board/{boardId}/configuration/fields/stage now lets you add stages, reorder them and recolor them. Send the full data list in the order you want. New stages can set color, closed and won (deal boards only). Renaming a stage, removing one, and changing an existing stage between open, closed and won are still refused, because cards, Automations and saved filters refer to stages by name. Open board views in the Aptly app refresh when stages change.
  • Enhancement: POST /api/boards now accepts an optional stages list so a new board can start with your own pipeline instead of the default one. Each stage has a label, and optionally a color, closed (ends a card’s life, like Done or Lost) and won (a closed stage that counts as won, deal boards only). The first stage is where new cards start, so it can’t be closed or won, and labels must be unique. Omit stages and boards are created exactly as before. Stages can only be set when the board is created.
  • Enhancement: The API key that creates a board with POST /api/boards now keeps access to that board. Even when the key is limited to specific boards and does not have the “Edit Boards” toggle, it can read and write the board’s cards, see it in GET /api/boards, and (with the update permission) add, change and remove its fields, change its theme and archive it. This applies only to boards created through the API by that key, and ends when the key is deleted. Automations still need their own “Automations” toggle, and Tasks, Files and mirror-field links to other boards still follow the key’s board list. Boards created before this change are not affected.

​
October 8, 2026

  • New Endpoint: POST /api/board/{boardId}/configuration/automations — Create an Automation on a board: a stage, segment (conditions) or reply trigger, a timing, and one or more actions (email, sms, task, assign, update_fields, stage, due_date, notify, archive, archive_convos, webhook). Requires update permission and the key’s separate “Automations” access toggle (off by default, independent of “Edit Boards”). Automations are always created paused. Every stage, field, template, inbox, user, team and condition in the request is checked against your board and organization, and the request is rejected with a message naming the problem rather than creating an automation that wouldn’t work.
  • Breaking Change: GET /api/board/{boardId}/configuration/automations now lists a board’s Automations (previously it returned the older create-card rules). Those rules are now at GET /api/board/{boardId}/configuration/card-rules, with the same response shape the old automations endpoint returned. Update any integration that read create-card rules from .../automations.
  • Deprecated: GET /api/board/{boardId}/configuration/workflows — use GET .../configuration/automations, which returns the same data. The old path still works.
  • Note: GET /api/board/{boardId}/configuration is unchanged: its automations key still holds the older create-card rules and its workflows key holds the board’s Automations.

​
October 6, 2026

  • New Endpoint: POST /api/board/{boardId}/configuration/fields — Add a custom field to a board. Same field shape and allowed field types as POST /api/boards.
  • New Endpoint: PUT /api/board/{boardId}/configuration/fields/{fieldUuid} — Update a field’s name, optional, pinned, defaultValue, or (select-type fields) option list. A field’s type and uuid never change.
  • New Endpoint: DELETE /api/board/{boardId}/configuration/fields/{fieldUuid} — Delete a field. Standard, locked, mirror and integration-managed fields can’t be deleted, and a field used by a saved filter (or a workflow/automation that runs off one) returns 409 CONFLICT listing what uses it.
  • New Endpoint: PATCH /api/board/{boardId}/configuration/theme — Update a board’s name, cardName, color, icon, description and shortCode.
  • New Endpoint: DELETE /api/board/{boardId} — Archive a board: its cards, saved filters and templates are archived and the cards’ open tasks closed. There is no un-archive endpoint.
  • New Endpoint: POST /api/board/{boardId}/configuration/mirror-fields — Add a field that mirrors a field of another board (targetBoardUuid + targetFieldUuid, optional name, readOnly). Requires the same “Edit Boards” access; the target board must also be inside the key’s board allowlist and API-enabled.
  • Enhancement: These five endpoints require update permission plus a new “Edit Boards” access toggle on the API key (Setup → Developer; off by default). An archived board no longer resolves through the Board API (404), so it stops accepting card reads and writes.
  • Fix: checkboxlist (Task List) fields no longer require a data option list when created via POST /api/boards or the new add-field endpoint - a task list holds checklist items, not options. Only singleselect and multiselect need data.

​
October 1, 2026

  • New Endpoint: POST /api/boards — Create a new board. Accepts name, an optional boardType (ticket or deal, defaults to ticket), and an optional fields array of custom fields. A stage field with a type-appropriate default pipeline is always added automatically. Requires the key’s “Create Boards” access toggle to be explicitly enabled in Setup → Developer, in addition to insert permission.
  • New Endpoint: DELETE /api/board/{boardId}/{cardId} — Archives a card (soft delete; the card is never removed, only marked archived).
  • New Endpoint: DELETE /api/board/{boardId}/webhook — Removes a board’s webhook. Idempotent: returns 200 even when no webhook is currently set. POST /api/board/{boardId}/webhook already handled add/update (re-pointing an existing webhook rotates its signing key); this closes out the set with a way to remove one.

​
September 30, 2026

  • New Endpoint: POST /api/board/{boardId}/list — Paginated, filterable card listing driven by saved segments or ad hoc rule sets; replaces query-based listing on GET /api/board/{boardId}, which is now deprecated for that purpose.

​
September 29, 2026

  • Enhancement: GET /api/inboxes/{channelId}/messages accepts a new unreadOnly query param to return only unread threads, applied before paging so count reflects the filtered total.

​
September 28, 2026

  • New Endpoint: POST /api/contacts/conversations — Find a batch of contacts’ real email, SMS, and call conversations across accessible inboxes, without requiring a helpdesk ticket.
  • New Endpoint: GET /api/contacts/{contactId}/conversations — Same lookup for a single contact.

​
September 25, 2026

  • Fix: POST /api/board/{boardId} updates now seed stage/tasksection/task workflow triggers the same way the Meteor app does — previously only newly created cards got them, so an update made through the API could silently skip automations a stage or task workflow should have started.

​
September 24, 2026

  • New Endpoint: GET /api/tours/feedback — List post-tour feedback surveys for the company.
  • New Endpoint: GET /api/tours/{showingId}/feedback — Get one showing’s tour feedback survey.
  • Enhancement: GET /api/knowledge/tree now accepts the same filters as GET /api/knowledge/list (board, card, conversation, search, archived, owner, date range, unlinked) and prunes the tree to matches plus their ancestors/descendants, with each node reporting a matched flag. GET /api/knowledge/{id}/children gains an archived param so an archived folder found via the filtered tree can be expanded.
  • Fix: Creating a knowledge document under a parent that belongs to a board now inherits that board automatically, instead of leaving the new document invisible on the board’s own Docs tab.

​
September 23, 2026

  • New Endpoint: POST /api/board/{boardId}/webhook — Sets or updates a board’s webhook URL for the API integration.
  • Enhancement: Every /api/* response now includes an X-Api-Version header reporting the API’s request-contract version, and a new GET /version endpoint returns the same value.

​
September 18, 2026

  • New Endpoint: GET /api/board/{boardId}/merge-fields — Returns the merge-field catalog available for a board, grouped by recipient/board/sender/etc., for building {{...}} merge placeholders in templates.

​
September 17, 2026

  • New Endpoint: POST /api/templates — Create a communication template (sms/email/form/eSignature/pdf), with merge-placeholder shape validation and attachment resolution.
  • New Endpoint: PUT /api/templates/{id} — Update an existing communication template, sharing the same validation rules as create.
  • Enhancement: GET /api/knowledge/{id} now returns a fully enriched document — folder path, shares, children, links, and metadata — instead of just { _id, name, html }, and enforces per-user access when called with a delegate token (a document you don’t have access to now 404s rather than exposing that it exists).
  • New Endpoint: GET /api/knowledge/list — List knowledge documents, with filters for folder, owner, created/updated date range, archived state, and unlinked documents.
  • New Endpoint: GET /api/knowledge/tree — Browse the knowledge base as a folder tree.
  • New Endpoint: GET /api/knowledge/{id}/children — List a knowledge document’s child documents and folders.
  • Fix: PUT /api/knowledge/{id} switching a document’s access to private now automatically grants a share to the acting user (or the document’s original creator) when it has none, instead of leaving it with no one able to access it.

​
September 16, 2026

  • Enhancement: GET /api/inboxes/{channelId}/messages thread status and a new isJunk field now report the stream’s own state instead of inferring it from closedAt — status is one of closed/new/open/sent (previously only open/closed), and isJunk is archived/not_junk/junk; either is null when the thread has no recorded value. A new unread boolean is also returned. Breaking: the thread’s assignee field is renamed to assigneeId.
  • New Endpoint: POST /api/phone/send-sms — Sends an SMS from a Twilio channel as a user of the company: one message enqueued per recipient rather than sent inline. Accepts a partner token, an API key, or a delegate token with phone:* write scope.

​
September 14, 2026

  • Fix: POST /api/board/{boardId} no longer overwrites a card’s original createdAt/createdBy when updating an existing card — both were previously reset to the update’s time and actor.

​
September 10, 2026

  • Fix: Presigned download links returned for card file/files fields now report an expiresAt that reflects when the link actually stops working, instead of always advertising a full hour — a link signed near the end of the server’s AWS session could previously fail immediately with ExpiredToken despite claiming an hour of remaining validity.

​
September 9, 2026

  • Enhancement: GET /api/board/{boardId} and GET /api/board/{boardId}/{cardId} now resolve file/files field values into file objects — { fileId, name, size, type, url, expiresAt } — carrying a presigned S3 download link, instead of returning bare file ids. An id with no readable file record degrades to { fileId } with no url.

​
September 8, 2026

  • Enhancement: POST /api/board/{boardId} now defaults a new card’s stage to the board’s first stage option when the request omits one, instead of leaving the card with no stage.

​
September 4, 2026

  • New Endpoint: GET /api/contacts/{contactId}/sentiment — Returns a contact’s conversation sentiment over the last 30 days, merged across every channel in the company into one daily series, plus a recency-weighted overall score and distinct conversation count.

​
September 2, 2026

  • Enhancement: POST /api/board/{boardId} now computes and stores initial workflow triggers on newly inserted cards, so board automations that fire on stage/task changes apply the same way to API-created cards as to cards created in the app.

​
August 24, 2026

  • Enhancement: POST /api/web-forms/{formId} can now link a submission to a contact with no Configuration-tab setup — reserved submission keys (contactFirstName, contactLastName, contactFullName, contactEmail, contactPhone) create or match a contact automatically when the form’s board has exactly one person/persons field. An explicit Configuration-tab contact mapping still takes precedence, field by field, over these reserved keys.

​
August 20, 2026

  • Enhancement: POST /api/web-forms/{formId} now supports linking a submission to a contact — when the form has contact mapping configured, it looks up an existing person by normalized email/phone (or creates one) and writes the resulting contact reference onto the board’s configured field.

​
August 18, 2026

  • Enhancement: GET /api/inboxes/{channelId}/messages threads now include a labels array ({ id, name }) listing the folder labels applied to the thread. Only real folder labels are returned — the encoded scoping ids also stored on a thread (channel, assignee, mention, person type, category) are omitted.

​
August 16, 2026

  • New Endpoint: POST /api/web-forms/{formId} — Public submission endpoint for Aptly Web Forms. Maps the submitted data onto the form’s board, creating a new card or updating a matching existing one (depending on the form’s configured match mode), and records the submission. The API key must be the exact token minted for the form — a board-scoped insert key can only submit to the one form it was created for.

​
August 13, 2026

  • Enhancement: Board API keys (x-token) can now be scoped to specific boards and to a subset of read/insert/update permissions, configurable from Setup → Developer → Board API Tokens. Requests outside a key’s allowed boards or permissions now receive a 403 FORBIDDEN. Existing keys are unaffected — an absent boardIds/permissions on a key means full access to all boards, as before.

​
July 31, 2026

  • New Endpoint: GET /api/inboxes — Lists the email and phone/SMS inboxes your credential can query. With a delegate token (inboxes:* scope) results are limited to inboxes the authenticated user can reach and each carries access: owned or monitored; ?scope= filters on that. API keys and partner tokens are company-scoped, so they return every inbox in the company and reject ?scope=.
  • New Endpoint: GET /api/inboxes/{channelId}/messages — Threads on an inbox, newest activity first, each with its messages and per-thread metrics (first/average response time, response count, reopen flag, touch counts). Filter by dateFrom/dateTo (exclusive, max 400 days) and direction; page over threads with page/pageSize (max 200). Automated/junk threads are excluded unless includeJunk=true.
  • Enhancement: GET /api/inboxes/{channelId}/analytics now returns sentiment and topics. sentiment gives the average AI sentiment score for the window plus the coverage it was computed from (scoredThreads / threadCount / pct) and an enabled flag reporting whether scoring is currently on for that inbox — scores exist only for threads the pipeline actually scored, so the coverage tells you how much of the window the average describes. topics lists the categories applied to threads in the window with their thread counts. Both are also broken out per group when groupBy is used (without the inbox-level enabled flag). Qualitative tone summaries are still not included.
  • New Endpoint: GET /api/inboxes/{channelId}/health — Scores an inbox’s message volume for the requested window against its own recent baseline, for health and risk surfaces. The baseline is a trailing average of the baselinePeriods same-length windows before dateFrom (default 3, max 12). Returns volumeVsBaselinePct, a trend comparing the two halves of the window, a severityScore (0–100, tracking decline magnitude — growth scores 0), a severityLabel (critical 75+, high 50–74, moderate 25–49, low 1–24, none) and tags such as Usage down, No activity and Still falling. When there is no baseline volume to compare against, volumeVsBaselinePct and severityScore are null and severityLabel is insufficient_history rather than reporting a misleading −100%.
  • New Endpoint: GET /api/inboxes/{channelId}/trends — A gap-free volume and response-time time series for an inbox, rolled up server-side by day, week, month or quarter. dateFrom and dateTo are both required (dateTo exclusive, max 400 days), and periods with no activity are returned with zero volume rather than omitted so the series can be charted directly. Bucketing is UTC and weeks start Monday. Note the two bucketing bases: volume counts messages during the period, while threadCount and the response/rate figures describe threads whose last activity fell in the period — don’t divide one by the other.
  • New Endpoint: GET /api/inboxes/{channelId}/analytics — Aggregated conversation metrics for one inbox: average first and overall response time with the responseCount behind them, one-touch and reopen rates, inbound/outbound volume, distinct contact count, plus first-party noCustomerResponseCount (outbound that never got a reply) and awaitingOurReplyCount (open threads where the contact spoke last). groupBy=assignee or groupBy=contactType breaks the same metrics out per group. Response times are business-hours aware, using your configured business hours and holidays, so they reconcile with in-app reports. Averages and rates are null rather than 0 when a window has nothing to measure.

​
July 29, 2026

  • Fix: GET /api/board/{boardId} and GET /api/board/{boardId}/{cardId} now return Aptly’s standard card fields (name, stage, dueAt, assignee, and the rest of the built-in field set) alongside your board’s custom fields. Previously only fields explicitly defined on the board were returned, so standard fields came back missing. Where a custom field shares a uuid with a standard one, your board’s definition wins.
  • Enhancement: Card responses now include a lastActivity object describing the most recent conversation on the card — content (message preview), type (email, sms, voice), direction (in or out), publishedAt, and conversationUrl, a deep link to the conversation thread in Aptly. It is null when the card has no activity, and conversationUrl is null when the activity isn’t attached to a thread.
  • Fix: GET /api/board/{boardId}/{cardId} now returns assignee as the assigned user’s display name, matching the list endpoint. It previously returned the raw user id.

​
July 20, 2026

  • Enhancement: POST /api/knowledge/create and PUT /api/knowledge/{id} now accept an optional markdown field as an alternative to html for the document body — provide one or the other, not both (a 400 is returned if both are set). Knowledge doc HTML retrieval (GET /api/knowledge/{id}) also now renders through an upgraded conversion engine with table support, with an automatic fallback for documents created before this change.

​
July 17, 2026

  • New Endpoint: GET /api/docs/openapi — Returns the raw contents of this OpenAPI spec (docs/openapi.yaml) as text/yaml. No authentication required.

​
July 9, 2026

  • Enhancement: POST /api/email/create-draft and POST /api/email/send now accept an optional discussionId to reply into an existing thread instead of starting a new one. On send, supplying discussionId without uuid appends the new draft as a reply to that thread; the thread’s own subject is kept. The thread must belong to the same company and channel.

​
June 26, 2026

  • New Endpoint: POST /api/files/upload-url — Request a presigned upload for a file. Returns a fileId plus the url and form fields for uploading the file directly to storage. The file is attached to a channel, aptlet, or knowledge doc (which must exist in your company), with content-type and 1 byte–50 MB size validation.
  • New Endpoint: POST /api/files/upload-complete — Finalize a direct upload after the file has been sent to storage. Records the file and returns its fileId and download url. Both endpoints accept an API key (x-token) or a delegate token with the files:* scope.
  • Enhancement: POST /api/email/create-draft and POST /api/email/send now accept attachmentIds to include uploaded files as attachments, and auto-detect inline images embedded in the HTML body via their file download URL (tagged and registered automatically — don’t also list them in attachmentIds). Upload each file first with the direct upload flow (POST /api/files/upload-url → S3 → POST /api/files/upload-complete), then pass the returned fileIds.

​
June 15, 2026

  • New Endpoint: GET /api/routing-groups — List all active routing groups for the authenticated company. Accepts an API key (x-token) or a delegate token with routing-groups read scope.
  • New Endpoint: POST /api/routing-groups/create — Create a routing group with a name, ring type (simultaneous or sequential), destination configuration, and optional caller experience and overflow settings. Returns the new group’s _id.
  • New Endpoint: PUT /api/routing-groups/{id} — Update an existing routing group. All fields are optional — only provided fields are changed. Pass null to clear a field.
  • New Endpoint: POST /api/routing-groups/{id}/archive — Archive (soft-delete) a routing group. Archived groups are excluded from list results and cannot be updated.

​
June 9, 2026

  • New Endpoint: POST /api/tasks/search — Query tasks for your company with optional filters (assignee, completion/pinned state, priority, board/card, stream/channel, and dueAt/checkedAt/updatedAt date ranges). Returns the matching tasks, or a count when useCount is set.
  • New Endpoint: POST /api/tasks — Create a task. When aptletInstanceId is provided, the task is also mirrored as a checklist entry on that card.
  • New Endpoint: GET /api/tasks/{taskId} — Fetch a single task with related card/board context and resolved attachments; pass includeMetadata=true for display labels and the resolved assignee.
  • New Endpoint: PUT /api/tasks/{taskId} — Update a task and keep its card-checklist mirror entry in sync. All task endpoints accept an API key (x-token) or a delegate token with the tasks:* scope.

​
June 3, 2026

  • New: Embedded iframe apps can now trigger Aptly UI interactions via a postMessage action system or the Aptly SDK. Nine actions are available: open a card pane, open a card in fullscreen, start the dialer, open the email/SMS composer, create a calendar event, create a card, create a task, create a contact, and navigate to a contact. Actions must be explicitly enabled per embed by an admin. See Embed App Actions.
  • New SDK methods: aptly.openCardPane(), aptly.openCardView(), aptly.startDialer(), aptly.openEmailComposer(), aptly.createEvent(), aptly.createCard(), aptly.createTask(), aptly.createContact(), aptly.navigateToContact(), and aptly.action() — each returns Promise<{ success, error? }> and times out after 3 seconds.
  • New SDK property: aptly.actions — array of action IDs the current embed has been granted, for runtime capability checks.
  • Enhancement: POST /api/email/create-draft and POST /api/email/send now accept an optional aptletInstanceId in the request body. When set, the outbound is linked to that card — the email is logged as an activity on the card and the discussion is tagged with it. Works whether the draft is pre-created or created on-the-fly.

​
May 26, 2026

  • New Endpoint: GET /api/app/me — Returns identity information for the credential used in the request. Delegate tokens return user identity (and embedded-app context when an appClientId is present); API keys return company identity; partner tokens return their permission list.
  • New Endpoint: GET /api/board/{boardId}/configuration — Returns all board configuration sections in one call: fields, automations, options, tabViews, workflows, groups, shares, theme, and filters. Accepts an API key or a partner token with board-admin permission (delegate tokens are not supported for board configuration endpoints).
  • New Endpoint: GET /api/board/{boardId}/configuration/automations — List the automations configured on a board.
  • New Endpoint: GET /api/board/{boardId}/configuration/options — Get the current board-level option flags.
  • New Endpoint: GET /api/board/{boardId}/configuration/fields — List all fields defined on a board, including archived ones.
  • New Endpoint: GET /api/board/{boardId}/configuration/workflows — List the workflows (sequences) configured on a board.
  • New Endpoint: GET /api/board/{boardId}/configuration/groups — List the field groups (sections) configured on a board.
  • New Endpoint: GET /api/board/{boardId}/configuration/shares — Get a board’s access type (public/private) and its ACL entries.
  • New Endpoint: GET /api/board/{boardId}/configuration/theme — Get a board’s display name, card name, color, icon, description, and short code.
  • New Endpoint: GET /api/board/{boardId}/configuration/filters — List saved filters for a board. Company-scoped filters are always included; private (user-scoped) filters are included when authenticating with a delegate token that carries a userId.
  • New Endpoint: GET /api/templates — List communication templates for your company, with optional filters for templateType, aptletUuid, and archived. Accepts an API key, a delegate token with templates scope, or a partner token with templates permission (pass companyId as a query param with partner auth).
  • New Endpoint: GET /api/templates/{id} — Get a single communication template by ID.
  • Enhancement: POST /api/board/{boardId}/tabView is now also available at POST /api/board/{boardId}/configuration/tabViews. The original path remains active as a legacy alias.
  • Enhancement: GET /api/boards now accepts delegate tokens with boards read scope in addition to API keys. The endpoints array in each board entry now includes all board configuration endpoints.

​
May 25, 2026

  • New Endpoint: GET /api/inboxes/{channelId}/drafts — List the unsent drafts on a given email inbox. Each item is the raw draft entry with the parent streamId attached; drafts currently being sent are excluded. Accepts the same dual-auth as the rest of the email endpoints (API key, delegate token with email:* read scope, or partner bearer token with inboxes/internal-admin).

​
May 21, 2026

  • New Endpoint: POST /api/email/create-draft — Create a new outbound email draft discussion from recipient and content fields (to, cc, bcc, subject, body, channelId). Returns streamId and draftUuid for use with POST /api/email/send.
  • New Endpoint: POST /api/email/send — Send an outbound email, either from an existing draft (discussionId + uuid) or on-the-fly from bare email fields. Auto-assignment is always applied when the draft is finalized.
  • New Endpoint: GET /api/users/{userId}/inboxes — List the email inboxes (Hermes/Nylas channels) accessible to a user, including both personal channels and team-shared channels. Each inbox is tagged kind: "personal" or kind: "shared".
  • Enhancement: Delegate tokens now support an email:* scope. When granted (read or write), the token can call POST /api/email/create-draft, POST /api/email/send, and GET /api/users/{userId}/inboxes on behalf of the user.

​
May 4, 2026

  • Fix: Card objects in board responses now consistently include both _id and cardId fields.

​
April 24, 2026 — Delegate Token Authentication

  • New Endpoint: POST /api/app/verify — Verify a short-lived delegate token and retrieve user identity without an API key. For use by embedded apps and plugins that receive a token from the Aptly platform.
  • New Endpoint: POST /api/board/verify-user — Verify a delegate token scoped to board access and retrieve the associated user context.
  • New Endpoint: GET /api/board/{boardId}/{cardId}/comments — List all comments on a card in chronological order.
  • New Endpoint: GET /api/board/{boardId}/{cardId}/contacts — List person contacts linked to a card via its person fields.
  • New Endpoint: POST /api/board/{boardId}/{cardId}/comment — Add or update a comment on a card.
  • New Endpoint: POST /api/board/{boardId}/{cardId}/file — Upload a file attachment to a card (multipart/form-data, max 50 MB).
  • New Endpoint: POST /api/board/{boardId}/tabView — Embed a tab view on a board.
  • Enhancement: Board, Contacts, and Knowledge endpoints now accept delegate token authentication (Authorization: DelegateToken <token>) in addition to API keys. Tokens carry explicit read and write scopes per resource.
  • Enhancement: GET /api/board/{boardId} now supports an assignee query parameter to filter cards by assigned user.
  • Enhancement: Cards created or updated via a delegate token now record the authenticated user as createdBy / updatedBy rather than attributing changes to “aptly”.

​
April 20, 2026

  • New Endpoint: GET /api/company/info — Retrieve your company’s profile including name, address, contact details, and logo URL.

​
April 16, 2026

  • New Endpoint: GET /api/users — List all non-archived users in your company.

​
April 14, 2026

  • New Endpoint: GET /api/boards — Discover all API-enabled boards for your account, including their UUIDs and ready-to-use endpoint URLs for card operations.

​
April 7, 2026

  • Enhancement: GET /api/contacts now supports updated_after and updated_before query parameters to filter contacts by last-updated timestamp.