Ringfree PBX API

The PBX API provides programmatic access to data and actions contained within Ringfree’s fork of FreePBX. Under normal circumstances, the API should always return a response containing the following structure:

  1. An HTTP status code such as 200, 204, 401, 404, etc.
  2. A human readable message such as “OK” or “Not found”.
  3. Whatever data is being returned from the API.

The API supports GET, POST, PUT, and DELETE messages and will return a 405 if the message type is not allowed for a route or a 501 if the message type is not yet implemented for that route.

Access to the API requires HTTP Basic authentication. There is a user and password configured within the API itself (usually api and a random password) and any administrator configured in FreePBX with the ALL SECTIONS permission can use the API.

Using This Documentation

There is a section for each major route with the route URL being the title of the section. Each section is broken down by request type with an example curl command. Example responses are not included in this documentation. Some routes may include an additional URI components at the end so please pay attention to the exact route.

Parameters (including GET query params) are not included in the example commands, but are rather listed with descriptions immediately following the example command. Sections of the example commands in all caps and surrounded by arrows are indented to be replaced with user-supplied data. These are documented along with the parameters except for <USER>, <PASS>, and <SUBDOMAIN> which should remain consistent throughout your use of the API.

It should be noted that the API is also installed on white-labeled PBXs. To access those, simply adjust the URI protocol, subdomain, top-level domain, and second-level domain as necessary.

 

/api/v1/test

GET:

Test route.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/test

POST:

Test route.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/test -X POST

PUT:

Test route.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/test -X PUT

DELETE:

Test route.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/test -X DELETE

 

/api/v1/ampusers

POST:

Creates a new ampuser within FreePBX.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/ampusers/add -X POST

  • username – Required – Alphanumeric but beginning with a letter.
  • password – Required – Any string.
  • sections – Required – JSON encoded string consisting of the permissions you’d like to enable for the user. You can check the database directly to get individual permission slugs. Most of them make sense but there are those such as “Add Extension” that present as “999”.

PUT:

Modifies the indicated ampuser within FreePBX.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/ampusers/<USERNAME> -X PUT

  • <USERNAME> – The username of the ampuser to modify.
  • password – Required – Any string.
  • sections – Required – As mentioned in the POST route parameters.

DELETE:

Deletes the indicated ampuser within FreePBX.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/ampusers/<USERNAME> -X DELETE

  • <USERNAME> – The username of the ampuser to delete.

 

/api/v1/announcements

GET:

Retrieves data on all announcements within the system.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/announcements

 

/api/v1/cache

POST:

Manages the cache. Currently only reloading of the extension cache has been implemented.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/cache/<CONTEXT> -X POST

  • context – Required  – The context from which to act. Acceptable values: extensions.
  • action – Required – The specific action to perform. Acceptable values: reload.

 

/api/v1/call

POST:

Initiates a call to the specified extension, then bridges that call to another placed to the specified destination.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/call -X POST

  • ext – Required – The extension you’d like to place the call from.
  • secret – Required – The SIP secret for the aforementioned extension.
  • dest – Required – The destination phone number.
  • autoanswer – Optional – Use any truthy value to attempt to automatically answer on supported extensions.

 

/api/v1/callflowcontrols

GET:

Retrieves data on all call flow control toggles within the system.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/callflowcontrols

 

/api/v1/cdr

GET:

Retrieves Asterisk CDR data

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/cdr

  • start – Optional – Unix timestamp beginning limit; Look no earlier than this time. Defaults to beginning of system.
  • end – Optional – Unix timestamp ending limit; Look no later than this time. Defaults to time of request.
  • src – Optional – Source endpoint, if looking for calls originating a particular endpoint. No default value.
  • dest – Optional – Destination endpoint, if looking for calls directed to a particular endpoint. No default value.
  • did – Optional – Limit calls to those containing this DID. No default value.
  • limit – Optional – Maximum number of records to return. Defaults to 1000.

 

/api/v1/coffee

GET:

RFC 2324 implementation.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/coffee

 

/api/v1/conferences

GET:

Retrieves data on all conferences within the system.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/conferences

 

/api/v1/did

POST:

