Q: How do you create a new FreeClimb application via the API?
A: Send a POST request to /Accounts/{accountId}/Applications containing JSON parameters such as alias, voiceUrl, voiceFallbackUrl, callConnectUrl, and smsUrl.
Q: How do you retrieve a list of all applications under a FreeClimb account?
A: Send a GET request to /Accounts/{accountId}/Applications. You can supply optional query parameters like alias to filter the returned list of application resources.
Q: How do you fetch configuration details for a single FreeClimb application?
A: Send a GET request to /Accounts/{accountId}/Applications/{applicationId} using the target Application ID.
Q: How do you update an existing FreeClimb application configuration?
A: Send a POST request to /Accounts/{accountId}/Applications/{applicationId} with the JSON payload specifying updated endpoint URLs or application aliases.
Q: How do you delete an application in FreeClimb?
A: Send a DELETE request to /Accounts/{accountId}/Applications/{applicationId} using the specific Application ID to permanently remove the resource.
An Application in FreeClimb is just a set of configuration data and URLs that FreeClimb invokes to notify the app of an event or to retrieve instructions on how to behave in response to an event, such as when one of the phone numbers associated with the Application receives a Call.
Overview
Applications are useful for encapsulating configuration information that we need to distribute across multiple phone numbers. Any number of phone numbers can point to a single Application so that they share a common set of properties and URLs. This makes it possible to change the configuration of a large number of phone numbers by modifying a single Application instance. If we create an Application with its voiceUrl set to http://www.example.com/answer, we can assign that Application to all of our incoming phone numbers and FreeClimb will make a request to that URL whenever an inbound call arrives.
Likewise, when making outbound calls using the REST API, we can specify an applicationId to handle the outbound request and FreeClimb will make a request to the callConnectUrl of the Application. The callConnectUrl property is used instead of the voiceUrl property for outbound calls. The behavior of the callConnectUrl and voiceUrl are different because of the difference in ‘behavior’ when making an outbound call and answering an inbound call; the main difference being that an outbound call may not actually be connected (e.g. busy, no answer).
For incoming SMS messages, we can specify an smsUrl which FreeClimb will request when a number assigned to our Application receives an SMS message.
Resource properties
An Application resource is represented by the following properties:
| Property | Type | Description |
|---|---|---|
| uri | string | The URI for this resource, relative to /apiserver. |
| dateCreated | string date-time | The date that this account was created (GMT) in RFC 1123 format (e.g., Mon, 15 Jun 2009 20:45:30 GMT). |
| dateUpdated | string date-time | The date that this account was last updated (GMT) in RFC 1123 format (e.g., Mon, 15 Jun 2009 20:45:30 GMT). |
| dateCreatedISO | string date-time | Date that this resource was created (UTC) in RFC3339 format (e.g., 2024-10-09T15:05:03.358Z). |
| dateUpdatedISO | string date-time | Date that this resource was last updated (UTC) in RFC3339 format (e.g., 2024-10-09T15:05:03.358Z). |
| revision | integer | Revision count for the resource. This count is set to 1 on creation and is incremented every time it is updated. |
| applicationId | string | A string that uniquely identifies this Application resource. |
| accountId | string | ID of the account that created this Application. |
| alias | string | A description for this Application, up to 64 characters long. |
| voiceUrl | string | The URL FreeClimb will request when a phone number assigned to this Application receives a Call. Used for inbound calls only. |
| voiceFallbackUrl | string | The URL that FreeClimb will request if it times out or otherwise encounters an error (including response code >= 400) waiting for a response from the voiceUrl. Used for inbound calls only. |
| callConnectUrl | string | The URL to which FreeClimb will make a POST request informing the result of the outbound Call request. The status property of the request message specifies if the Call was connected or not. |
| statusCallbackUrl | string | A URL to which FreeClimb will make a POST request when the Call ends to notify this app. |
| smsUrl | string | The URL FreeClimb will request when a phone number assigned to this Application receives an incoming SMS message. Used for inbound SMS only. |
| smsFallbackUrl | string | The URL that FreeClimb will request if it times out waiting for a response from the smsUrl. Used for inbound SMS only. |