Overview

What this reference explains

An assistant is an AI voice agent that answers phone calls for a business. It is built from a prompt template (industry-specific or general), a personality (a platform-managed bundle of name, voice and tone), business metadata injected into the prompt, and call-behaviour settings (greeting, voicemail handling, call length, keypad input, and more).

This reference shows how the assistant system works under the hood: every dashboard action goes through the endpoints documented here, with exact fields, required/nullable flags, validation limits, the database columns behind them, and precise responses. Changes are applied to the live voice platform and mirrored locally in the same request.

Where the system serves this API

Assistant endpoints live under:

https://app.sulus.ai/api

Note: assistants are not part of the /api/v1 surface — there is no /api/v1/assistants. The v2 builder endpoints under /api/v2/assistants are a layered template engine for the same assistants, not a separate public version.

Response envelope

This module answers with the panel envelope:

• Lists: {"success": true, "data": [ … ], "pagination": {"current_page","last_page","per_page","total","from","to"}}
• Single resources: {"success": true, "data": { … }, "message": "…"}
• Failures: {"success": false, "message": "…"}

Responses may additionally carry a platform mirror object of the live voice configuration; it is internal and not part of the documented contract.

Identifiers

The public identifier of an assistant is assistant_id — a UUID present on every assistant object. Every path parameter written as {assistantId} takes this value, never the numeric row id (which also appears in responses as id but is not routable).

Feature availability

This module is gated by the assistants feature. When disabled, every endpoint returns 403 with {"message":"This feature is not enabled for your account. Please contact your administrator.","feature":"assistants"}.

Core concepts

• Templates drive the prompt structure; variableValues fill the template’s custom fields.
• Personalities are platform-managed bundles (name + voice + tone). Users pick one; the underlying voice engine settings are set by the platform, never edited directly.
• Creation quota — non-admin accounts are limited by their subscription; exceeding it returns 403 with an account-specific message.
• Phone number on create — passing selected_phone_number purchases and wires that number to the new assistant in the same request.
• Live sync — create/update writes to the live voice platform first; if that fails, nothing is saved and a 500 with a clear message is returned.
• Advanced editor — a superset endpoint for full configuration; the regular update covers the common fields.
• Version history — configuration changes are journalled; any entry can be restored.