> ## Documentation Index > Fetch the complete documentation index at: https://docs.usesimple.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create Call > Create a new call via the public API. Requires a valid API key. If `idempotency_key` is provided, duplicate requests with the same JSON body return the original response. Reusing the same `idempotency_key` with a different JSON body returns `409 Conflict`. The simplest way to use Simple AI is the create call endpoint. You can pass a prompt and tools inline to create a one-off call without setting up an agent first. If you need more control over the conversation flow, create a reusable [agent](/agents) and reference it by ID instead. ## OpenAPI ````yaml POST /calls openapi: 3.1.0 info: title: Public API v1 description: >- Public API v1 requiring API keys. **Timestamps:** All datetime fields in API responses are returned in UTC using ISO 8601 format (e.g., `2024-01-15T14:30:00Z`). When filtering by date parameters, provide timestamps in ISO 8601 format. version: 0.1.0 servers: - url: https://api.prod.usesimple.ai/api/v1 description: Production API Server security: [] paths: /calls: post: tags: - Calls summary: Create Call description: >- Create a new call via the public API. Requires a valid API key. If `idempotency_key` is provided, duplicate requests with the same JSON body return the original response. Reusing the same `idempotency_key` with a different JSON body returns `409 Conflict`. operationId: create_call_calls_post requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CallRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/CallResponse' '409': description: Idempotency Conflict content: application/json: schema: $ref: '#/components/schemas/CallCreateConflictResponse' examples: requestInProgress: summary: Request with this idempotency key is already in progress value: success: false errors: - idempotency_key request is already in progress requestBodyMismatch: summary: Idempotency key reused with a different request body value: success: false errors: - >- idempotency_key has already been used with a different request body '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyHeader: [] components: schemas: CallRequest: properties: to_number: type: string title: To Number description: The phone number to call in E.164 format examples: - '+12345678900' from_number_id: type: string format: uuid title: Phone Number ID description: >- The UUID of the phone number to use for the outbound call. If not provided, a phone number will be automatically selected. examples: - 123e4567-e89b-12d3-a456-426614174000 record: type: boolean title: Record description: Whether to record the call or not default: false language: $ref: '#/components/schemas/LanguageEnum' default: en prompt: anyOf: - type: string - type: 'null' title: Prompt description: >- The prompt to use for the AI call. Required if agent_id is not provided examples: - Hello, I'm calling to confirm your appointment boost_keywords: anyOf: - type: array items: type: string - type: 'null' title: Boost Keywords description: Keywords to emphasize during the conversation examples: - - appointment - schedule - morning agent_id: anyOf: - type: string format: uuid - type: 'null' title: Agent Id description: >- ID of the pre-configured agent to handle the call. Required if prompt is not provided. Cannot be used together with prompt or analyzers - use the agent's analyzers instead. examples: - 123e4567-e89b-12d3-a456-426614174000 version_id: anyOf: - type: string format: uuid - type: 'null' title: Version Id description: >- When using agent_id, specifies which agent version to use. If not provided, uses the most recently updated version. examples: - 456e7890-e89b-12d3-a456-426614174000 params: anyOf: - type: object additionalProperties: type: string - type: 'null' title: Params description: >- Additional parameters to pass to the call. These will be subtituted into the prompt for all keys with {{params.key}} examples: - appointment_type: morning customer_id: '123456' external_identifiers: anyOf: - type: object additionalProperties: type: string - type: 'null' title: External Identifiers description: >- External identifiers to associate with the call. These can be used to find the call later using the find_by_attribute endpoint. examples: - customer_id: CUST-123456 order_id: ORD-789012 analyzers: anyOf: - type: array title: Analyzers description: >- List of analyzers to run after the call. Can only be provided when agent_id is not provided. If using an agent, use the agent's analyzers instead. items: type: object required: - prompt - output_config - title properties: title: type: string title: Title description: The title of the analyzer prompt: type: string title: Prompt description: The prompt to use for analysis output_config: type: object title: Output Config description: Configuration for the expected output format required: - type properties: type: type: string enum: - string - boolean - datetime - object description: The type of output expected properties: type: object description: >- Required when type is 'object'. Defines the structure of the object additionalProperties: type: object required: - type properties: type: type: string enum: - string - boolean - datetime - type: 'null' default: null voice_id: anyOf: - type: string format: uuid - type: 'null' title: Voice Id description: >- The UUID of the voice to use for this call. Overrides the agent's default voice when provided. examples: - 789e0123-e89b-12d3-a456-426614174000 idempotency_key: anyOf: - type: string - type: 'null' title: Idempotency Key description: >- Optional idempotency key for safe retries. Reusing the same key with the same JSON request body returns the original call response; reusing it with a different body returns 409 conflict. examples: - call-create-2026-03-04-0001 type: object required: - to_number title: Call Request description: Request to initiate an AI phone call oneOf: - required: - prompt not: required: - agent_id - required: - agent_id not: anyOf: - required: - prompt - required: - analyzers CallResponse: properties: success: type: boolean title: Success status: type: string title: Status uuid: type: string title: Uuid record: type: boolean title: Record language: type: string enum: - en - es - ar title: Language answered_by: $ref: '#/components/schemas/AnsweredByEnum' analyzers: type: array title: Analyzers description: List of analyzers configured for this call items: $ref: '#/components/schemas/AnalyzerResponse' analysis_results: type: array title: Analysis Results description: Results from analyzers that have completed items: $ref: '#/components/schemas/AnalysisResultResponse' type: object required: - success - status - uuid - language title: CallResponse CallCreateConflictResponse: properties: success: type: boolean title: Success errors: items: type: string type: array title: Errors type: object required: - success - errors title: CallCreateConflictResponse HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError LanguageEnum: type: string enum: - en - es - ar title: Language description: The language to use for the call - English (en) or Spanish (es) AnsweredByEnum: type: string enum: - voicemail - human - no_answer - unknown title: Answered By description: >- Indicates how the call was answered - by a human, voicemail, or if there was no answer AnalyzerResponse: type: object properties: id: type: string format: uuid title: Id description: Unique identifier for the analyzer prompt: type: string title: Prompt description: The prompt used for analysis output_config: type: object title: Output Config description: Configuration for the expected output format properties: type: type: string enum: - string - boolean - datetime - object description: The type of output expected properties: type: object description: >- Required when type is 'object'. Defines the structure of the object additionalProperties: type: object properties: type: type: string enum: - string - boolean - datetime required: - id - prompt - output_config title: AnalyzerResponse AnalysisResultResponse: type: object properties: id: type: string format: uuid title: Id description: Unique identifier for the analysis result analyzer_id: type: string format: uuid title: Analyzer Id description: Identifier of the analyzer that produced this result prompt: type: string title: Prompt description: The prompt used for analysis output_config: type: object title: Output Config description: Configuration for the expected output format result: type: object title: Result description: The analysis result, structure depends on the output_config required: - id - analyzer_id - prompt - output_config - result title: AnalysisResultResponse ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError securitySchemes: APIKeyHeader: type: apiKey in: header name: Authorization ````