ResourcesOnboarding

Onboarding

Start, progress, and complete the Talkturo onboarding wizard through the API — create workspaces, save drafts, generate prompts, and provision assistants.

curl -X POST "https://app.talkturo.com/api/onboarding/start" \
  -H "Content-Type: application/json" \
  -H "Cookie: sb-access-token=session_example_7f9c2d1a" \
  -d '{
    "companyName": "Northwind Solar",
    "website": "https://northwindsolar.com",
    "assistantName": "Northwind Reception",
    "purpose": "Answer inbound questions and qualify installation leads",
    "clientToken": "7d9a3f2b-6f44-4a7d-9b1e-42a4e6c18c51"
  }'
{
  "accountId": "7f4f7c8c-2a4a-4c1e-96ee-3dd9d7a4b0b1",
  "slug": "northwind-solar"
}
curl -X POST "https://app.talkturo.com/api/onboarding/progress" \
  -H "Content-Type: application/json" \
  -H "Cookie: sb-access-token=session_example_7f9c2d1a" \
  -d '{
    "step": "conversation",
    "patch": {
      "purpose": "Answer inbound questions and book follow-up calls",
      "language": "en",
      "llmProvider": "openai",
      "model": "gpt-4.1",
      "adaptTone": true,
      "callSummaryEnabled": true,
      "callSummaryEmail": "ops@northwindsolar.com",
      "promptOverride": "You are the front desk assistant for Northwind Solar. Answer questions about residential solar installation, financing, and appointment scheduling.",
      "firstMessageOverride": "Thanks for calling Northwind Solar. How can I help today?"
    }
  }'
{
  "ok": true
}
curl "https://app.talkturo.com/api/onboarding/progress" \
  -H "Cookie: sb-access-token=session_example_7f9c2d1a"
{
  "step": "conversation",
  "generatedPrompt": {
    "prompt": "You are the front desk assistant for Northwind Solar. Help callers understand residential solar options, qualify their needs, and route urgent billing issues to a human.",
    "firstMessage": "Thanks for calling Northwind Solar. How can I help today?"
  }
}
curl -X POST "https://app.talkturo.com/api/onboarding/complete" \
  -H "Content-Type: application/json" \
  -H "Cookie: sb-access-token=session_example_7f9c2d1a" \
  -d '{
    "prompt": "You are the front desk assistant for Northwind Solar. Answer questions about residential solar installation, financing, and appointment scheduling.",
    "firstMessage": "Thanks for calling Northwind Solar. How can I help today?",
    "business": {
      "name": "Northwind Solar",
      "website": "https://northwindsolar.com",
      "phone": "+14155550182",
      "industry": "Solar",
      "city": "San Diego",
      "state": "CA",
      "country": "US"
    }
  }'
{
  "assistantId": "asst_8f3b5a2d1c4e",
  "slug": "northwind-solar"
}

Endpoint summary

MethodPathPurposeAuth
POST/api/onboarding/startStart onboarding and create or adopt a workspaceSession cookie
POST/api/onboarding/progressSave a wizard step draftSession cookie
GET/api/onboarding/progressFetch the latest draft step and generated promptSession cookie
POST/api/onboarding/completeFinish onboarding and provision the assistantSession cookie

All onboarding endpoints require a valid Supabase session cookie. These endpoints do not accept API keys.

POST /api/onboarding/start

Start an onboarding session by creating a new workspace or adopting an existing one.

Behavior

Without accountSlug, the endpoint creates a new workspace through an idempotent RPC keyed by clientToken. Repeating the same request with the same clientToken returns the same workspace instead of creating a duplicate.

With accountSlug, the endpoint adopts an existing workspace after verifying that your session belongs to that workspace.

Body parameters

body
companyNamestring
Required

Workspace company name. Must be 1 to 100 characters.

body
websitestring

Company website URL. Maximum length is 500 characters.

body
assistantNamestring

Initial assistant name. Maximum length is 100 characters.

body
purposestring

Short description of what the assistant should do.

body
clientTokenstring
Required

UUID idempotency key for the start request. Reuse the same value when retrying the same onboarding start action.

body
accountSlugstring

Existing workspace slug to adopt instead of creating a new workspace.

Response fields

accountIdstring
Required

Workspace UUID created or adopted for onboarding.

slugstring
Required

Workspace slug.

Error responses

StatusMeaning
400Invalid request body or missing required fields
401No valid session
403Session user is not a member of the requested workspace
404Requested workspace was not found
500Internal server error

POST /api/onboarding/progress

Save a draft for the current onboarding step.

Behavior

This endpoint stores a partial draft for a single wizard step. If website or purpose changes in the patch, Talkturo also kicks off background prompt generation.