Creates a new DID, or “Inbound Route”, within the system.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/did/add

  • did – Required – The DID to create. Generally speaking this will be an 11 digit NANP number.
  • destination – Optional – Where in the system the DID should be routed. The value here can be any FreePBX destination. The default value is app-blackhole,hangup,1 to terminate the call.
  • mohclass – Optional – The “music on hold” class to associated with the DID. This defaults to default.
  • description – Optional – The description to associate with the DID. If not specified, this will default to the DID itself.

DELETE:

Deletes a DID from the system.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/did/<DID> -X DELETE

  • <DID> – The DID to delete from the system. This has to be an exact match. For instance ten and eleven digit DIDs are not interchangeable.

 

/api/v1/dids

GET:

Retrieves a list of all DIDs, along with their information, within the system.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/dids

GET:

Retrieves the information about the specified DID from the system.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/dids/<DID>

  • <DID> – The DID about which to retrieve the information.

 

/api/v1/extdump

GET:

Outputs all information, excluding AstDB data, for all extensions in the system.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/extdump

GET:

Outputs all information, including AstDB data, for a single extension in the system.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/extdump/<EXTENSION>

  • <EXTENSION> – The extension for which to retrieve information.

 

/api/v1/extension

POST:

Create a new extension within the system.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/extension/add -X POST

  • extension – Required – The number of the extension you’d like to create.
  • exttype – Required – The extension type. Accepted values: sip, virtual.
  • displayname – Optional – A label to associated with the extension. Defaults to the extension number.
  • secret – Optional – The SIP secret, or password, used to authenticate the extension. This should always be included for SIP extensions but is unused for virtual extensions. Note that software exists which tries to brute force this. As such, this should be a long, random string.
  • outboundcid – Optional – An NANP DID to use for the caller ID when making outbound calls from this extension.
  • emergencycid – Optional – An NANP DID to use for the caller ID when making outbound calls to emergency services from this extension.
  • voicemail – Optional – Use any truthy value to enable voicemail for this extension.
  • email – Optional – Email address to be used for voicemail notification messages.
  • voicemailpassword – Optional – PIN the end user can use to access voicemail and the PBXUser interface.
  • followme – Optional – Use any truthy value to enable FollowMe for this extension.
  • followmegrptime – Optional – Amount of time in seconds to ring the extension before ringing the FollowMe group. Defaults to 20.
  • recInternalIn – Optional – How to address recording internal inbound calls. Accepted values: always, dontcare, never. Defaults to dontcare.
  • recInternalOut – Optional – How to address recording internal outbound calls. Accepted values: always, dontcare, never. Defaults to dontcare.
  • recExternalIn – Optional – How to address recording external inbound calls. Accepted values: always, dontcare, never. Defaults to dontcare.
  • recExternalOut – Optional – How to address recording external outbound calls. Accepted values: always, dontcare, never. Defaults to dontcare.
  • recOndemand – Optional – Whether on-demand recording should be enabled. Accepted values: enabled, disabled. Defaults to enabled.
  • recPriority – Optional – An integer from 0 to 20 indicating the priority to associate with recordings from this extension. Defaults to 10.

DELETE:

Deletes the specified extension from the system.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/extension/<EXTENSION> -X DELETE

  • <EXTENSION> – The extension you’d wish to delete.

 

/api/v1/extensions

GET:

Retrieves data for all extensions from the extensions cache. If the cache is empty or invalid, it reloads the cache prior to issuing a response.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/extensions

GET:

Retrieves data for a single extension from the extensions cache. If the cache is empty or invalid, it reloads the cache prior to issuing a response.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/extensions/<EXTENSION>

  • <EXTENSION> – The extension for which to retrieve data.

 

/api/v1/followme

GET:

Retrieves the FollowMe group list for the specified extension.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/followme/<EXTENSION>

  • <EXTENSION> – The extension for which to retrieve the group list.

GET:

Retrieve the FollowMe status for the specified extension.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/followme/<EXTENSION>/status

  • <EXTENSION> – The extension for which to retrieve the FollowMe status.

GET:

Return whether or not the specified entry is within the FollowMe group list.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/followme/<EXTENSION>/<ENTRY>

  • <EXTENSION> – The extension from which to check if the entry is within the FollowMe group list.
  • <ENTRY> – The entry to check for within the FollowMe group liist.

