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"
}'
const response = await fetch("https://app.talkturo.com/api/onboarding/start", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Cookie": "sb-access-token=session_example_7f9c2d1a"
},
body: JSON.stringify({
companyName: "Northwind Solar",
website: "https://northwindsolar.com",
assistantName: "Northwind Reception",
purpose: "Answer inbound questions and qualify installation leads",
clientToken: "7d9a3f2b-6f44-4a7d-9b1e-42a4e6c18c51"
})
});
const data = await response.json();
console.log(data);
{
"accountId": "7f4f7c8c-2a4a-4c1e-96ee-3dd9d7a4b0b1",
"slug": "northwind-solar"
}
{
"error": "You do not have access to this workspace"
}
{
"error": "Workspace not found"
}
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?"
}
}'
const response = await fetch("https://app.talkturo.com/api/onboarding/progress", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Cookie": "sb-access-token=session_example_7f9c2d1a"
},
body: JSON.stringify({
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?"
}
})
});
const data = await response.json();
console.log(data);
{
"ok": true
}
{
"error": "Invalid onboarding step"
}
curl "https://app.talkturo.com/api/onboarding/progress" \
-H "Cookie: sb-access-token=session_example_7f9c2d1a"
const response = await fetch("https://app.talkturo.com/api/onboarding/progress", {
headers: {
"Cookie": "sb-access-token=session_example_7f9c2d1a"
}
});
const data = await response.json();
console.log(data);
{
"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"
}
}'
const response = await fetch("https://app.talkturo.com/api/onboarding/complete", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Cookie": "sb-access-token=session_example_7f9c2d1a"
},
body: JSON.stringify({
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"
}
})
});
const data = await response.json();
console.log(data);
{
"assistantId": "asst_8f3b5a2d1c4e",
"slug": "northwind-solar"
}
{
"error": "Prompt exceeds maximum length"
}
Endpoint summary
| Method | Path | Purpose | Auth |
|---|---|---|---|
POST | /api/onboarding/start | Start onboarding and create or adopt a workspace | Session cookie |
POST | /api/onboarding/progress | Save a wizard step draft | Session cookie |
GET | /api/onboarding/progress | Fetch the latest draft step and generated prompt | Session cookie |
POST | /api/onboarding/complete | Finish onboarding and provision the assistant | Session 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
Workspace company name. Must be 1 to 100 characters.
Company website URL. Maximum length is 500 characters.
Initial assistant name. Maximum length is 100 characters.
Short description of what the assistant should do.
UUID idempotency key for the start request. Reuse the same value when retrying the same onboarding start action.
Existing workspace slug to adopt instead of creating a new workspace.
Response fields
Workspace UUID created or adopted for onboarding.
Workspace slug.
Error responses
| Status | Meaning |
|---|---|
400 | Invalid request body or missing required fields |
401 | No valid session |
403 | Session user is not a member of the requested workspace |
404 | Requested workspace was not found |
500 | Internal 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
Wizard step being saved.
companyassistantvoiceconversationtoolsnumberreviewPartial onboarding draft to merge into the existing saved state for the current workspace.
Patch fields
Assistant display name.
Business website used for onboarding context and prompt generation.
Description of the assistant's job.
Primary language for the assistant configuration.
Model provider used during assistant provisioning.
Model identifier for the selected language model provider.
Voice provider for synthesized speech.
Provider-specific voice identifier.
Human-readable voice name shown in the onboarding UI.
Language or locale associated with the selected voice.
Whether generated conversation text should adapt tone automatically.
Whether to send post-call summaries.
Destination email for call summaries.
Manual system prompt override. Maximum length is 20000 characters.
Manual first-message override. Maximum length is 2000 characters.
Whether onboarding already purchased a phone number.
Selected phone number identifier.
Whether the number step was skipped.
Map of provider names to plugin connection settings. Each provider entry can include connectionId, enabled, and tools.
Array of flow template UUIDs to clone during completion.
Array of knowledge base file UUIDs to attach during completion.
Business profile values to prefer over generated or inferred values.
Nested patch objects
Connection identifier for the external provider. Replace provider with the provider key you store in the plugins object.
Whether the provider integration is enabled.
Tool identifiers enabled for that provider connection.
Business name override.
Business website override.
Business phone number override.
Business industry override.
Business city override.
Business state or region override.
Business country override.
Response fields
Returns true when the draft was saved.
Error responses
| Status | Meaning |
|---|---|
400 | Invalid step or invalid patch payload |
401 | No valid session |
404 | Active onboarding workspace was not found |
500 | Internal 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
Most recently saved onboarding step.
Latest generated prompt payload, or null if generation has not completed or has not started.
Generated assistant system prompt.
Generated opening message for the assistant.
Error responses
| Status | Meaning |
|---|---|
401 | No valid session |
404 | Active onboarding workspace was not found |
500 | Internal 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
Final system prompt to save on the assistant. Maximum length is 20000 characters.
Final assistant opening message. Maximum length is 2000 characters.
Business profile values to save before assistant provisioning.
Business fields
Business name.
Business website URL.
Business phone number.
Business industry.
Business city.
Business state or region.
Two-character ISO country code.
Response fields
Created assistant identifier.
Workspace slug for the completed onboarding.
Error responses
| Status | Meaning |
|---|---|
400 | Invalid payload or failed validation |
401 | No valid session |
404 | Active onboarding workspace was not found |
500 | Internal 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.