Create Agent

Creates a new AI voice agent with a complete conversation configuration and optional knowledge base files.

Required fields

name — display name for this agent.

voice — the AI voice model to use for speech synthesis.

direction — call direction: inbound (agent answers calls) or outbound (agent places calls).

org_unit_id — the organizational unit this agent belongs to.

Conversation configuration

greeting — the opening message spoken when a caller connects.

prompt — the main system prompt that defines the agent's persona, knowledge, and conversation goals.
Knowledge base files
Upload up to 10 files (PDF, DOCX, TXT) as part of the multipart form. These documents are embedded and used by the agent to answer caller questions. Maximum 10 MB per file.

Call handling

max_call_duration — maximum seconds the agent will stay on a call before ending (default: 300).
Response
Returns the full agent configuration including the assigned agent ID.

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

curl --location --request POST 'https://platform-api.convirza.com/v3/ai-voice-agents' \ --header 'Authorization: Bearer <token>' \ --form 'voiceagent_name="Sales Assistant - Inbound Leads"' \ --form 'greetings="Hello, thanks for calling Convirza. How can I help you today?"' \ --form 'prompt="You are a helpful and professional sales assistant for Convirza. Your goal is to qualify leads, answer questions about our call tracking solutions, and schedule demos. Always be polite, concise, and focus on understanding the caller'\''s needs."' \ --form 'voice_id="3"' \ --form 'inherited_prompt_id="12"' \ --form 'direction="inbound"' \ --form 'urls="https://docs.example.com/sales-playbook"' \ --form 'urls="https://www.example.com/pricing"' \ --form 'integrations=""' \ --form 'integrations=""' \ --form 'integrations=""' \ --form 'more_information="Use concise and clear responses. If the caller asks about pricing, mention our flexible plans starting at $99/month. Always attempt to schedule a demo for qualified leads."' \ --form 'config="{ \"background_noise\": false, \"volume\": 0.8, \"block_non_intelliquent_number\": true }"' \ --form 'max_call_duration="300"' \ --form 'notification_time="30"' \ --form 'notification_message="Agent has been on the call for 30 seconds."' \ --form 'created_by="2001"' \ --form 'ext_org_unit_id="1001"' \ --form 'knowledge_base=""' \ --form 'knowledge_base=""' \ --form 'org_unit_id="1001"' \ --form 'industry_id="7"' \ --form 'files=""'

{ "code": 200, "message": "Success", "data": { "id": 101, "primary_phone_number": "+14255551234", "prompt": "You are a professional sales assistant for Convirza. Your goal is to qualify inbound leads, answer product questions, and schedule demos. Always be concise, friendly, and focused on the caller's needs.", "greetings": "Thank you for calling Convirza! How can I assist you today?", "voiceagent_type_id": 1, "voice_id": 3, "voiceagent_name": "Sales Assistant — Inbound Leads", "type": "conversational", "voice": "alloy", "created_on": "2026-01-15T10:30:00.000Z", "updated_on": "2026-03-20T14:20:00.000Z", "status": "active", "direction": "inbound", "more_information": "Prioritize callers who mention pricing or demo requests. Escalate to a human if the caller expresses frustration.", "urls": [ "https://docs.example.com/faq", "https://www.example.com/pricing" ], "inherited_prompt_id": 12, "config": { "background_noise": false, "volume": 0.8, "block_non_intelliquent_number": true }, "max_call_duration": 300, "notification_time": 60, "notification_message": "This call will end in 1 minute.", "org_unit_id": 1001, "knowledgebase_files": [ "product-catalog.pdf", "sales-playbook.docx" ], "knowledgebase_urls": [ "https://docs.example.com/guide", "https://www.example.com/faq" ] }, "request_id": "550e8400-e29b-41d4-a716-446655440000", "timestamp": "2026-01-20T12:34:56.789Z" }

Request

Responses