Papal REST API v2 Reference

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:

  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.

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.