> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kejue.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Persona Call

> Create a call with the full persona configuration pre-loaded.

Applies the complete settings hierarchy:
**System Defaults → Workspace → Persona → API Overrides**

All persona tools (in-call and post-call), tags, scoring criteria,
structured data extraction, call windows, retry schedules, and webhooks
are inherited automatically. Optional ``config`` overrides are applied
on top as the highest priority.



## OpenAPI

````yaml /openapi.json post /persona-calls
openapi: 3.1.0
info:
  title: Kejue Public API
  description: >-
    The Kejue Public API lets you programmatically create calls, manage
    campaigns, and retrieve call results.


    ## Authentication


    All requests require an API key passed in the `X-API-Key` header:


    ```

    X-API-Key: kej_live_...

    ```


    API keys are scoped to a workspace. Create and manage keys from the Kejue
    dashboard under **Settings → API Keys**.


    ## Base URL


    ```

    https://api.kejue.co/api/v1

    ```


    ## Rate Limits


    API requests are rate-limited per workspace. If you exceed the limit you'll
    receive a `429 Too Many Requests` response.


    ## Errors


    All error responses follow a consistent format:


    ```json

    {
      "error": "Human-readable message",
      "code": "ERROR_CODE",
      "details": {}
    }

    ```
  version: 1.0.0
servers:
  - url: https://api.kejue.co/api/v1
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Agents
    description: >-
      Create and manage AI agents (personas). Each agent has a name, prompt,
      voice configuration, and optional tools. Agents are the core building
      block — attach voice configs, tools, and use them to make calls.
  - name: Calls
    description: >-
      Create outbound calls, retrieve call details and transcripts, and list
      calls with filtering. Each call is associated with a contact and
      optionally an agent and campaign.
  - name: Persona Calls
    description: >-
      Create calls with the full agent configuration pre-loaded. Applies the
      complete settings hierarchy (workspace → agent → campaign → overrides)
      with all agent tools, tags, scoring, and webhooks inherited automatically.
  - name: Contacts
    description: >-
      Create and manage contacts. Contacts represent the people your agents
      call. Each contact has a phone number, name, and optional metadata.
      Supports single creation, bulk import, and CSV upload.
  - name: Campaigns
    description: >-
      Create and manage calling campaigns. Campaigns let you batch-call a list
      of contacts with shared settings, scheduling, and retry logic.
  - name: Tools
    description: >-
      Create and manage custom HTTP tools that agents can invoke during calls.
      Tools let agents fetch data, trigger actions, or integrate with external
      systems mid-conversation.


      Each tool supports three parameter types:

      - **Dynamic parameters** — filled by the AI at runtime (visible to the AI)

      - **Static parameters** — fixed values sent with every invocation (hidden
      from the AI)

      - **System parameters** — values injected from the execution context at
      runtime, such as `call_id`, `contact_id`, or `workspace_id` (hidden from
      the AI)
  - name: Voices
    description: List available voices for use in agent voice configurations.
  - name: Phone Numbers
    description: List phone numbers available in your workspace for making outbound calls.
  - name: Webhooks
    description: >-
      Create and manage webhook subscriptions. Receive real-time notifications
      for call events (started, ended, etc.) at your specified URL.
  - name: Models
    description: List available AI models for use in agent voice configurations.
