Platform Overview

FreeClimb is a cloud-based application programming interface (API) that puts the power of the Vail platform in your hands. FreeClimb simplifies the process of creating applications that can use a full range of telephony features without requiring specialized or on-site telephony equipment.

FreeClimb gives application developers access to features including:

FreeClimb Applications

Before you can take advantage of FreeClimb, you’ll create an Application using the Dashboard.

An Application is a set of URLs, along with configuration data, that uses FreeClimb’s RESTful API or PerCL resource (Performance Command Language) to tell FreeClimb what to do. The Applications resource represents all of the applications affiliated with a single FreeClimb account.

How Applications Work

FreeClimb maintains constant interaction with your client applications using HTTP. From the perspective of the client application, FreeClimb looks like a browser when it makes requests.

There are two modes of operation on FreeClimb's platform:

Application-initiated actions using the RESTful API
Actions using PerCL that are in response to external events

Application-Initiated Actions Using the RESTful API

The client application (or the end user) can explicitly initiate an action, such as issuing an HTTP request using a command-line interface. FreeClimb authenticates the request using basic authentication over HTTPS before processing the request.

If a synchronous request is made, then FreeClimb fully processes the request and returns a response to the client application. If the request is asynchronous, it is added to a job queue and FreeClimb will return a response code. Potential response codes include:

202 ACCEPTED (FreeClimb was able to add the request to the job queue)
500 INTERNAL SERVER ERROR (FreeClimb was unable to add the request to the job queue)

The status codes indicate whether FreeClimb has acknowledged the request, but do not indicate that FreeClimb completed the task.

The FreeClimb Dashboard is an example of an application using the RESTful API to initiate actions using FreeClimb's platform. The features correspond to REST API counterparts. This means that the sequence of actions a customer takes to purchase an incoming phone number via the Dashboard results in the same under the hood behavior as the sequence of actions required when making HTTP POST calls to the API’s AvailablePhoneNumbers resource to provision an incoming phone number.

See the RESTful API Reference documentation for more details on communicating with FreeClimb via API.

Actions Using PerCL in Response to External Events

FreeClimb can respond to external events that were not triggered by the client application or the end user. FreeClimb’s responses are sent to the client application using the HTTP protocol in the form of a POST request.

The client application, in response to FreeClimb’s request, can provide a response that contains the call control logic written as commands. These commands use the Performance Command Language (PerCL).

FreeClimb defines the execution points during the call. These execution points include, but aren't limited to:

Inbound call received from the Public Switched Telephone Network (PSTN)
End of digit collection from the caller
Completion of message recording

For these events, FreeClimb describes the data that is included in the HTTP POST request to the client.

For information on using Performance Command Language commands to communicate with FreeClimb, see the PerCL Overview Reference.

Standard HTTP Requests to a FreeClimb Application

FreeClimb makes a synchronous HTTP Request to a FreeClimb application whenever an event, like receiving a call, occurs.

The application profile, RESTful API requests, and PerCL commands all contain URLs that communicate to FreeClimb where specific requests should be sent.

Application URLs can use either the HTTP or HTTPS protocols, but the request from FreeClimb to the application always uses the HTTP POST method.

The data that FreeClimb provides to the client application in the request includes the following standard request parameters that appear in the message body.

Parameter	Description
requestType	Context or reason why the request was made.
callId	Unique identifier for the Call.
accountId	ID associated with your account
from	Phone number of the party that initiated the Call. Uses the E.164 format (e.g., +13145551234).
to	Phone number to which the Call is directed. Uses the E.164 format.
callStatus	Descriptive status for the Call.
direction	Description for the direction of the Call (`inbound` for inbound calls, `outbound` for RESTful API-initiated calls, `outboundDial` for calls made using the `OutDial` PerCL command)
conferenceId	Populated if status is `bridged` or if request pertains to a Conference; otherwise, `conferenceId` is set to `null`.
queueId	Populated if status is `queued` or if the request pertains to a Queue; otherwise, `queueId` is set to `null`.

Resources

FreeClimb offers you access to resources, or telephonic functionalities, that help facilitate the development of your client applications. The resources you create are owned by your account and cannot be manipulated by any other accounts, regardless of method. Currently, FreeClimb offers the following resources: