Phone Janitor Web API Reference

All the functionality of Phone Janitor is exposed through a set of web-accessible interfaces. These interfaces make it possible to automate account management and build new features on top of the system.

Every API call takes the form of an HTTP POST request directed at a URL which indicates the API function you wish to call. URLs always begin with https://phonejanitor.com/api/, followed by the function name. The content of the POST is a JSON Object which provides arguments for the API call, such as account credentials.

The response will similarly be a JSON string which either contains the requested data, an indication that the call succeeded or an error message indicating that the call failed. If the call succeeded, results will be stored in a JSON object with the key value, while error messages will be stored with the key error.

Most API calls are authenticated using a session token. Calling beginSession with an account username and password will produce such a token. Existing session tokens are automatically invalidated if beginSession is called, or can be explicitly invalidated with endSession. Calling checkSession allows user code to test whether a token is still valid. Session tokens will automatically expire after 1 hour of inactivity, not counting checkSession.

Imagine a user with an account named "Steve" had a password "un$4n1tAry" and owned the endpoint (phone number) "1-(555)-867-5309". Steve wants to write a script that allows him to see if he has any new voicemail messages. First, Steve needs to call beginSession to get an API token, and then he can make other calls. The API call getVoicemail will provide the information he needs, so he writes a quick Python program:

#!/usr/bin/env python

import json
import urllib2

# obtain a session token
credentials = {"username": "Steve", "password": "un$4n1tAry"}
authrequest = urllib2.Request("https://phonejanitor.com/api/beginSession", json.dumps(credentials))
authtoken   = json.loads(urllib2.urlopen(authrequest).read())["value"]

# request the contents of the voicemail inbox
payload = {"token": authtoken, "number":"15558675309"}
request = urllib2.Request("https://phonejanitor.com/api/getVoicemail", json.dumps(payload))
newmail = json.loads(urllib2.urlopen(request).read())["value"]["new"]

if any(newmail):
	print "You have a new voicemail!"
else:
	print "No unheard voicemail today."

# manually expire the session token
# (not strictly necessary, but a good practice)
logoff = urllib2.Request("https://phonejanitor.com/api/endSession", json.dumps({"token": authtoken}))
urllib2.urlopen(logoff)

The full JSON response from this call may have looked something like:

{
	"value": {
		"caller": ["Richard Fawkes", "Janet H."],
		"number": ["1-557-8001", "1-555-1551"],
		"time"  : ["2015-05-24 03:45:01.0", "2015-05-23 09:10:30.0"],
		"new"   : [false, true],
		"audio" : ["820df6f4-1902-11e5-b60b-1697f925ec7b", "820df6f4-1902-11e5-b60b-1697f925ec7b"],
		"id"    : [1401, 1711]
	}
}

Note that the data is returned in a columnar fashion rather than as a list of tagged records. All API functions which return bulk data use a similar approach. All the columns returned will always be the same length.

If Steve had provided an incorrect username or password, he might have instead received:

{
	"error": "invalid credentials."
}

API Overview

API Function Details

beginSession

endSession

checkSession

createAccount

checkUsername

getAccountInfo

setAccountInfo

setPassword

getEndpoints

getGroups

createGroup

deleteGroup

setInGroup

getContacts

The result of calling getContacts will additionally contain several arrays of booleans keyed to each group (see getGroups) in an account's contact list. Each of these arrays will have the name of a group with the prefix group- as a key. The array contains true for each contact in the given group.

Argument	Type	Description
token	String	A session token. See beginSession.

createContact

deleteContact

setContactName

getCalls

getVoicemail

setVoicemailRead

deleteVoicemail

getRuleSet

setActiveRules

getRules

setRules

Rules

Rules form the basis of PhoneJanitor's core functionality: routing calls. A set of rules, or a "routing script" is represented as a JSON array containing a series of entries. Each entry has a list of conditions (such as who is calling or the time of day) and a list of actions (such as forwarding the call or sending it to voicemail) which should be performed if all the conditions are true. Both actions and conditions have a type field which indicates what, if any, additional parameters it should have. The structure of a set of Rules may be validated via setRules.

The following routing script contains two entries: if a family member calls during work hours, the call should be routed to the user's office phone, and if Jenny the Telemarketer tries to call it should go straight to voicemail.

[
    {
        "conditions": [
            {
                "type": "callerInGroup",
                "group": "Family"
            },
            {
                "type": "timeOfDay",
                "span": "after",
                "time": "09:00:00"
            },
            {
                "type": "timeOfDay",
                "span": "before",
                "time": "17:00:00"
            }
        ],
        "actions": [
            {
                "type": "callContact",
                "id": 10
            }
        ]
    },
    {
        "conditions": [
            {
                "type": "callerIsContact",
                "id": 32
            }
        ],
        "actions": [
            {
                "type": "sendToVoicemail"
            }
        ]
    }
]

Every endpoint has one or more associated routing scripts, exactly one of which is "active" at any given time. This makes it possible to set up a number of configurations and switch between them easily. See getRuleSet and setActiveRules for more information.

Condition Types

callerInGroup

callerIsContact

callerHasNumber

currentDate

dayOfWeek

timeOfDay

anyCall

Action Types

Currently all action types are exclusive, and thus it is only valid for the action list to contain a single action. In the future, support for additional action types will be added which may be combined with these "terminal" actions:

callContact

callNumber

sendToVoicemail

dropCall