Call Request

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/simple-ai/json-schema/simple-ai-call-request-schema.json",
  "title": "Call Request",
  "description": "Request to initiate an AI phone call",
  "x-generated": "2026-10-29",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/simple-ai-openapi.json#/components/schemas/CallRequest",
  "properties": {
    "to_number": {
      "type": "string",
      "title": "To Number",
      "description": "The phone number to call in E.164 format"
    },
    "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."
    },
    "record": {
      "type": "boolean",
      "title": "Record",
      "description": "Whether to record the call or not",
      "default": false
    },
    "language": {
      "type": "string",
      "title": "Language",
      "description": "Language code for the call, such as `en` or `es`. Defaults to the agent's language when `agent_id` is provided, otherwise `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"
    },
    "boost_keywords": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Boost Keywords",
      "description": "Keywords to emphasize during the conversation"
    },
    "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."
    },
    "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."
    },
    "params": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Params",
      "description": "Additional parameters to pass to the call. These will be substituted into the prompt for all keys with {{params.key}}"
    },
    "external_identifiers": {
      "anyOf": [
        {
          "additionalProperties": {
            "type": "string"
          },
          "type": "object"
        },
        {
          "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."
    },
    "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"
            ],
            "properties": {
              "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."
    },
    "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."
    }
  },
  "type": "object",
  "required": [
    "to_number"
  ],
  "oneOf": [
    {
      "required": [
        "prompt"
      ],
      "not": {
        "required": [
          "agent_id"
        ]
      }
    },
    {
      "required": [
        "agent_id"
      ],
      "not": {
        "anyOf": [
          {
            "required": [
              "prompt"
            ]
          },
          {
            "required": [
              "analyzers"
            ]
          }
        ]
      }
    }
  ]
}