The PhoneMondo API

Basically using the PhoneMondo API is making HTTP requests to our server.
The base URL is https://www.phonemondo.com/api/ and you will need an API token to have access there.
You can generate API tokens yourself here: https://www.phonemondo.com/portal/settings/apitoken/

Once you have a token use it by sending it with every request. We accept GET and POST, so it can be as simple as this:
https://www.phonemondo.com/api/calls/items?api_token=<yourtoken>[&format=(json|xml)][&nice=1]
The response can be JSON or XML, depending on your choice using the format parameter. If unspecified, the API will return JSON. This document only refers to JSON but there are some sample links to XML output. Just try them, you'll see that it's pretty much self-explanatory.
If you include the nice=1 parameter the API will return some more data that you may use for display purpose. It contains preformatted date-time values, numbers and so on in the users correct language and formatting. Again this is not part of this documentation, but there are sample links available.

Examples

We use many APIs ourselves, so we know that it's always best to learn by sample. As the PhoneMondo API is just calling URLs (and we know you are using a browser atm) we can instandly provide some example URLs just by entering an API token below.

Any modern browser parses XML instantly and shows you the results in a nice manner, but if you want to have a deeper look into the result JSON, you should consider pressing F12 to enable your browsers developer tools. They provide a nice way to inspect the JSON response.

Please fill in a valid API token here to create valid sample URLs:

List calls:

List calls page 2, 5 items per page:

List contacts page 1, 1 items per page:

Get information for german number 058120889652:

List all sources:

API reference

To have things grouped together, the PhoneMondo API is split into different parts.
We call these parts 'controller'. Each controller has a set of 'methods' which is what you may call.

Each call needs the @api_token parameter, but we will leave that out in the documentation below to keep it slim.

calls

The calls controller provides methods for listing calls and their details. It is also used to report calls to PhoneMondo.

calls/items

Pagewise list calls, ordered by age.

Request details:

URL calls/items?page=@&items=@
@page Page number, starting at 1
@itemsItems per page, values from 1 to 100, default 20

Return value: Listing[CallObject]

Errors: USERNOTFOUND

calls/get

Returns details about a call.

Request details:

URLcalls/get?uid=@
@uidThe calls uid

Return value: CallObject

Errors: CALLNOTFOUND

calls/report

Reports a new call to PhoneMondo. Note that this is used to report calls while they take place and change their states. If you want to inform PhoneMondo about historical calls, use 'import' instead.

Request details:

URLcalls/report?source_identifier=@&call_identifier=@&caller=@&called=@&state=@&direction=@&source_label
@source_identifierIdentifies the source reporting the call (see IDENTIFIER)
@call_identifier Identifies the call in context of the source (see IDENTIFIER)
@caller The raw caller string
@called The raw called string
@state The call state, values are 0,1,2 (see CALLSTATE)
@direction The call direction, values are 0,1 (see DIRECTION)
@source_label An optional label for the source, used for creation if it's a new source

Return values: CallObject
OR

{"duplicate": true}

Errors: SOURCENOTFOUND

calls/reportState

Changes a calls state. Note that for an existing call you can also use the 'report' method. If you want the simpler interface, use this.

Request details:

URLcalls/reportState?source_identifier=@&call_identifier=@&state=@
@source_identifierIdentifies the source reporting the call (see IDENTIFIER)
@call_identifier Identifies the call in context of the source (see IDENTIFIER)
@state The call state, values are 0,1,2 (see CALLSTATE)

Return value: CallObject

Errors: CALLNOTFOUND, SOURCENOTFOUND

calls/ping

Let PhoneMondo know that a call is still in progress. If this is not called periodically, PhoneMondo will assume that there was an error and mark the call as ended automatically.

Request details:

URLcalls/ping?call_identifier=@
@call_identifierIdentifies the call in context of the source (see IDENTIFIER)

Return value: CallObject

Errors: CALLNOTFOUND

calls/import

Imports a call into PhoneMondo. Note that this is used to report historical calls. If you want to inform PhoneMondo about active calls, use 'report' instead.

Request details:

URLcalls/import?source_identifier=@&call_identifier=@&calldate=@&caller=@&called=@&direction=@&duration
@source_identifierIdentifies the source reporting the call (see IDENTIFIER)
@call_identifier Identifies the call in context of the source (see IDENTIFIER)
@calldate The date and time when the call took place (see DATETIME)
@caller The raw caller string
@called The raw called string
@direction The call direction, values are 0,1 (see DIRECTION)
@duration The duration of the call in seconds

Return value: CallObject

Errors: SOURCENOTFOUND

calls/decline

Hangs up a call.

Request details:

URLcalls/decline?uid=@
@uidThe calls uid