paths:
  /persona-calls:
    post:
      tags:
        - Persona Calls
      summary: Create Persona Call
      description: |-
        Create a call with the full persona configuration pre-loaded.

        Applies the complete settings hierarchy:
        **System Defaults → Workspace → Persona → API Overrides**

        All persona tools (in-call and post-call), tags, scoring criteria,
        structured data extraction, call windows, retry schedules, and webhooks
        are inherited automatically. Optional ``config`` overrides are applied
        on top as the highest priority.
      operationId: create_persona_call_persona_calls_post
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePersonaCall'
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCallResponse'
        '400':
          description: >-
            The persona, agent, or phone number is in an inactive state, or the
            phone number is invalid.
          content:
            application/json:
              example:
                error: Persona is not active
                code: BAD_REQUEST
                details: {}
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: >-
            Missing or invalid API key. Pass a workspace API key in the
            `X-API-Key` header.
          content:
            application/json:
              example:
                error: Invalid or missing API key
                code: UNAUTHORIZED
                details: {}
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Persona not found in this workspace.
          content:
            application/json:
              example:
                error: Persona not found
                code: NOT_FOUND
                details:
                  persona_id: non_existent_id
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Request body or query parameters failed validation.
          content:
            application/json:
              example:
                error: Validation failed
                code: VALIDATION_ERROR
                details:
                  errors:
                    - field: body.name
                      message: Field required
                      type: missing
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    CreatePersonaCall:
      properties:
        contact_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Contact Id
          description: Existing contact ID
        contact:
          anyOf:
            - $ref: '#/components/schemas/ContactInput'
            - type: 'null'
          description: New contact to create inline
        persona_id:
          type: string
          title: Persona Id
          description: Persona to use
        agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Id
          description: Voice agent ID
        phone_number_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Phone Number Id
          description: Pin a specific origin phone number
        schedule_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Schedule At
          description: Schedule for later
        priority:
          type: integer
          maximum: 100
          minimum: 0
          title: Priority
          description: Queue priority
          default: 50
        config:
          anyOf:
            - $ref: '#/components/schemas/CallConfig'
            - type: 'null'
          description: Overrides on top of settings hierarchy
        external_reference:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          title: External Reference
          description: External tracking ID
        context:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Context
          description: Template variables
      type: object
      required:
        - persona_id
      title: CreatePersonaCall
      description: >-
        Persona call creation — requires persona_id, inherits full settings
        hierarchy.
    CreateCallResponse:
      properties:
        id:
          type: string
          title: Id
          description: Call ID
        contact_id:
          type: string
          title: Contact Id
          description: Contact ID
        status:
          type: string
          title: Status
        scheduled_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Scheduled At
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
        - id
        - contact_id
        - status
        - created_at
      title: CreateCallResponse
      description: Response after creating a call via public API.
    ErrorResponse:
      properties:
        error:
          type: string
          title: Error
        code:
          type: string
          title: Code
        details:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Details
      type: object
      required:
        - error
        - code
      title: ErrorResponse
      description: Standard error response.
      example:
        code: NOT_FOUND
        details:
          contact_id: '123'
        error: Contact not found
    ContactInput:
      properties:
        phone:
          type: string
          title: Phone
          description: Phone number (E.164 recommended)
        whatsapp_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Whatsapp Number
          description: WhatsApp number (E.164)
        email:
          anyOf:
            - type: string
            - type: 'null'
          title: Email
          description: Email address
        first_name:
          anyOf:
            - type: string
            - type: 'null'
          title: First Name
          description: First name
        last_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Name
          description: Last name
        company:
          anyOf:
            - type: string
            - type: 'null'
          title: Company
          description: Company name
        job_title:
          anyOf:
            - type: string
            - type: 'null'
          title: Job Title
          description: Job title
        country:
          anyOf:
            - type: string
            - type: 'null'
          title: Country
          description: ISO country code (auto-deduced from phone if omitted)
        timezone:
          anyOf:
            - type: string
            - type: 'null'
          title: Timezone
          description: IANA timezone (auto-deduced from phone if omitted)
        language:
          anyOf:
            - type: string
            - type: 'null'
          title: Language
          description: Language code (auto-deduced from phone if omitted)
        tags:
          items:
            type: string
          type: array
          title: Tags
          description: Tags for the contact
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
          description: Custom key-value metadata
      type: object
      required:
        - phone
      title: ContactInput
      description: Inline contact creation for calls. Phone is required.
    CallConfig:
      properties:
        prompt:
          anyOf:
            - type: string
            - type: 'null'
          title: Prompt
          description: System prompt
        first_message:
          anyOf:
            - type: string
            - type: 'null'
          title: First Message
          description: Agent's opening message
        first_message_uninterruptible:
          anyOf:
            - type: boolean
            - type: 'null'
          title: First Message Uninterruptible
          description: Prevent interrupting first message
        first_speaker:
          anyOf:
            - $ref: '#/components/schemas/FirstSpeaker'
            - type: 'null'
          description: Who speaks first
        voice_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Voice Id
          description: Voice ID
        model:
          anyOf:
            - $ref: '#/components/schemas/Model'
            - type: 'null'
          description: Voice AI model
        temperature:
          anyOf:
            - type: number
              maximum: 2
              minimum: 0
            - type: 'null'
          title: Temperature
          description: Model temperature
        max_duration:
          anyOf:
            - type: integer
              maximum: 7200
              minimum: 30
            - type: 'null'
          title: Max Duration
          description: Max call duration in seconds
        silence_timeout:
          anyOf:
            - type: integer
              maximum: 120
              minimum: 5
            - type: 'null'
          title: Silence Timeout
          description: Silence timeout in seconds
        recording_enabled:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Recording Enabled
          description: Record the call
        language_locale:
          anyOf:
            - type: string
            - type: 'null'
          title: Language Locale
          description: BCP-47 locale
        inactivity_messages:
          anyOf:
            - items:
                $ref: '#/components/schemas/InactivityMessage'
              type: array
            - type: 'null'
          title: Inactivity Messages
          description: Messages after periods of user silence
        call_start_hour:
          anyOf:
            - type: integer
              maximum: 23
              minimum: 0
            - type: 'null'
          title: Call Start Hour
        call_start_minute:
          anyOf:
            - type: integer
              maximum: 59
              minimum: 0
            - type: 'null'
          title: Call Start Minute
        call_end_hour:
          anyOf:
            - type: integer
              maximum: 23
              minimum: 0
            - type: 'null'
          title: Call End Hour
        call_end_minute:
          anyOf:
            - type: integer
              maximum: 59
              minimum: 0
            - type: 'null'
          title: Call End Minute
        allowed_days:
          anyOf:
            - items:
                type: integer
              type: array
            - type: 'null'
          title: Allowed Days
          description: 0=Monday, 6=Sunday
        auto_retry:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Auto Retry
        retry_schedule:
          anyOf:
            - items:
                type: integer
              type: array
            - type: 'null'
          title: Retry Schedule
          description: Minutes between retries
        phone_assignment_mode:
          anyOf:
            - $ref: '#/components/schemas/PhoneAssignmentMode'
            - type: 'null'
          description: How to assign origin phone
        scoring_criteria:
          anyOf:
            - type: string
            - type: 'null'
          title: Scoring Criteria
          description: LLM scoring instructions
        tools:
          anyOf:
            - items:
                anyOf:
                  - $ref: '#/components/schemas/ToolRef'
                  - $ref: '#/components/schemas/InlineTool'
              type: array
            - type: 'null'
          title: Tools
          description: Tools for the call (ToolRef or InlineTool)
        tags:
          anyOf:
            - items:
                $ref: '#/components/schemas/TagDefinition'
              type: array
            - type: 'null'
          title: Tags
          description: Tag definitions
        structured_data_schema:
          anyOf:
            - items:
                $ref: '#/components/schemas/StructuredDataField'
              type: array
            - type: 'null'
          title: Structured Data Schema
          description: Fields to extract from conversation
        server_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Server Url
          description: URL to POST call events to
        server_secret:
          anyOf:
            - type: string
            - type: 'null'
          title: Server Secret
          description: HMAC-SHA256 signing secret
        webhooks:
          anyOf:
            - items:
                $ref: '#/components/schemas/InlineWebhook'
              type: array
            - type: 'null'
          title: Webhooks
          description: Inline webhook definitions
        webhook_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Webhook Ids
          description: Existing webhook subscription IDs to attach
      type: object
      title: CallConfig
      description: Per-call configuration. All fields optional — null = use defaults.
    FirstSpeaker:
      type: string
      enum:
        - agent
        - user
      title: FirstSpeaker
      description: Who speaks first in the call.
    Model:
      type: string
      enum:
        - KJUE-v0
        - KJUE-v0-mini
        - KJUE-v0-large
        - KJUE-v1.0
      title: Model
      description: Available voice AI models.
    InactivityMessage:
      properties:
        message:
          type: string
          title: Message
          description: Text the agent will speak after the delay
        delay_seconds:
          type: integer
          maximum: 120
          minimum: 1
          title: Delay Seconds
          description: Seconds of silence before sending this message
        end_behavior:
          anyOf:
            - type: string
            - type: 'null'
          title: End Behavior
          description: >-
            What to do after speaking this message. One of
            END_BEHAVIOR_UNSPECIFIED, END_BEHAVIOR_HANG_UP_SOFT,
            END_BEHAVIOR_HANG_UP_STRICT. Maps to Ultravox endBehavior.
      type: object
      required:
        - message
        - delay_seconds
      title: InactivityMessage
      description: A message the agent sends after a period of silence from the user.
      example:
        delay_seconds: 15
        end_behavior: END_BEHAVIOR_UNSPECIFIED
        message: Are you still there?
    PhoneAssignmentMode:
      type: string
      enum:
        - local
        - foreign
        - any
      title: PhoneAssignmentMode
      description: How to assign the origin phone number.
    ToolRef:
      properties:
        id:
          type: string
          title: Id
          description: Tool ID (from GET /tools) or builtin name
        config:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Config
          description: Tool-specific config overrides
      type: object
      required:
        - id
      title: ToolRef
      description: Reference to an existing tool by ID or registry name.
    InlineTool:
      properties:
        name:
          type: string
          title: Name
          description: Tool name (shown to the AI)
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: What the tool does
        tool_type:
          type: string
          const: http
          title: Tool Type
          description: Tool type
          default: http
        http_config:
          $ref: '#/components/schemas/HttpToolConfig'
          description: HTTP endpoint configuration
        parameters:
          anyOf:
            - items:
                $ref: '#/components/schemas/ToolParameter'
              type: array
            - type: 'null'
          title: Parameters
          description: Parameters the AI can pass when invoking the tool
      type: object
      required:
        - name
        - http_config
      title: InlineTool
      description: A fully-defined tool passed inline with the call request.
    TagDefinition:
      properties:
        name:
          type: string
          title: Name
          description: Tag label, e.g. 'Interested'
        description:
          type: string
          title: Description
          description: When to apply this tag -- the AI uses this to decide
      type: object
      required:
        - name
        - description
      title: TagDefinition
      description: A tag that can be applied to a call based on conversation content.
    StructuredDataField:
      properties:
        key:
          type: string
          title: Key
          description: Output field key, e.g. 'budget'
        description:
          type: string
          title: Description
          description: What to extract from the conversation
      type: object
      required:
        - key
        - description
      title: StructuredDataField
      description: A field to extract from the conversation after the call.
    InlineWebhook:
      properties:
        url:
          type: string
          title: Url
          description: URL to POST events to
        events:
          anyOf:
            - items:
                $ref: '#/components/schemas/WebhookEvent'
              type: array
            - type: 'null'
          title: Events
          description: Which events to send. Defaults to all call events.
        signing_method:
          $ref: '#/components/schemas/SigningMethod'
          description: How to sign the payload
          default: hmac_sha256
        secret:
          anyOf:
            - type: string
            - type: 'null'
          title: Secret
          description: Signing secret. Required unless signing_method is 'none'.
      type: object
      required:
        - url
      title: InlineWebhook
      description: A fully-defined webhook passed inline with the call request.
    HttpToolConfig:
      properties:
        url:
          type: string
          title: Url
          description: URL to call when the tool is invoked
        method:
          $ref: '#/components/schemas/HttpMethod'
          description: HTTP method
          default: POST
        headers:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Headers
          description: Static headers
        auth_type:
          $ref: '#/components/schemas/AuthType'
          description: Authentication method
          default: none
        auth_config:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Auth Config
          description: Auth credentials
        timeout_ms:
          type: integer
          maximum: 60000
          minimum: 1000
          title: Timeout Ms
          description: Request timeout in milliseconds
          default: 30000
        static_parameters:
          anyOf:
            - items:
                $ref: '#/components/schemas/StaticToolParameter'
              type: array
            - type: 'null'
          title: Static Parameters
          description: Fixed parameters sent with every invocation
      type: object
      required:
        - url
      title: HttpToolConfig
      description: HTTP configuration for an inline tool.
    ToolParameter:
      properties:
        name:
          type: string
          title: Name
          description: Parameter name
        type:
          $ref: '#/components/schemas/ParameterType'
          description: Parameter data type
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: What this parameter is for
        required:
          type: boolean
          title: Required
          description: Whether this parameter is required
          default: false
        default:
          anyOf:
            - {}
            - type: 'null'
          title: Default
          description: Default value if not provided
        enum:
          anyOf:
            - items: {}
              type: array
            - type: 'null'
          title: Enum
          description: Allowed values
      type: object
      required:
        - name
        - type
      title: ToolParameter
      description: A parameter the AI agent provides at runtime.
    WebhookEvent:
      type: string
      enum:
        - call.started
        - call.ended
        - call.analyzed
        - campaign.started
        - campaign.ended
        - campaign.paused
        - campaign.resumed
        - campaign.failed
        - '*'
      title: WebhookEvent
      description: Webhook event types.
    SigningMethod:
      type: string
      enum:
        - hmac_sha256
        - hmac_sha1
        - bearer
        - basic_auth
        - none
      title: SigningMethod
      description: Webhook signing methods.
    HttpMethod:
      type: string
      enum:
        - GET
        - POST
        - PUT
        - PATCH
        - DELETE
      title: HttpMethod
      description: HTTP methods for tool requests.
    AuthType:
      type: string
      enum:
        - none
        - basic
        - bearer
        - api_key
      title: AuthType
      description: Authentication types for HTTP tools.
    StaticToolParameter:
      properties:
        name:
          type: string
          title: Name
          description: Parameter name
        value:
          type: string
          title: Value
          description: Static value. Supports {workspace_id} substitution.
        location:
          $ref: '#/components/schemas/ParameterLocation'
          description: 'Where to send: body, query, path, header'
          default: body
      type: object
      required:
        - name
        - value
      title: StaticToolParameter
      description: A fixed parameter sent with every tool invocation (hidden from the AI).
    ParameterType:
      type: string
      enum:
        - string
        - number
        - integer
        - boolean
        - object
        - array
      title: ParameterType
      description: Data types for tool parameters.
    ParameterLocation:
      type: string
      enum:
        - body
        - query
        - path
        - header
      title: ParameterLocation
      description: Where to send a parameter in an HTTP request.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Workspace API key (e.g. `kej_live_...`)

````