Configure FlexML Endpoint

Introduction

FlexML endpoints enable you to create powerful call flows using simple XML instructions. This guide walks you through:

1. Creating a FlexML endpoint
2. Assigning phone numbers
3. Building a sample voice app
4. Handling inbound calls
5. Making outbound calls

Key Concept

FlexML uses XML verbs like <Say> and <Record> that execute in sequence to control call flow.

1. Create Your FlexML Endpoint

Prerequisites

Before creating an FlexML endpoint, you need to have:

1. A CarrierX account. If you don't have one, sign up.
2. A rented phone number. If you don't have one, rent a phone number.

Step-by-Step Setup

1. Once you've loged in to your CarrierX account, select CONFIGURE

2. Navigate to Endpoints

3. Click Create New Endpoint

   

Configuration Options

1. Type in the Endpoint Name: This is the internal reference name

2. Check Provision Trunk Group: Required for call routing

   About Trunk Groups

   Trunks route calls by matching dialed numbers to assigned DIDs. Learn more or see the Core API docs.

3. Select Endpoint Type: Select FlexML

4. Click Create Endpoint

   

2. Assign Phone Numbers

Linking Numbers to Your Endpoint

As soon as you create a FlexML endpoint, you will see your endpoint details:

Now you can assign phone numbers to your endpoint. This allows you to receive inbound calls on the assigned numbers.

1. Go to CONFIGURE > Phone Numbers

2. Select an available number:

   

3. Scroll down to the bottom and click Edit

4. Choose your endpoint's trunk group from the Trunk Group SID dropdown. This is the trunk group we've provisioned earlier when creating our FlexML endpoint.

   

5. Click Save

success

You can assign multiple numbers to the same endpoint - callers can dial any assigned number to reach your endpoint.

3. Build a Voice Application

In this section, we will build a simple voice application with Python, Flask, and ngrok, which we will use for inbound and outbound calls. An application can be built using any language and tools you are familiar with.

Sample Python/Flask App

Start with a hello.py file inside your project directory. Create the following POST route, which returns FlexML.

from flask import Flask
app = Flask(__name__)

@app.route('/hello', methods=['POST'])
def hello():
    return '''
    <Response>
        <Say>Hello, thank you for calling.</Say>
    </Response>
    '''

Running Your App

1. Install Flask:

   Windows	MacOS/Linux
   pip install flask	pip3 install flask

2. Set the environment variable:

   Windows	MacOS/Linux
   set FLASK_APP=hello.py	export FLASK_APP=hello.py

3. Start the Flask server:

   Windows	MacOS/Linux
   python -m flask run	python3 -m flask run

   When Flask starts, it will display the following message in the terminal window:

   * Running on http://127.0.0.1:5000

   The port number may vary depending on your configuration. The default port is 5000.

4. Use a free tool called ngrok to expose our localhost application to the Internet. The service needs to be reachable on the public Internet so that your endpoint can access and load the FlexML instructions.

   Install ngrok and then run the command with the port number that your local server is running on. In this example, our server is running on port 5000.

   ngrok http 5000

5. When ngrok is run successfully, the following data will show in the terminal window. The URL in the red box is now accessible publicly on the Internet.

   

4. Configure Inbound Calls

Two Assignment Methods: handler URLs can be assigned to a DID or to a FlexML endpoint.

Priority

DID-assigned URLs take precedence over endpoint URLs if both are set.

Option A: Assign URL to a Phone Number

First, we will learn how to add the handler URL to the DID associated with the FlexML endpoint trunk group.

When inbound calls are made to the DID, a request to the URL will be triggered. In our example, when individuals call the DID, they will hear the message nested inside the Say verb.

1. Navigate to CONFIGURE > Phone Numbers

2. Select a phone number associated with the FlexML endpoint trunk group

3. Navigate to Application: FlexML tab, click Edit

4. Enter your ngrok URL and click Save

   

Option B: Assign URL to an Endpoint

Now, we will learn how to assign a handler URL to the FlexML endpoint. This URL will be used by default for all calls to this endpoint if no URL is configured for the phone number.

1. Navigate to CONFIGURE > Endpoints

2. Select the FlexML endpoint that you would like to associate your link with

3. Navigate to Application: FlexML tab, click Edit

4. Set the Default URL and click Save

   

Inbound Call Flow

When a caller dials the DID, the call is routed the FlexML endpoint through the corresponding trunk group. The endpoint then sends a POST or GET request to the URL hosting the FlexML application. Based on the instructions provided in the application, the call is processed accordingly.

5. Make Outbound Calls

Make Outbound Calls via the Portal

First, let's make an outbound call via the Portal.

1. Navigate to CONFIGURE > Endpoints

2. Select the FlexML endpoint that you would like to make the outbound calls with

3. In the configuration window, scroll down to the Place Call section

4. Fill in the corresponding fields and in the Method field select POST

5. Click Place Call

   

Make Outbound Calls via the API

Before making a request, we need to find our credentials for the FlexML endpoint we would like to create the outbound call from.

API Credentials

1. Navigate to CONFIGURE > Endpoints

2. Find your endpoint's unique credentials:

   

3. Form a POST request with at least calling_did and called_did passed in the request body.

   We are also passing a value containing the URL for the simple FlexML voice application we created. If we do not pass a url field and value, the url will default to the one set on the DID. This is useful if you do not want to set the url each time in the FlexML instructions. Refer to the DIDs section in the FlexML API Reference for information on how to set the URL on the DID object.

   When called_did answers, a request will be made to the FlexML URL. In this example, the called party will hear the message that we configured in Step 3. Build a Voice Application section.

   Since no delay field or value is set, the call is placed immediately.

cURL Example

curl -X POST \
'https://api.carrierx.com/flexml/v1/calls' \
-H 'Content-Type: application/json' \
--data-binary '{"calling_did":"13098029080", "called_did":"12094408040", "url":"https://4146-188-2-25-253.ngrok-free.app/hello"}' \
-u '[your_flexml_endpoint_username]:[your_flexml_endpoint_password]'

Response Example

{
    "account_sid": "99844092-3fe2-4d94-b9b4-318fdf4255ce",
    "attributes": {},
    "call_sid": "52aa2963-be4d-4186-b344-7afa68969c3c",
    "called_did": "12094408040",
    "calling_did": "13098029080",
    "delay": 0,
    "date_created": "2025-05-15T20:24:15.736Z",
    "flexml": null,
    "method": "POST",
    "status": "created",
    "status_callback_method": "POST",
    "status_callback_url": null,
    "url": "https://4146-188-2-25-253.ngrok-free.app/hello"
}

Note

A successful API response doesn't guarantee call completion. Verify your account has outbound calling enabled.

Outbound Call Flow

The FlexML application hosted on some URL is making an outbound call. This time the call is routed via the FlexML endpoint through the corresponding trunk group and your rented DID to a regular phone (landline or mobile).

5. Next Steps

1. Explore the FlexML API Reference.
2. Try building more complex call flows with additional verbs.