> For the complete documentation index, see [llms.txt](https://docs.ixhello.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ixhello.com/ixhc2/integrations/executing-flow-via-api-headless-execution/outbound-calling-api.md).

# Outbound Calling API

### Overview 

The Outbound Calling API allows the platform to initiate outbound voice calls via API and execute conversational flows during the call. It supports integrations with telephony systems such as PSTN and SIP. 

### Key Benefits 

* Proactive Engagement: Enables outbound campaigns, alerts, and notifications 
* Automation: Supports automated voice-based workflows and testing 
* Interoperability: Integrates with external telephony systems (e.g., SIP, Genesys) 

### Core Capabilities 

* Initiate outbound calls programmatically 
* Execute flows during the call lifecycle 
* Support multiple execution modes 
* Detect call-answer types (live vs machine) 

### API Capabilities 

### Call Initiation 

* Requires:  
  * Organization ID 
  * Flow ID 
  * Destination (PSTN or SIP) 

### Execution Modes 

| Mode        | Description                                         |
| ----------- | --------------------------------------------------- |
| Synchronous | Waits for call completion (limited to \~30 seconds) |
| Polling     | Returns immediately; status fetched via API         |
| Webhook     | Asynchronous updates sent via webhook               |

1. **Synchronous (Blocking)** 

The HTTP connection is held open until the call reaches a terminal state (or the 30-second timeout). The full outcome is returned in the response body. 

Best for: Very short flows that complete within 30 seconds. Use poll or webhook mode for longer calls. 

2. **Polling (Async)** 

Returns immediately with a session identifier and Queued status. The caller then polls GET .../calls/:sessionId at its own pace to check progress. 

Best for: Backends that cannot hold connections open, or that want fine-grained status tracking without exposing a public endpoint. 

3. **Webhook (Event-Driven)** 

Returns immediately with a session identifier. The platform POSTs to your webhookUrl at each lifecycle event: 

* When the call is answered (with AMD result if requested) 
* When it fails before answer 
* When it reaches a final state 

Delivery is best-effort — failed deliveries are logged and not retried in the initial implementation. 

Best for: Production event-driven integrations that need to react to call outcomes without polling. 

#### Call Analysis (Answering Machine Detection) 

* Detects:  
  * Live person 
  * Answering machine 
  * Fax / unknown 
* Flow execution can be condition-based (e.g., execute only for live answers) 
  * Uses AI to detect destination type 

#### Advanced Use Cases 

* Automated Testing: Trigger flows across environments (e.g., QA → Prod) 
* Back-to-back testing: Use flows to test other flows via voice calls 
* Cross-platform calling: Call external providers (e.g., Twilio, Genesys) 

Notes / Limitations 

* No persistence beyond call completion 
* Post-call data only available via reporting 
* No scheduling (calls executed immediately) 
* Semantic call analysis (AI-based detection) is future work 


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.ixhello.com/ixhc2/integrations/executing-flow-via-api-headless-execution/outbound-calling-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.