The method call_external creates a new call in your Basix PBX by calling a specified external address (PSTN number) and after answer, transferring he/she to a specified destination.

It will create a channel (originating leg) by calling the external number. Then, when the channel gets answered it will be connected to any destination reachable by the PBX (destination can be a PSTN number, a user, a group, an extension number, etc).

Method parameters

Parameter Name Description Allowed Values Default Value Optional
target external number to call as originating leg any PSTN number. You can specify a calling_number and/or end_user identity: instead of just a string you can pass a complex object with details. none no
destination destination to which originating leg will be connected to after answer any valid destination in your PBX. If destination is PSTN, same rules applies as for target concering calling_number and end_user identity none no

For the parameter target and in case destination is a PSTN number: instead of a simple string you can specify an object with additional details. So instead of just this:

{ "target": "0311112222", "destination": "0377778888" }

we can use something like this (adding optional parameters):

{ "target": { "called_number": "0311112222", "calling_number": "0506868001", "end_user": { "id": 12345678, "name": "Olive", "organization": "Thimble Theatre", "avatar": "https://gravatar/jo9j9sdj93j9j9jw9j39wj39.jpg" } }, "destination": { "called_number": "0377778888", "calling_number": "0506868002", "end_user": { "id": 11223344, "name": "Popeye", "organization": "Thimble Theatre", "avatar": "https://gravatar/3osdj93j9jw3j9j93w939w5.jpg" } } }

Note that this is just a more detailed format of the destination parameter. You don't have to use all of sub-parameters shown. You just add the ones you need. If you don't need anything then just use "destination": "0377778888"

The end_user information will be relayed in WebSocket CTI notifications so it can be rendered by web apps.


Response will return a json string with result_code=0 in case of success and a list containing one Channel UUID (for the leg generated to call the address) A non-zero result_code indicates an error and will be accompanied by a description of the error.

result_code Description
0 Success
500 Error. Details will be present in the json string.


When the hunt finishes, if specified, the callback_url will be called informing if call was successful or not.

Parameter Name Description
result_code see above
uuid uuid of the channel that answered the call.

Examples using curl

Example 1: Calling 0312341234 and connecting whoever answers with group "sales"

$ curl -u 'DOMAIN_NAME:API_TOKEN' -X POST -H 'Content-Type: application/json' -d '{"target": "0312341234", "destination": "sales"}'


Example 2: Calling some end_user called "luke.s" at 0312341234 and connecting whoever answers with user "helen"

$ curl -u 'DOMAIN_NAME:API_TOKEN' -X POST -H 'Content-Type: application/json' -d '{"target": {"end_user": {"name": "luke.s"}, "called_number": "0312341234"}, "destination": "helen"}'


Example 3: Calling 0901111222 using calling_number 05068601111 connecting whoever answers with group "campaign"

$ curl -u 'DOMAIN_NAME:API_TOKEN' -X POST -H 'Content-Type: application/json' -d '{"target": {"calling_number": "05068601111", "called_number": "09011112222"}, "destination": "campaign"}'


Example 4: Failed request due to channel limit

$ curl -u 'DOMAIN_NAME:API_TOKEN' -X POST -H 'Content-Type: application/json' -d '{"target": "090111122222", "destination": "campaign"}'