Nixflex - AI Voice Platform for Building AI Phone Agents

Create outbound call

curl --request POST \
  --url https://api.nixflex.com/v1/calls/outbound

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.nixflex.com/v1/calls/outbound",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.nixflex.com/v1/calls/outbound"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.nixflex.com/v1/calls/outbound")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

POST

calls

outbound

Create outbound call

curl --request POST \
  --url https://api.nixflex.com/v1/calls/outbound

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.nixflex.com/v1/calls/outbound",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.nixflex.com/v1/calls/outbound"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.nixflex.com/v1/calls/outbound")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

Triggers Nixflex to call a phone number. The agent dials, waits for pickup, runs voicemail detection, and starts the conversation when a human answers. The call is fire-and-forget: the request returns immediately with a call_id, then the actual ringing, conversation, and ending all happen asynchronously. If you want the result, set a webhook_url on the agent (or on the number) and you will receive a call.completed event when the call ends.

The number you dial from must be outbound-enabled. A number that only handles inbound calls will not place outbound calls. Enable outbound on the Phone Numbers page (or when you import the number). Inbound working does not mean outbound works â€” they are separate switches.

Request

curl -X POST https://api.nixflex.com/v1/calls/outbound \
  -H "Authorization: Bearer KEY_ID:KEY_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_125207e452f8714a",
    "to_number": "+447386172392",
    "prompt": "You are Sarah from Bright Smile Dental. Call to remind {patient_name} about their appointment on {appointment_time} and confirm they can still attend.",
    "dynamic_vars": {
      "patient_name": "Sarah",
      "appointment_time": "Tuesday at 2pm"
    }
  }'

Body parameters

Field	Type	Required	Notes
`agent_id`	string	Yes	The agent that will handle this call. Must belong to your API key.
`to_number`	string	Yes	Who to call, in E.164 format (`+447386172392`, not `07386172392`).
`prompt`	string	Yes	The call purpose â€” what the agent should say and why it is calling. Sent fresh per call, stored nowhere. This is separate from the agent’s own saved prompt and must not be empty.
`dynamic_vars`	object	No	Key-value pairs injected into the prompt (see below).
`from_number`	string	No	Which of your numbers to dial from. Must be an outbound-enabled number on this agent. If you omit it, the engine uses the agent’s first outbound-enabled number.
`campaign_id`	string	No	Link this call to a batch campaign for reporting.

The request body uses to_number (not to). Sending to will fail with missing_field. (to is used by the SMS endpoints, not by outbound calls.)

How the dialing number is chosen

You do not have to pass from_number. The engine works out which of your numbers to dial from in this order:

You passed from_number â†’ the engine uses exactly that number, but only if it is outbound-enabled and belongs to this agent under your API key. If it is not, you get from_number_not_found.
You omitted from_number â†’ the engine picks the agent’s first outbound-enabled number.
Legacy fallback â†’ if the agent has no rows in the phone numbers table, it falls back to the single number stored on the agent itself.

If none of these produce a usable number, you get agent_missing_phone_number.

Dynamic variables

Anything in dynamic_vars is interpolated into the prompt. Reference each value with curly braces:

You are calling {patient_name} about their appointment on {appointment_time}.

The engine replaces {patient_name} with "Sarah" before the agent speaks. If the prompt references a variable that is not in dynamic_vars, it is left as-is â€” the agent will see the literal {patient_name} text, so double-check your keys match.

Response

201 Created:

{
  "call_id": "CA1234567890",
  "status": "initiated",
  "to": "+447386172392",
  "from": "+447446466847"
}

The response returns immediately. Your carrier dials within about 5 seconds. The actual call lifecycle (ringing â†’ connected â†’ ended) happens asynchronously â€” you will receive a webhook when the call ends if you have a webhook_url set.

Validation order

The engine checks these in order and stops at the first failure:

agent_id, to_number, and prompt are all present (and prompt is not blank).
to_number is valid E.164 (e.g. +447386172392, not 07386172392).
The agent exists and belongs to your API key.
The agent has an outbound-enabled number assigned. Inbound-only numbers do not count. If you passed a specific from_number, it must be outbound-enabled on this agent.
Carrier credentials exist for that number.

Each failure returns a 400 with a specific code (see below).

Errors

Code	HTTP	Cause
`missing_field`	400	`agent_id`, `to_number`, or `prompt` is missing or empty
`invalid_phone_format`	400	`to_number` is not valid E.164
`from_number_not_found`	400	The `from_number` you passed is not an outbound-enabled number on this agent. Import it and enable outbound on the Phone Numbers page.
`agent_missing_phone_number`	400	The agent has no number assigned. Import one via Phone numbers and enable outbound.
`agent_missing_twilio_credentials`	400	The chosen number has no Twilio credentials stored
`outbound_failed`	502	Twilio rejected the dial (see `details.twilio_error`)

What happens next

After you trigger the call:

Your carrier dials the to_number using the chosen outbound number.
Voicemail detection runs - the AI reads the first thing it hears.
If voicemail is detected, the agent leaves a short message from your prompt and ends the call. See Voicemail detection.
If a human answers, the agent starts the conversation using your prompt.
The call ends naturally, or via [END_CALL], or on timeout.
The recording is saved and post-call analysis runs.
A call.completed webhook fires to your webhook_url if one is set.

See Outbound calls for the full conceptual overview.

​Request

​Body parameters

​How the dialing number is chosen

​Dynamic variables

​Response

​Validation order

​Errors

​What happens next

Request

Body parameters

How the dialing number is chosen

Dynamic variables

Response

Validation order

Errors

What happens next