Version 2 of the Papal REST API improves on version 1 in a number of ways. Most notably it always returns a consistent data structure with three components:
- An HTTP status code such as 200, 204, 401, 404, etc.
- A human readable message such as “OK” or “Not found”.
- Whatever data is being returned from the API.
Additionally, version 2 adds support for POST requests.
Like version 1, the API requires authentication in the form of both a username and password. Access to the various GET and POST routes depends on whether or not the user has the api-get or api-post permissions assigned to them in Papal. As with all other Papal functions, superadmins can access both without having the permissions explicitly set.
https://portal.ringfree.com/api/v2
This is used as a test route for both GET and POST requests. When used as a POST route, all POST data is discarded as it’s just a route for testing.
GET
Example usage:
curl -k -u user:pass https://portal.ringfree.com/api/v2/
Example response:
{"status":200,"message":"GET test success","data":null}
POST
Example usage:
curl -k -u user:pass -d "test=test" https://portal.ringfree.com/api/v2/
Example response:
{"status":200,"message":"POST test success","data":null}
https://portal.ringfree.com/api/v2/manifest
This route returns a complete manifest of PBX containers indexed by CTID. This is a GET only route and POST requests to it will result in a 405 “Method not allowed” error.
GET
Example usage:
curl -k -u user:pass https://portal.ringfree.com/api/v2/manifest/
Example response (abbreviated):
{"status":200,"message":"OK","data":{"4005":{"ipaddress":"172.16.67.18","hostname":"privtest1.ringfree.biz","node":"node001.ringfree.biz","dbserver":"db1.ringfree.biz","callperseclimit":"15","chanlimit":"30","callingplan":"65533","pstnroutetable":"3","sbcroutetable":"4","sbctrunkid":"4","fqdntrunkid":"5","pstntrunkid":"6","pptlocation":null,"fiftyseventy":null,"vendorid":"1","fop2manager":null,"dbname":"4005_asterisk","nfsserver":"atl.san1.ringfree.biz"}}}
https://portal.ringfree.com/api/v2/revnat
This route returns an abbreviated PBX container manifest containing data specifically useful for the Revnat and HAProxy instances in the Ringfree infrastructure. This is a GET only route and POST requests to it will result in a 405 “Method not allowed” error.
GET
Example usage:
curl -k -u user:pass https://portal.ringfree.com/api/v2/revnat/
Example response (abbreviated):
{"status":200,"message":"OK","data":{"4005":{"hostname":"privtest1.ringfree.biz","ipaddress":"172.16.67.18","vendorid":"1"}}}
https://portal.ringfree.com/api/v2/customers
This route returns a complete list of customers in the Papal database along with all of the associated contact data. This is a GET only route and POST requests to it will result in a 405 “Method not allowed” error.
GET
Example usage:
curl -k -u user:pass https://portal.ringfree.com/api/v2/customers
Example response (abbreviated):
{"status":200,"message":"OK","data":{"1":{"name":"AcctVantage ERP","address1":"317 N. Main St.","address2":"Suite 200","city":"Hendersonville","state":"NC","zip":"28792","hostname":"acctvantage.ringfree.biz","phone":"18286923301","itpartnerid":null,"isitpartner":null,"active":"1"}}
https://portal.ringfree.com/api/v2/contacts
This route returns a complete list of contacts in the Papal database along with all of the associated contact data. This is a GET only route and POST requests to it will result in a 405 “Method not allowed” error.
GET
Example usage:
curl -k -u user:pass https://portal.ringfree.com/api/v2/contacts
Example response (abbreviated):
{"status":200,"message":"OK","data":{"58":{"customer":"Edifice Solutions","customerid":"61","firstname":"Kisha","lastname":"Baker","email":"k.baker@edificesolutions.com","phone":"12024995900","extension":"104","type":"none"}}}
https://portal.ringfree.com/api/v2/contacts/<customer_id>
This returns a list of contacts associated with any given customer. Replace <customer_id> with the actual customer ID value in the URL. This is a GET only route and POST requests to it will result in a 405 “Method not allowed” error.
GET
Example usage:
curl -k -u user:pass https://portal.ringfree.com/api/v2/contacts/61
Example response:
{"status":200,"message":"OK","data":{"58":{"customer":"Edifice Solutions","customerid":"61","firstname":"Kisha","lastname":"Baker","email":"k.baker@edificesolutions.com","phone":"12024995900","extension":"104","type":"none"}}}
https://portal.ringfree.com/api/v2/contact
This route is for submitting a new contact and, as such, is a POST only route. The following fields will be considered when submitted, however customer, firstname, and lastname are required:
customer(int) – The ID of the customer with which the contact should be associated.firstname(string) – The first name of the contact.lastname(string) – The last name of the contact.email(string) – The contact’s email. This field will be rejected if not properly formatted.phone(string) – Ten or eleven digit phone number. Format should be irrelevant.extension(int) – The contact’s extension in the phone system.type(bool) – What is the type of this contact (prim, scnd, auth, none)?
POST
Example usage (Note: Email parameter may be passed using either @ or %40) :
curl -k -u user:pass -d "customer=120&firstname=Jon&lastname=Lucas&email=jlucas@ringfree.com&phone=18285750030&extension=107&type=auth" https://portal.ringfree.com/api/v2/contact
Example response:
{"status":200,"message":"OK","data":"63"}
https://portal.ringfree.com/api/v2/contact/<id>
This route is for either retrieving or updating a contact. The contact ID naturally replacing <id> in the URL.
GET
Example usage:
curl -k -u user:pass https://portal.ringfree.com/api/v2/contact/1
Example response:
"status":200,"message":"OK","data":{"1":{"customer":"AcctVantage ERP","customerid":"1","firstname":"Tim","lastname":"Lau","email":"tlau@acctvantage.com","phone":"18286923301","extension":"702","type":"none"}}}
POST
Example usage:
curl -k -u user:pass -d "extension=456" https://portal.ringfree.com/api/v2/contact/63
Example response:
{"status":200,"message":"OK","data":"63"}
https://portal.ringfree.com/api/v2/alerts
This GET only route returns complete data for all active system alerts. POST requests to this route will return a 405 “Method not allowed” error.
GET
Example usage:
curl -k -u user:pass https://portal.ringfree.com/api/v2/alerts
Example response:
{"status":200,"message":"OK","data":{"5":{"title":"Database Failover","timestamp":"2017-02-14 18:34:29","blurb":"galera-atl.ringfree.biz experienced a failover.","data":"galera-atl.ringfree.biz is presently routing to galera-nyc-01.ringfree.biz as a result of a MySQL error on galera-atl-01.ringfree.biz. Manual reversion is recommended."}}}
https://portal.ringfree.com/api/v2/alert
This is a POST only route for submitting new system alerts. Submitting a new alert requires three fields to be submitted in the POST data:
- title (string): The system alert title.
- blurb (string): The alert summary.
- data (string): The full text of the alert.
Omitting any of the fields will result in a 400 “Bad request” error. A successful request will return the ID of the newly created alert in the data field of the response.
POST
Example usage:
curl -k -u user:pass -d "title=Testing&blurb=Alert via API&data=This is a test of the API v2 POST route to create system alerts." https://portal.ringfree.com/api/v2/alert
Example response:
{"status":200,"message":"OK","data":"6"}
https://portal.ringfree.com/api/v2/alert/<id>
This route is used to either retrieve data associated with an alert or to mark that alert as dismissed. In either case, replace <id> with the ID of the alert. Using the ID of an alert that does not exist will result in a 404 “Not found” error.Using a POST request to dismiss an alert that has already been dismissed will result in a 409 “Conflict” error.
Dismissing an alert requires a single entry in the POST data: a user field so that the API knows which user to identify as responsible for dismissing the alert.
Using this route with a GET request will return all data associated with the alert, including the dismissal status and, if dismissed, which user was responsible for the dismissal.
GET
Example usage:
curl -k -u user:pass https://portal.ringfree.com/api/v2/alert/5
Example response:
{"status":200,"message":"OK","data":{"5":{"title":"Database Failover","timestamp":"2017-02-14 18:34:29","blurb":"galera-atl.ringfree.biz experienced a failover.","data":"galera-atl.ringfree.biz is presently routing to galera-nyc-01.ringfree.biz as a result of a MySQL error on galera-atl-01.ringfree.biz. Manual reversion is recommended.","dismissed":"1","dismissedby":"1"}}}
POST
Example usage:
curl -k -u user:pass -d "user=1" https://portal.ringfree.com/api/v2/alert/6
Example response:
{"status":200,"message":"OK","data":"6"}
https://portal.ringfree.com/api/v2/notifications/<user_id>
This is a GET only route that displays a given user’s active notifications and associated data. POST requests to this route will result in a 405 “Method not allowed” error. Replace the <user_id> with the actual user ID number.
GET
Example usage:
curl -k -u user:pass https://portal.ringfree.com/api/v2/notifications/1
Example response:
{"status":200,"message":"OK","data":{"9":{"timestamp":"2017-02-15 08:00:00","title":"Test","blurb":"API Test","data":"This is a test of the API."}}}
https://portal.ringfree.com/api/v2/notification
This is a POST only route for creating new user notifications. Requests to this route must include the following data fields:
- user (int): The ID of the user with which to assocaite the notification.
- title (string): The notification title.
- blurb (string): The notification summary.
- data (string): The full text of the notification.
Omission of any of the above fields will result in a 400 “Bad request” error. GET requests to this route will result in a 405 “Method not allowed” error. Successful requests will return the ID of the newly created notification in the response data field.
POST
Example usage:
curl -k -u user:pass -d "user=1&title=API&blurb=API&data=API" https://portal.ringfree.com/api/v2/notification
Example response:
{"status":200,"message":"OK","data":"11"}
https://portal.ringfree.com/api/v2/notification/<id>
This route accepts GET requests as a means of retrieving data associated with a particular notification as well as POST requests as a means of dismissing a particular notification.
POST requests require a dismiss field to be included in the POST data; any truthy value will suffice. Submission of a falsey value for dismiss will result in a status 204 message. Omission of the dismiss field will result in a 400 “Bad request” error. Attempts to dismiss a notification that can not be found will result in a 404 “Not found” error. Attempts to dismiss a notification that has already been dismissed will result in a 409 “Conflict” error.
GET
Example usage:
curl -k -u user:pass https://portal.ringfree.com/api/v2/notification/11
Example response:
{"status":200,"message":"OK","data":{"11":{"user":"1","timestamp":"2017-02-15 16:22:47","title":"API","blurb":"API","data":"API"}}}
POST
Example usage:
curl -k -u user:pass -d "dismiss=1" https://portal.ringfree.com/api/v2/notification/11
Example response:
{"status":200,"message":"OK","data":"11"}
https://portal.ringfree.com/api/v2/yconfpass/<ctid>
This route accepts GET requests as a means of retrieving the YConf password associated with a given PBX and POST requests as a means of setting/updating the YConf password associated with a given PBX.
POST requests require a password field to be included in the POST data; any password should suffice. Failure to provide a password will result in a 400 “Bad Request” error. GET or POST requests to a CTID that doesn’t exist will result in a 404 “Not Found” error. Successful POST requests wil return a 200 with the CTID in the data field. Successful GET requests will return either a 200 or a 204 depending on whether or not a password is currently set.
GET
Example usage:
curl -k -u user:pass https://portal.ringfree.com/api/v2/yconfpass/1900027
Example response:
{"status":200,"message":"OK","data":"examplepassword"}
POST
Example usage:
curl -k -u user:pass -d "password:newpassword" https://portal.ringfree.com/api/v2/yconfpass/1900027
Example response:
{"status":200,"message":"OK","data":"1900027"}
That’s all for now. Additional REST routes will be added in the near future.