Return value: OK

Errors: CALLNOTFOUND

calls/forward

Forwards a call to another number.

Request details:

URLcalls/decline?uid=@&number=@
@uid The calls uid
@number The number to forward the call to

Return value: OK

Errors: CALLNOTFOUND

contacts

The contacts controller provides methods for listing contacts and their details. It is also used to report contacts to PhoneMondo.

contacts/items

Pagewise list contacts, ordered by name.

Request details:

URL contacts/items?page=@&items=@
@page Page number, starting at 1
@itemsItems per page, values from 1 to 100, default 20

Return value: Listing[ContactObject]

Errors: none

contacts/get

Returns details about a contact.

Request details:

URLcontacts/get?uid=@
@uidThe contact's uid

Return value: ContactObject

Errors: CONTACTNOTFOUND

contacts/getNumbers

Returns all numbers that have been assigned to a contact.

Request details:

URLcontacts/getNumbers?uid=@
@uidThe contact's uid

Return value: Listing[NumberObject]

Errors: CONTACTNOTFOUND

contacts/getCalls

Returns all calls a contact was involved with.

Request details:

URLcontacts/getCalls?uid=@&page=@&items=@
@uidThe contact's uid
@page Page number, starting at 1
@itemsItems per page, values from 1 to 100, default 20

Return value: Listing[CallObject]

Errors: CONTACTNOTFOUND

contacts/import

Imports a contact into PhoneMondo.

Request details:

URLcontacts/import?origin=@&name=@&address1=@&address2=@&zip=@&city=@&country=@&description=@&number=@&number_role=@
@origin An origin for this contact (something like your app name)
@name Contact's name
@address1 Optional: First address line
@address2 Optional: Second address line
@zip Optional: ZIP code
@city Optional: City
@country Optional: Two letter country code (DE,EN,...)
@description Optional: A Description
@number Optional: A number to add (if it is recognized)
@number_role Optional: A role for the optional number (Home, Office, Mobile,...)

Return value: ContactObject

Errors: CONTACTLIMITREACHED

contacts/assignNumber

Assigns a telephone number to a contact.

Request details:

URLcontacts/assignNumber?uid=@&number=@&number_role=@
@uid The contact's uid
@number Number to add (if it is recognized)
@number_role A role for the optional number (Home, Office, Mobile,...)

Return value: NumberObject

Errors: CONTACTNOTFOUND, INVALIDNUMBER

numbers

numbers/info

Gets information about a number string

Request details:

URLnumbers/info?number=@&country=@
@number The number string
@country Optional: Two letter country code to let PhoneMondo recognize local numbers

Return value: NumberObject

Errors: INVALIDNUMBER

numbers/getContacts

Returns all contacts that have the given number assigned

Request details:

URLnumbers/getContacts?number=@
@number The number

Return value: Listing[ContactObject]

Errors: NUMBERNOTFOUND

sources

sources/add

Creates a new call source

Request details:

URLsources/add?identifier=@&label=@
@identifier The source identifier
@label The source label

Return value: SourceObject

Errors: SOURCENOTFOUND

sources/items

Pagewise list all active sources, newest first.

Request details:

URL sources/items?page=@&items=@
@page Page number, starting at 1
@itemsItems per page, values from 1 to 100, default 20

Return value: Listing[SourceObject]

Errors: none

sources/startCall

Starts a call using a specific source.

Request details:

URLsources/startCall?uid=@&number=@
@uidThe source's uid
@number The number to be called

Return value: OK

Errors: SOURCENOTFOUND, INSUFFICIENT_CAPABILITIES, SOURCEBUSY

Type definitions

Object types

Listing[Type]

{
	"paging": // this is optional
	{
		"rows_per_page": 20,
		"current_page" : 2,
		"total_pages"  : 10,
		"total_rows"   : 205,
		"offset"       : 40
	},
	"items":
	[
		// zero or more items of given type
	]
}

CallObject

{
	"uid": "3dAHtxFuUg", 
	"identifier": "c82a9b4a-8445-4f74-8d75-1fcd6a2a8b5c", 
	"caller_raw": "058120889652", 
	"called_raw": "21", 
	"caller": { NumberObject },               // optional, only given if caller_raw is/was recognized as valid number
	"called": { NumberObject },               // optional, only given if called_raw is/was recognized as valid number
	"direction": 0, 
	"ringing": "2015-05-19T12:45:33+02:00", 
	"connected": "2015-05-19T12:45:37+02:00",     // optional, only given if call is/was connected
	"disconnected": "2015-05-19T12:52:25+02:00",  // optional, only given if call is/was disconnected
	"capabilities":     // optional, only given if call is currently active
	{
		"drop":true,	// call can be dropped using calls/decline
		"forward":true  // call can be forwarded using calls/forward
	}
}