Body parameters

body
stepstring
Required

Wizard step being saved.

Allowed values:companyassistantvoiceconversationtoolsnumberreview
body
patchobject
Required

Partial onboarding draft to merge into the existing saved state for the current workspace.

Patch fields

patch.assistantNamestring

Assistant display name.

patch.websitestring

Business website used for onboarding context and prompt generation.

patch.purposestring

Description of the assistant's job.

patch.languagestring

Primary language for the assistant configuration.

patch.llmProviderstring

Model provider used during assistant provisioning.

patch.modelstring

Model identifier for the selected language model provider.

patch.voiceProviderstring

Voice provider for synthesized speech.

patch.voiceIdstring

Provider-specific voice identifier.

patch.voiceNamestring

Human-readable voice name shown in the onboarding UI.

patch.voiceLanguagestring

Language or locale associated with the selected voice.

patch.adaptToneboolean

Whether generated conversation text should adapt tone automatically.

patch.callSummaryEnabledboolean

Whether to send post-call summaries.

patch.callSummaryEmailstring

Destination email for call summaries.

patch.promptOverridestring

Manual system prompt override. Maximum length is 20000 characters.

patch.firstMessageOverridestring

Manual first-message override. Maximum length is 2000 characters.

patch.numberPurchasedboolean

Whether onboarding already purchased a phone number.

patch.numberSelectedIdstring

Selected phone number identifier.

patch.numberSkippedboolean

Whether the number step was skipped.

patch.pluginsobject

Map of provider names to plugin connection settings. Each provider entry can include connectionId, enabled, and tools.

patch.flowTemplatesstring[]

Array of flow template UUIDs to clone during completion.

patch.kbFileIdsstring[]

Array of knowledge base file UUIDs to attach during completion.

patch.businessOverrideobject

Business profile values to prefer over generated or inferred values.

Nested patch objects

patch.plugins.provider.connectionIdstring

Connection identifier for the external provider. Replace provider with the provider key you store in the plugins object.

patch.plugins.provider.enabledboolean

Whether the provider integration is enabled.

patch.plugins.provider.toolsstring[]

Tool identifiers enabled for that provider connection.

patch.businessOverride.namestring

Business name override.

patch.businessOverride.websitestring

Business website override.

patch.businessOverride.phonestring

Business phone number override.

patch.businessOverride.industrystring

Business industry override.

patch.businessOverride.citystring

Business city override.

patch.businessOverride.statestring

Business state or region override.

patch.businessOverride.countrystring

Business country override.

Response fields

okboolean
Required

Returns true when the draft was saved.

Error responses

StatusMeaning
400Invalid step or invalid patch payload
401No valid session
404Active onboarding workspace was not found
500Internal server error

Saving progress can trigger asynchronous prompt generation when website or purpose changes. A successful 200 response confirms the draft was saved, not that prompt generation has finished.

GET /api/onboarding/progress

Fetch the current draft step and the latest generated prompt, if one is available.

Response fields

stepstring
Required

Most recently saved onboarding step.

generatedPromptobject|null
Required

Latest generated prompt payload, or null if generation has not completed or has not started.

generatedPrompt.promptstring

Generated assistant system prompt.

generatedPrompt.firstMessagestring

Generated opening message for the assistant.

Error responses

StatusMeaning
401No valid session
404Active onboarding workspace was not found
500Internal server error

POST /api/onboarding/complete

Complete onboarding and provision the assistant, phone number, tools, and related resources.

Behavior

The endpoint resolves the final prompt, persists the business profile, creates the assistant configuration, attaches MCP plugins, attaches knowledge base files, clones selected flow templates, assigns a phone number, provisions a LiveKit trunk, and marks onboarding as complete.

Body parameters

body
promptstring

Final system prompt to save on the assistant. Maximum length is 20000 characters.

body
firstMessagestring

Final assistant opening message. Maximum length is 2000 characters.

body
businessobject

Business profile values to save before assistant provisioning.

Business fields

business.namestring

Business name.

business.websitestring

Business website URL.

business.phonestring

Business phone number.

business.industrystring

Business industry.

business.citystring

Business city.

business.statestring

Business state or region.

business.countrystring

Two-character ISO country code.

Response fields

assistantIdstring
Required

Created assistant identifier.

slugstring
Required

Workspace slug for the completed onboarding.

Error responses

StatusMeaning
400Invalid payload or failed validation
401No valid session
404Active onboarding workspace was not found
500Internal server error

Completion is a provisioning operation with multiple side effects. Retrying after a network failure can create ambiguity unless your integration first checks onboarding state and assistant creation results.