POST:

Performs an action on the FollowMe for the specified extension. With this you can add or remove numbers from the FollowMe group list or enable/disable the FollowMe functionality for the extension altogether.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/followme/<EXTENSION> -X POST

  • <EXTENSION> – The extension upon which to perform the action.
  • action – Required – The action to perform. Accepted values: addExternal, removeExternal, enable, disable.
  • number – Conditional – The number to add/remove from the FollowMe group list. This parameter is required for the addExternal and removeExternal actions but is ignored for the enable and disable actions.

 

/api/v1/ivrs

GET:

Retrieves data on all IVRs (auto-attendants) within the system.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/ivrs

 

/api/v1/patterns/outbound

GET:

Retrieves a list of outbound dial patterns configured for use within the system.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/patterns/outbound

 

/api/v1/pbx/asterisk

GET:

Performs a core reload command within Asterisk.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/pbx/asterisk/reload

 

/api/v1/pbx/framework

GET:

Retrieves a list of all destinations within the phone system. This includes extensions, ring groups, conferences, queues, etc. Specifically what is considered to be a destination is determined within the various FreePBX modules so there specific output here depends on which modules are enabled.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/pbx/framework/destinations

GET:

Retrieves a list of just the numerical assignments for all destinations within the phone system. As noted in the above destinations documentation, what is included is dependent on which modules are enabled.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/pbx/framework/destnumbers

GET:

Retrieves a boolean indicating whether or not the FreePBX configuration requires a reload. This is commonly indicated within the GUI with the presence of a red “Apply Config” button.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/pbx/framework/needreload

GET:

Returns a list of available “Music on Hold” classes configured within the system.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/pbx/framework/mohclasses

GET:

Performs a reload of the FreePBX configuration. This applies any “pending” changes, writes the Asterisk dial plan, and removes the red “Apply Config” button from the GUI.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/pbx/framework/reload

POST:

Sets a flag within FreePBX indicating that the configuration requires a reload. This presents within the GUI with the presence of a red “Apply Config” button.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/pbx/framework/needreload -X POST

 

/api/v1/queues

GET:

Retrieves data on all queues within the system.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/queues

 

/api/v1/recordings

GET:

Retrieves a list of all system recordings within the system.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/recordings

GET:

Downloads the specified recording from the system.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/recordings/<NAME>

  • <NAME> – The display name of the recording you wish to download.

 

/api/v1/registrations

GET:

Retrieves information, including registration status and user agent, for all extensions in the system.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/registrations

GET:

Retrieves information, including registration status and user agent, for the specified extension.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/registrations/<EXTENSION>

  • <EXTENSION> – The display name of the recording you wish to download.

 

/api/v1/ringgroups

GET:

Retrieves data on all ring groups within the system.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/ringgroups

 

/api/v1/state

GET:

Retrieves state/presence data on all SIP extensions within the system.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/state

GET:

Retrieves state/presence data on the specified SIP extension.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/state/<EXTENSION>

  • <EXTENSION> – The extension for which to retrieve state/presence data.

 

/api/v1/timeconditions

GET:

Retrieves data on all time conditions within the system. Associated time group data is included.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/timeconditions

 

/api/v1/voicemail

GET:

Retrieves a list of all voicemail messages for the specified extension.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/voicemail/<EXTENSION>

  • <EXTENSION> – The extension from which to retrieve voicemail message data.

GET:

Downloads a specific voicemail message.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/voicemail/<EXTENSION>/<MESSAGE>

  • <EXTENSION> – The extension from which to download the message.
  • <MESSAGE> – The voicemail message file identifier.

POST:

Delete one or more voicemail messages from the specified extension.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/voicemail/<EXTENSION> -X POST

  • <EXTENSION> – The extension from which to delete the voicemail message(s).
  • messages – Required – A multipart array of message file identifiers.

DELETE:

Deletes the specified voicemail message.

curl -u <USER>:<PASS> https://<SUBDOMAIN>.ringfree.biz/api/v1/voicemail/<EXTENSION>/<MESSAGE> -X DELETE

  • <EXTENSION> – The extension from which to delete the message.
  • <MESSAGE> – The voicemail message file identifier.