NumberObject

{
	"uid": "3dAHtxFuUg", 
	"number": "004958120889652", 
	"details": { NumberDetailsObject },  // optional, depends on API details level
	"contacts": [ ContactObject ],              // optional, only given if there are contacts with this number
	"notificationData": { KEYVALUEPAIRS },     // deprecated, will be removed
	"metadata": { KEYVALUEPAIRS }
}

NumberDetailsObject

{
	"country_code": "DE",
	"cc": "49",
	"ndc": "581",
	"sn": "",
	"type": "FIXED",
	"country": "Germany",
	"lat": 52.9668375,
	"lng": 10.5586149,
	"subscriber": "947713",
	"international": "004958120889652"
}

ContactObject

{
	"avatar": "http://www.phonemondo.com/portal/.....",
	"uid": "asxdLay58b",
	"name": "Testkunde Meier",
	"address1": "Meierstra\u00dfe 3",
	"address2": "",
	"zip": "29588",
	"city": "Oetzen",
	"country": "DE"
}

SourceObject

{
	"device": { DeviceObject },
	"uid": "asxdsday58b",
	"identifier": "192.168.23.129|SIP\/OfficePhone1",
	"original_name": "SIP\/OfficePhone1",
	"label": "SIP\/OfficePhone1",
	"enabled": "1",
	"deleted": false,
	"settings": { KEYVALUEPAIRS }
}

DeviceObject

{
	"uid": "lXAjaaD1dbf",
	"identifier": "hUeNgwWsVZlNd",
	"label": "COMPUTER1",
	"country": "DE",
	"culture": "de",
	"timezone": "Europe\/Berlin",
	"areacode": "5805"
}

ErrorObject

{
	"state": "err",    // this is a constant value and always 'err'
	"code": "(see ErrorCodes)",
	"message": "invalid number given"	// this is a very short human readable description
}

KEYVALUEPAIRS

This is untyped object. It can contain anything and it depends on the context what is in there.

{
	"key1": "value1", 
	"key 2": true, 
	"k ey3": { "some":"data" }
	// ...
}

OK

This is a fixed object, used for OK responses.

{ "state": "ok" }

Simple types

UID

A UID is the type-wide uinique identifier inside the PhoneMondo system. It is a pseudo-random combination of chars that is genreated when the object is saved first and it is never changed.

IDENTIFIER

An identifier can contain of any number of any chars. It is not generated by the PhoneMondo server, but clientside thus it is not guaranteed to be unique!

DATETIME

Dates and times are delivered in a global machine readable format: ISO 8601. Date and time will always be combined and time zone designators are always used!

DIRECTION

A call direction is incoming or outgoing. PhoneMondo uses 0 (zero) for incoming and 1 (one) for outgoing calls.

CALLSTATE

Represents the current state of the call: 0 (zero) is used for ringing calls, 1 (one) for active calls and 2 (two) for disconnected calls.

FQNUMBER

This represents a full qualified international telephone number. Note that PhoneMondo does not use '+', but '00' as prefix.

NUMBERTYPE

The type of a telephone number. Basically one of these: 'FIXED', 'MOBILE', 'MOBILE/FIXED', 'MOBILE/PAGING', 'PAGING', 'SATELLITE', 'SUPPLEMENTARY SERVICES'

Error codes

In case of an error the API will return valid JSON. In other words: If you encounter an HTTP error, something more basic crashed.
See the ErrorObject for details about structure.

These are the most common errors the api may return. They are all quite self-explanatory, so we just provide a short description here.

USERNOTFOUND A valid user was required, but could not be identified.
CALLNOTFOUND The requested call was not found.
SOURCENOTFOUND The requested source was not found.
CONTACTNOTFOUND The requested contact was not found.
CONTACTLIMITREACHED Too many contacts. Upgrade to PhoneMondo Professional to get unlimited contacts.
INVALIDNUMBER A given number string could not be recognized as telephone number
SOURCEBUSY Source is busy and cannot be used for call actions
INSUFFICIENT_CAPABILITIESSource cannot do what you want is to do (call, block,...)

Notes on XML

When the PhoneMondo API outputs XML, it will in fact dump out a multidimentional associative array. It may happen, that an array key starts with a number (0-9). As the XML spec does not allow node-names to start with a number, the API will in that case generate a node named xmlnode with a name attribute containing the key.
So far with the explanation, here's an example:

<lines>
	<HKasC4S7df>SIP/1001</HKasC4S7df>
	<xmlnode name="4qIBDCS39df">SIP/1002</xmlnode>
	<qwe123adqw>SIP/1003</qwe123adqw>
</lines>