Partner API¶

API Call Reference¶

/api/partner/user¶

GET /api/partner/user/(user-uuid)¶

Get user-related information of the user with UUID user-uuid that was created under the current partner.

Response body example

{
    "user": {
        "username": "johndoe47",
        "firstname": "John",
        "lastname": "Doe",
        "display_name": "Johnny Doe",
        "country_code": "+49",
        "ignore_ip_whitelisting": true,
        "usergroup": "Accounting",
        "email": "john@doe.com",
        "language": "de",
    },
    "phone": {
         "+492216698712": {
             "conference_enable": false,
             "fax_enable": true,
             "recording_enable": true,
             "notification_email": true,
             "notification_attachment": true
         },
         "+491234567890": {
             "conference_enable": true,
             "fax_enable": false,
             "recording_enable": false,
             "notification_email": false,
             "notification_attachment": false,
             "p_asserted_identity": "+492216698712"
         }
     },
     "feature": {
         "pack": [
             "20GB+",
             "COSPACE-BOX"
         ]
     }
}

Status:	wrong-user: The given `user-uuid` does not exist or the user does not belong to the current partner

This API call requires a session that is authenticated with a partner. The phone section will only be included if the partner controls phone number assignments for its users.

The feature section, pack subsection lists the feature packs assigned to the user.

GET /api/partner/user¶

Lists all partner related users.

Query Parameters:

from – optional: start time, in seconds-since-epoch when the user was created (must have from <= to)
to – optional: end time, in seconds-since-epoch when the user was created (must have from <= to)
start –
optional: the UUID of the first user to return, exclusive, i.e. the user with an exact match UUID is not returned.

If given, overrides the from parameter when asc order is selected or overrides the to parameter when desc order is selected.
order –
optional: If set to asc (default), users are returned in time ascending order (i.e. starting with from or start and ending with stop).

If set to desc, users are returned in time descending order (i.e. starting with to or start and ending with from).
count – optional, default 50: limits the number of returned users (valid range: 1...500)

Response body example

{
    "users": [
        "3d6371b0-b9d8-11e5-b5f6-f8a96351ccd6",
        "4418f930-b9d8-11e5-b5f6-f8a96351ccd6",
        "4475e640-b9d8-11e5-b5f6-f8a96351ccd6"
    ]
}

This API call requires a session that is authenticated with a partner.

GET /api/partner/user/(user-uuid)/calls¶

Get all phone numbers related to the user with UUID user-uuid and information about how many calls are currently active.

Response body example

{
    "phones": {
        "4922166966920" : 0,
        "4922166966930" : 2,
        "4922166966940" : 0
    }
}

Status:	wrong-user: The given `user-uuid` does not exist or the user does not belong to the current partner

This API call requires a session that is authenticated with a partner.

POST /api/partner/user/(user-uuid)¶

Allows a partner to temporarily disable or permanently delete the user UUID user-uuid that was created under the current partner.

Request body example

{
    "country_code": "+49",
    "disabled": true,
    "feature": {
        "pack": {
            "add": [
                "20GB+",
                "COSPACE-BOX"
            ],
            "delete": [
                "10GB+"
            ]
        }
    }
}

JSON Parameters:

country_code –
^\+[0-9]{1,3}$

Optional; the country code of the user.
ignore_ip_whitelisting –
true|false

Optional; the user’s ip address is not taken into account for nomadic use restrictions (and therefore disables this feature for this user)
disabled –
true|false

Optional; true means the user account will be temporarily disabled, false means the user account will be enabled again.
deleted –
true

Optional; if set to true, the user account will be permanently deleted. This action cannot be undone.

Response body example

{}

Status:	wrong-user: The given `user-uuid` does not exist or the user does not belong to the current partner

This API call requires a session that is authenticated with a partner.

Within the feature and pack section, feature packs can be associated with the user by listing them in the add subsection, or they can be deleted from the user having them in the delete subsection.

POST /api/partner/recovery/(user-uuid)¶

Start password recovery procedure and create a password recovery code for the user UUID user-uuid that was created under the current partner.

Request body example

{}

Response body example

{
    "code": "iausDia8sdfasjb9aaobasdfDF"
}

Status:	wrong-user: The given `user-uuid` does not exist or the user does not belong to the current partner

This API call requires a session that is authenticated with a partner.

GET /api/partner/user/event¶

Subscribe the current session to the event flow of all user’s associated to the partner.

Query Parameters:
	timeout – optional: expiration timeout of the event flow in seconds. Default: 1 hour (3600 seconds), valid range 1..36000 seconds (10 hours)

Response body example

{}

This API call will enable the flow of user events to the current session. The flow of events will automatically stop after the timeout period. If this behavior is not desired, this API call should be called again before expiration to re-new the timeout period. If there are more than one sessions of the partner subscribing, then the stream will be split between the subscribing sessions and if one of the sessions die, then the corresponding stream is just diverted to other sessions.

The observable user events are the following:

call_update
call_dtmf
sip_register
sip_unregister
fax_convert
fax_report
conference_*
dialplan_callreverse_start
dialplan_callreverse_stop

See Event Reference for more information.

DELETE /api/partner/user/event¶

Cancel the subscription of the current session to the data events of users

Response body example

{}

This API call will stop the flow of sensor data events to the current session.

/api/partner/phone¶

GET /api/partner/phone¶

Lists all partner related phones and the associated users.

Query Parameters:
	start – optional: the first phone number to return, exclusive, i.e. the phone number will not be returned, if it is an exact match. count – optional, default `50`: limits the number of returned users (valid range: `1...500`)

Response body example

{
    "phones": {
        "+4922166966910": "48999930-d3b3-11e4-b265-f8a96351ccd6",
        "+4922166966920": "4418f930-b9d8-11e5-b5f6-f8a96351ccd6",
        "+4922166966930": "4418f930-b9d8-11e5-b5f6-f8a96351ccd6",
        "+4922166966940": "4418f930-b9d8-11e5-b5f6-f8a96351ccd6"
    }
}

This API call requires a session that is authenticated with a partner.

POST /api/partner/phone/(user-uuid)¶

Modify phone configuration for the user UUID user-uuid that was created under the current partner.

Request body example

{
    "create": {
        "+492216698123": {
            "dialplan_enable": true,
            "call_enable": false,
            "recording_enable": false,
            "fax_enable": false,
            "conference_enable": false,
            "play_announcement_only": false,
            "notification_email": true
        }
    },
    "update": {
        "+492216698712": {
            "conference_enable": false,
            "notification_email": true,
            "notification_attachment": true
        },
        "+491796548354": {
            "fax_enable": true,
            "conference_enable": false,
            "notification_attachment": false
        },
        "+49221669871200": {
            "p_asserted_identity": "+492216698712"
        }
    },
    "delete": [
        "+492211110004",
        "+492211110006"
    ]
}

JSON Parameters:
	phonenumber – `^\+[0-9]{3,20}$` p_asserted_identity – `^\+[0-9]{3,20}$` Optional; The given number will used for billing and law issues. It must be a correct number. Setting the field to `null` will remove the field.

Response body example

{}

Status:

wrong-user: The given user-uuid does not exist or the user does not belong to the current partner
wrong-phone: A phone number listed in the update or delete section does not belong to this user
phone-duplicate: A phone number listed in the update section is already assigned to some user
phone-forbidden: The current partner does not have the right to control phone number assignments for its users

This call requires a session that is authenticated with a partner. Additionally, the partner must have the right to assign phone numbers to its users.

The numbers in the create section are added to the user’s list of phone numbers, the numbers in the update section of the request body are modified in the current user’s phone data and the numbers in the delete section are deleted from the user’s phone data.

The dialplan_enable, call_enable, fax_enable, conference_enable and recording_enable elements in the create and update sections are all optional (dialplan_enable and call_enable default to false, all other switches default to true).

Any combination of the *_enable switches is possible; however dialplan_enable takes priority, i.e. if dialplan_enable is true, the setting of call_enable, fax_enable, conference_enable and recording_enable is ignored for that number. The call API (call_enable) will only work if call_enable is the only switch that is true.

The play_announcement_only field is optional and defaults to false. If set to true, the system will not record a voice message after the announcement has been played in voice recorder mode.

The notification_email and notification_attachment elements in the create and update sections are optional (default false).

See POST /api/phone for further information. The field’s announcement and on_hold_music can’t be set with this call.

/api/partner/callfilter¶

POST /api/partner/callfilter/(user-uuid)¶

Modify a user’s call filter.

Request body example

{
    "callfilter": [
        {
            "operator": "replace",
            "key": "^00",
            "value": "+"
        },
        {
            "operator": "replace",
            "key": "^0",
            "value": "+49"
        },
        {
            "operator": "replace",
            "key": "^+4911",
            "value": "11"
        },
        [
            {
                "operator": "service",
                "key": "sip",
                "reverse": true,
                "break": true
            },
            {
                "operator": "match",
                "key": "^\\+492216698711$",
                "pass": false
            },
            {
                "operator": "match",
                "key": "^\\+492216698499$",
                "pass": false
            },
            {
                "operator": "match",
                "key": "^(\\+49[2-8][0-9]{3,16})|(\\+499[1-9][0-9]{3,15})|(\\+4990[1-9][0-9]{3,14})$",
                "pass": true
            },
            {
                "operator": "match",
                "key": "^[1]{2}[0-7][0-9]{0,3}$",
                "pass": true
            }
        ],
        [
            {
                "operator": "service",
                "key": "fax",
                "reverse": true,
                "break": true
            },
            {
                "operator": "match",
                "key": "^(\\+49[2-8][0-9]{3,16})|(\\+499[1-9][0-9]{3,15})|(\\+4990[1-9][0-9]{3,14})$",
                "pass": true
            }
        ],
        {
            "operator": "match",
            "key": ".+",
            "pass": false
        }
    ]
}

Response body example

{}

Status:	wrong-user: The given `user-uuid` does not exist or the user does not belong to the current partner too-large: The given call filter exceeds the limit of 250 operators

This API call requires a session that is authenticated with a partner.

The partner can attach a call filter to user accounts that were created under the partner. Every time a user tries to make an outgoing phone call (e.g. send a fax, or place a call using SIP), the call filter will be checked in turn.

A filter consists of the operator and one or more more additional fields specific for the selected operator.

Operators can be nested using JSON arrays. The linear evaluation of such an array can be canceled by using the break field in certain operators. An operator can also directly allow or deny the call (skipping all following checks), using the pass field in certain operators. If nothing matches or the filter is empty, the call will be allowed. Every filter must contain the opening string call filter on the top level, containing at least one operator.

The following operators are supported:

replace

This operator can alter the dialed destination number. If the regular expression given in the key field matches the destination number, each occurence of the matched regular expression will be replaced by the value field. Both key and value fields must be JSON strings.

Break or pass fields may not be used in this operator.

As an example, this operator may be used to enforce country specific international numbers format (e.g. replace a leading „0” by „+49” for calls in Germany.
match

This operator matches the regular expression given in the key field against the destination number. If the expression matches, it can either allow or deny the call depending on the contents of the pass field. Alternatively, the evaluation of the current operator array can be stopped by setting the break field to true. Exactly one of the break or pass fields must be present.

If a additional reverse field is contained with a value of true, it will negate the check.

As an example, this operator can be used to allow (or deny) certain number areas like cell phone numbers or to implement outgoing call black lists.
service

This operator matches the type of outgoing call against the JSON string given in the key field. If the call type matches, it can either allow or deny the call depending on the contents of the pass field. Alternatively, the evaluation of the current operator array can be stopped by setting the break field to true. Exactly one of the break or pass fields must be present.

If a additional reverse field is contained with a value of true, it will negate the check.

Valid service types are fax, sip, dialplan, call_through, callback, ivr, announcement_call and call_api.

The call filter given in the example will work like this:

The destination number will be altered to match the German international phone number format, excluding the special number prefix 11 (used for emergency calls) .
If the service type is not of the type sip, the inner JSON array will be canceled. Otherwise, the destination number will be checked. +492216698711 and +492216698499 are explicitly denied while German fixed network numbers, service numbers that are free of charge and emergency calls are allowed.
If the call is not allowed or denied so far, because no operator containing a pass has matched, the filter continues with the second inner JSON array.
If the service type is not of the type fax, this JSON array will be canceled. Otherwise the destination number will be checked again. German fixed network numbers and service numbers that are free of charge are allowed.
At the end of the filter, all calls are denied.

GET /api/partner/callfilter/(user-uuid)¶

Get a user’s call filter, if any.

Response body example

{
    "callfilter": {
        "operator": "match",
        "key": ".+",
        "pass": false
    }
}

Status:	wrong-user: The given `user-uuid` does not exist or the user does not belong to the current partner empty-filter: The given user does not have a call filter

This API call requires a session that is authenticated with a partner.

DELETE /api/partner/callfilter/(user-uuid)¶

Delete a user’s call filter.

Response body example

{}

Status:	wrong-user: The given `user-uuid` does not exist or the user does not belong to the current partner

This API call requires a session that is authenticated with a partner.

/api/partner/cdr¶

GET /api/partner/cdr/(phone)¶

Get the list of call detail records (CDR) related to this phone number.

Query Parameters:

from – optional: start time, in seconds-since-epoch (must have from <= to)
to – optional: end time, in seconds-since-epoch (must have from <= to)
start –
optional: the id of the first CDR to return, exclusive, i.e. the result with an exact match id is not returned.

If given, overrides the from parameter when asc order is selected or overrides the to parameter when desc order is selected.
order –
optional: If set to asc (default), objects are returned in time ascending order (i.e. starting with from or start and ending with stop).

If set to desc, objects are returned in time descending order (i.e. starting with to or start and ending with from).
count – optional, default 10: limits the number of returned objects (valid range: 1...5000)

Response body example

{
    "cdr": [
        {
            "id": "2b5e1560-124f-11e4-b449-f8a96351ccd6",
            "date": 1406109196726
            "service": "call",
            "b_number": "+492216698711",
            "t_pre": 4,
            "t_post: 107,
        },
        {
            "id": "b31e29b0-3813-11e4-bae1-f8a96351ccd6",
            "date": 1406109203444
            "service": "call",
            "a_number": "+492216698499",
            "parent": "2b5e1560-124f-11e4-b449-f8a96351ccd6",
            "root": "2b5e1560-124f-11e4-b449-f8a96351ccd6",
            "t_pre": 7,
            "t_post: 33,
        },
        {
            "id": "981c8030-41cb-11e6-bc0b-f8a96351cc93",
            "b_number": "+492216698711",
            "root": "97ef2ea0-41cb-11e6-bc0b-f8a96351cc93",
            "parent": "97ef2ea0-41cb-11e6-bc0b-f8a96351cc93",
            "date": 1467625336745,
            "service": "call",
            "t_post": 7,
            "t_pre": 3
        },
        {
            "id": "97ef2ea0-41cb-11e6-bc0b-f8a96351cc93",
            "a_number": "csc_00",
            "date": 1467625336365,
            "phone": "+4922166966914",
            "t_post": 7,
            "t_pre": 3
        },
    ]
}

Status:	wrong-phone: The given phone number was not assigned by the partner or does not exist

This API call requires a session that is authenticated with a partner.

The partner can fetch CDRs according to the given phone. All CDRs have the following fields:

date (the current time in ms since epoch when the call was initiated)
service (one of call, conference, fax, blf_pickup, call_through, call_reverse and call_back)
fax_id (Optional uuid of fax)
recording_id (Optional uuid of recording)
conference_id (Optional uuid of conference)
a_number (for incoming calls only) Contains the phone number or sip account.
b_number (for outgoing calls only) Contains the phone number or sip account.
parent (Optional uuid of the parent cdr)
root (Optional uuid of the first cdr in this group)
t_pre (pre_answer duration)
t_post (post_answer duration)

Certain service types have additional fields:

Conference service calls have a conference_id field, containing the conference id.

Fax service calls have a fax_id, containing the fax id. The numbers of pages sent / received will be in the page_count field.

Mailbox service calls have a recording_id field, containing the recording id.

GET /api/partner/cdr/event¶

Subscribe the current session to the event flow of CDRs associated to the partner.

Query Parameters:
	timeout – optional: expiration timeout of the event flow in seconds. Default: 1 hour (3600 seconds), valid range 1..36000 seconds (10 hours)

Response body example

{}

This API call will enable the flow of CDR events to the current session. The flow of events will automatically stop after the timeout period. If this behavior is not desired, this API call should be called again before expiration to re-new the timeout period. If there are more than one sessions of the partner subscribing, then the stream will be split between the subscribing sessions and if one of the sessions die, then the corresponding stream is just diverted to other sessions.

DELETE /api/partner/cdr/event¶

Cancel the subscription of the current session to the data events of CDRs

Response body example

{}

This API call will stop the flow of CDR events to the current session.

/api/partner/emergency¶

GET /api/partner/emergency/(user-uuid)¶

Get emergency-call related information.

Response body example

{
    "uui_header": "001D73306138F193FFFF4A6F6C696F742D43757269652D5374722E",
    "emergency_police": "221CC00",
    "emergency_rescue": "221CC02"
}

Status:	wrong-user: The given `user-uuid` does not exist or the user does not belong to the current partner

This API call requires a session that is authenticated with a partner.

POST /api/partner/emergency/(user-uuid)¶

Update emergency-call related information.

Request body example

{
    "uui_header": "001D73306138F193FFFF4A6F6C696F742D43757269652D5374722E",
    "emergency_police": "221CC00",
    "emergency_rescue": "221CC02"
}

JSON Parameters:
	uui_header – `^.{0,200}$` Optional; the user-to-user-information for this user. emergency_police – `^.{0,10}$` Optional; the emergency number of the responsible police control center in german emergency encoding. emergency_rescue – `^.{0,10}$` Optional; the emergency number of the responsible rescue control center in german emergency encoding.

Response body example

{}

Status:	wrong-user: The given `user-uuid` does not exist or the user does not belong to the current partner

This API call requires a session that is authenticated with a partner.

If a user makes an emergency call (110 or 112) and has an emergency_police or emergency_rescue entry, the call will be routed to the responsible control center. An empty value for any of the parameters will delete them.

/api/partner/usergroup¶

POST /api/partner/usergroup¶

Creates an usergroup.

Request body example

{
    "description" : "Controlling",
    "prefix" : 7
}

JSON Parameters:
	description – `^.{0,200}$` optional: the description for this usergroup prefix – `0..9` optional: the prefix for this usergroup

Response body example

{
    "group_uuid": "dfc3e9c4-4e81-11e1-9fe3-0024e8f90cc0"
}

This API call requires a session that is authenticated with a partner.

A new usergroup will be created for the partner. The call will return the UUID of the group. In order to active the usergroups prefix, a partner must enable the group_prefix_enable flag for the surrounding enterprise.

POST /api/partner/usergroup/(uuid)¶

Updates an usergroup.

Request body example

{
    "description" : "Accounting",
    "prefix" : 7
}

JSON Parameters:
	description – `^.{0,200}$` optional: the description for this usergroup prefix – `^0..9$` optional: the prefix for this usergroup

Response body example

{}

This API call requires a session that is authenticated with a partner.

0 is no valid prefix. The transmission of 0 will remove the current prefix.

DELETE /api/partner/usergroup/(uuid)¶

Deletes an usergroup

Response body example

{}

Status:	wrong-usergroup: The given usergroup `uuid` does not exist or does not belong to the partner not-empty: The given usergroup `uuid` is not empty.

This API call requires a session that is authenticated with a partner.

An usergroup can only be deleted if there are no associated users.

POST /api/partner/usergroup/(uuid)/user¶

Modifies the list of users in an usergroup.

Request body example

{
    "users": {
        "add": [
            "6f756b60-b672-11e3-9948-0026b9c1d1a6",
            "3759ea04-4005-11e4-ba4e-0314e1b2a9ec",
            "37e25268-4005-11e4-8832-9781ed589c3f"
        ],
        "delete": [
            "383a87d0-4005-11e4-a8b2-1f1752f935a9"
        ]
    }
}

Response body example

{}

Status:	wrong-usergroup: The given usergroup `uuid` does not exist or does not belong to the partner wrong-user: At least one of the users listed does not exist or does not belong to the partner already-grouped: At least one of the users listed in the add section is already listed in another usergroup

This API call requires a session that is authenticated with a partner.

With this API call, users can be grouped into usergroups. Note that each user may only join one usergroup.

GET /api/partner/usergroup¶

Lists all usergroups that belong to the current partner.

Response body example

{
    "usergroups": {
        "d322dfe0-9730-11e4-8ff7-f8a96351ccd6": {
            "description": "Accounting",
            "prefix" : 7
        },
        "e8ee4030-9730-11e4-8ff7-f8a96351ccd6": {
            "description": "Controlling"
        }
    }
}

Status:	wrong-usergroup: The given usergroup `uuid` does not exist or does not belong to the partner

This API call requires a session that is authenticated with a partner.

GET /api/partner/usergroup/(uuid)/user¶

Get the list of users in an usergroup.

Response body example

{
    "usergroup" : {
        "users" : [
            "6f756b60-b672-11e3-9948-0026b9c1d1a6",
            "3759ea04-4005-11e4-ba4e-0314e1b2a9ec",
            "37e25268-4005-11e4-8832-9781ed589c3f"
        ]
    }
}

Status:	wrong-usergroup: The given usergroup `uuid` does not exist or does not belong to the partner

This API call requires a session that is authenticated with a partner.

GET /api/partner/usergroup/(uuid)/extension¶

Get information about the usergroup uuid internal extensions

Response body example

{
    "extensions" : {
        "10": "77a93f80-7f96-11e4-bfab-f8a96351ccd6",
        "20": "c759a6b0-7f9a-11e4-bfab-f8a96351ccd6"
    }
}

Status:	wrong-usergroup: The given usergroup `uuid` does not exist or does not belong to the partner

This API call requires a session that is authenticated with a partner.

POST /api/partner/usergroup/(uuid)/extension¶

Updates the usergroup uuid internal extensions

Request body example

{
    "add": {
        "100" : "5704a3d8-7b9e-11e4-af85-1725ff033d08",
        "200" : "57054036-7b9e-11e4-af28-17b08d2664a8",
        "300" : "5705df5a-7b9e-11e4-be13-8f63fafaa45c",
        "400" : "5707524a-7b9e-11e4-a24c-8bf86e2591ea",
        "500" : "57092ab6-7b9e-11e4-9633-9ba60e6dbcd6"
    },
    "delete" : [
        "10",
        "20",
        "30",
        "40",
        "50"
    ]
}

JSON Parameters:
	extension – `^[0-9]{1,5}$` the users internal extension

Response body example

{}

Status:	wrong-usergroup: The given usergroup `uuid` does not exist or does not belong to the partner wrong-user: At least one user does not exist, does not belong to the current partner or is not a member of the given `uuid`

This API call requires a session that is authenticated with a partner.

A partner can set internal extensions to an usergroup. Every user that is grouped into that usergroup and makes an outgoing call can dial a valid extension and will be connected to the given user’s dialplan.

GET /api/partner/usergroup/(uuid)/limit¶

Gets the concurrent call limit for an usergroup.

Response body example

{
    "limit": 2
}

Status:	wrong-usergroup: The given usergroup `uuid` does not exist or does not belong to the partner no-limit: The given usergroup does not have a concurrent call limit

This API call requires a session that is authenticated with a partner.

POST /api/partner/usergroup/(uuid)/limit¶

Sets a concurrent call limit for an usergroup.

Request body example

{
    "limit": 2
}

JSON Parameters:
	limit – `^[0-9]{1,3}$` The new concurrent call limit for this usergroup

Response body example

{}

Status:	wrong-usergroup: The given usergroup `uuid` does not exist or does not belong to the partner

This API call requires a session that is authenticated with a partner.

The concurrent call limit restricts the number of concurrent phone calls for all users in an usergroup. A limit of 0 effectively prevents the users in the group from establishing any calls.

DELETE /api/partner/usergroup/(uuid)/limit¶

Deletes the concurrent call limit for an usergroup.

Response body example

{}

Status:	wrong-usergroup: The given usergroup `uuid` does not exist or does not belong to the partner

This API call requires a session that is authenticated with a partner.

POST /api/partner/usergroup/(uuid)/credit¶

Modifies the credit count of an usergroup.

Request body example

{
    "add": 10000
}

JSON Parameters:
	add – `Integer` optional; the amount of credits to add subtract – `Integer` optional; the amount of credits to subtract

Response body example

{}

Status:	wrong-usergroup: The given usergroup `uuid` does not exist or does not belong to the partner

This API call requires a session that is authenticated with a partner.

At least one of the add or subtract fields must be present in the request.

GET /api/partner/usergroup/(uuid)/credit¶

Gets the credits left for an usergroup.

Response body example

{
    "credit": 4820
}

Status:	wrong-usergroup: The given usergroup `uuid` does not exist or does not belong to the partner no-credit: The given usergroup `uuid` does not have credits configured

This API call requires a session that is authenticated with a partner.

GET /api/partner/usergroup/credit¶

Lists all credits for the selected usergroups.

Query Parameters:
	min – optional, integer: only list usergroups with at least `min` credits (must be >= 0; if both present, `min` must be less than `max`) max – optional, integer: only list usergroups with a maximum of `max` credits (must be >= 0; if both present, `max` must be greather than `min`)

Response body example

{
    "credits": {
        "47795c20-d3b3-11e4-b265-f8a96351ccd6": 10000,
        "d322dfe0-9730-11e4-8ff7-f8a96351ccd6": 12000,
        "e8ee4030-9730-11e4-8ff7-f8a96351ccd6": 14000
    }
}

This API call requires a session that is authenticated with a partner.

If neither min nor max is present, all usergroups with credits will be returned.

DELETE /api/partner/usergroup/(uuid)/credit¶

Delete credit limit on an usergroup.

Response body example

{}

Status:	wrong-usergroup: The given usergroup `uuid` does not exist or does not belong to the partner

This API call requires a session that is authenticated with a partner.

POST /api/partner/usergroup/(uuid)/zonefilter¶

Modifies the zone filter of an usergroup.

Request body example

{
    "zonefilter": [
        {
            "description": "national",
            "prefix": ["+49"],
            "cost": 139
        },
        {
            "description": "euro1",
            "prefix": ["+32", "+39", "+44"],
            "cost": 189
        },
        {
            "description": "rest",
            "prefix": [""],
            "cost": 599
        }
    ]
}

Response body example

{}

Status:	wrong-usergroup: The given usergroup `uuid` does not exist or does not belong to the partner too-large: The given zone filter exceeds the limit of 250 entries

This API call requires a session that is authenticated with a partner.

A partner can define a zone filter for an usergroup. Every time a user associated with that usergroup initiates an outgoing call, this zone filter is checked and the corresponding cost is applied and subtracted from the usergroup’s credits.

A zone filter consists of a JSON object as shown in the example. It is an array of up to 250 rules, each of which have a description, a number of prefixes that make the rule match if the one of the prefix matches the outgoing phone number, and a cost (in credits per minute).

If a prefix matches, the corresponding cost will be removed from the usergroup’s credits as soon as the call is answered, and will from then on be removed every 60 seconds until the call ends. If the usergroup does not have enough credits left, the call is terminated.

The cost does not have a specific currency associated with it. It might be defined in cents, 1/100 cents or any other metric, as long as the definitions within the usergroup’s credit and the zone filter cost match.

Usually, a partner would periodically add to the credits in a usergroup, to ensure that the users in that group can continue to make outgoing calls.

If a destination number does not match any of the entires, a cost value of 0 is assumed and therefore no credits are used for the particular call.

GET /api/partner/usergroup/(uuid)/zonefilter¶

Get the zone filter of an usergroup.

Response body example

{
    "zonefilter": [
        {
            "description": "national",
            "prefix": ["+49"],
            "cost": 139
        },
        {
            "description": "euro1",
            "prefix": ["+32", "+39", "+44"],
            "cost": 189
        },
        {
            "description": "rest",
            "prefix": [""],
            "cost": 599
        }
    ]
}

Status:	wrong-usergroup: The given usergroup `uuid` does not exist or does not belong to the partner empty-filter: The given usergroup does not have a zone filter

This API call requires a session that is authenticated with a partner.

DELETE /api/partner/usergroup/(uuid)/zonefilter¶

Delete the zone filter of an usergroup.

Response body example

{}

Status:	wrong-usergroup: The given usergroup `uuid` does not exist or does not belong to the partner

This API call requires a session that is authenticated with a partner.

/api/partner/enterprise¶

POST /api/partner/enterprise¶

Creates an enterprise.

Request body example

{
    "description" : "Company"
    "group_prefix_enable" : false
}

JSON Parameters:
	description – `^.{0,200}$` optional: the description for this enterprise group_prefix_enable – `true\|false` optional: enable the usergroups prefix for internal extensions. (default: false)

Response body example

{
    "enterprise_uuid": "9c362cb0-d3cd-11e4-82ed-f8a96351ccd6"
}

This API call requires a session that is authenticated with a partner.

A new enterprise will be created for the partner. The call will return the UUID of the enterprise. If the group_prefix_enable flag is set to true, users have to dial the usergroup’s prefix (POST /api/partner/usergroup/(uuid)) in order to reach users in other usergroups via internal extensions.

GET /api/partner/enterprise¶

Lists all enterprises that belong to the current partner.

Response body example

{
    "enterprises": {
        "93f59fc0-fd4b-11e4-8571-f8a96351ccd6": {
            "description": "",
            "group_prefix_enable": false
        },
        "9c362cb0-d3cd-11e4-82ed-f8a96351ccd6": {
            "description": "Company",
            "group_prefix_enable": false
        }
    }
}

This API call requires a session that is authenticated with a partner.

POST /api/partner/enterprise/(uuid)¶

Updates an enterprise.

Request body example

{
    "description" : "Accounting",
    "group_prefix_enable" : true
}

JSON Parameters:
	description – `^.{0,200}$` optional: the description for this enterprise group_prefix_enable – `true\|false` optional: enable the usergroups prefix for internal extensions.

Response body example

{}

Status:	wrong-enterprise: The given enterprise `uuid` does not exist or does not belong to the partner

This API call requires a session that is authenticated with a partner.

DELETE /api/partner/enterprise/(uuid)¶

Deletes an enterprise

Response body example

{}

Status:	wrong-enterprise: The given enterprise `uuid` does not exist or does not belong to the partner not-empty: The given enterprise `uuid` is not empty.

This API call requires a session that is authenticated with a partner.

An enterprise can only be deleted if there are no associated usergroups.

POST /api/partner/enterprise/(uuid)/usergroup¶

Modifies the list of usergroups in an enterprise.

Request body example

{
    "usergroups": {
        "add": [
            "d322dfe0-9730-11e4-8ff7-f8a96351ccd6",
            "e8ee4030-9730-11e4-8ff7-f8a96351ccd6"
        ],
        "delete": [
            "95336280-ab9f-11e4-bdfb-f8a96351ccd6"
        ]
    }
}

Response body example

{}

Status:	wrong-enterprise: The given enterprise `uuid` does not exist or does not belong to the partner wrong-usergroup: At least one of the usergroups listed does not exist or does not belong to the partner already-grouped: At least one of the usergroups listed in the add section is already listed in another enterprise

This API call requires a session that is authenticated with a partner.

With this API call, usergroups can be grouped into enterprises. Note that each usergroup may only join one enterprise.

/api/partner/sensor¶

GET /api/partner/sensor/event¶

Subscribe the current session to the event flow of sensors associated to the partner.

Query Parameters:
	timeout – optional: expiration timeout of the event flow in seconds. Default: 1 hour (3600 seconds), valid range 1..36000 seconds (10 hours)

Response body example

{}

This API call will enable the flow of partner_sensor_data and partner_sensor_action events to the current session for the specified sensor object. The flow of events will automatically stop after the timeout period. If this behavior is not desired, this API call should be called again before expiration to re-new the timeout period. If there are more than one sessions of the partner subscribing, then the stream will be split between the subscribing sessions and if one of the sessions die, then the corresponding stream is just diverted to other sessions.

DELETE /api/partner/sensor/event¶

Cancel the subscription of the current session to the data events of sensors

Response body example

{}

This API call will stop the flow of sensor data events to the current session.

POST /api/partner/sensor/(sdevice)/action¶

Triggers an action on the sensor sdevice.

The sdevice field carries the hardware address of the sensor device associated with the sensor as a hex encoded string. The model field contains the model identification string of the associated sensor device. If the sensor device belongs to a standardized profile class, this is shown in the profile field.

Request body example

{
    "action": [
        0,
        "Hello, World!"
    ]
}

- or -

{
    "action": [
        1,
        null
    ]
}

Response body example

{
    "action-uuid": "97a1f558-9167-11e2-892a-0024e8f90cc0"
}

Status:	wrong-sensor: The given sdevice does not match a sensor accessible to the current partner sensor-offline: The sensor is currently not visible through any devices, so the action cannot be delivered

The entries in the JSON array action must exactly match the action capabilities of the sensor (see GET /api/partner/sensor/(sdevice)). The type of values in the array depend on the specific action capabilities. In the first example, the sensor has an onoff capability at index 0, which is set to the “off” state (value 0) with this call, and a text capability at index 1 which is instructed to display the string “Hello, World!”. In the second example, the onoff-switch is set to “on”, while the text display remains unchanged.

Note that even though the number of elements in the action array must exactly match the number of action capabilities of the given sensor, a value of null might be given for a specific element to signal that no change is desired for this actor.

If the action was successfully queued to the sensor, the call will return an action UUID. A sensor_action event will be delivered to the current partner session after an acknowledgement message has been received by the sensor to confirm that the action was successfully carried out.

GET /api/partner/sensor/(sdevice)¶

Get information about sensor sdevice

The sdevice field carries the hardware address of the sensor device associated with the sensor as a hex encoded string. The model field contains the model identification string of the associated sensor device. If the sensor device belongs to a standardized profile class, this is shown in the profile field.

Response body example

{
    "sensor": {
        "model": "cospace-sensor",
        "profile": "room-sensor-thm",
        "recv_interval": 60,
        "recv_after_send": true,
        "recv_time": 1363623307,
        "battery_status": 86,
        "mains_power": true,
        "tamper_detect": 1363347807,
        "fault_detect": 1363347820,
        "capabilities": {
            "data": [
                "temperature",
                "motion"
            ],
            "action": [
                "onoff",
                "text"
            ]
        },
        "state": {
            "data": [
                20.5,
                [1, 10, 50]
            ],
            "action": [
                1,
                "Hello, World!"
            ]
        },
        "box": {
            "efd04b02-8fd8-11e2-bf7e-0024e8f90cc0": {
                "time": 1320403260,
                "rssi": -80,
                "lqi": 45
            },
            "f10cb83e-8fd8-11e2-9f7c-0024e8f90cc0": {
                "time": 1320403155,
                "rssi": -38,
                "lqi": 70
            }
        },
    }
}

Status:	wrong-sensor: The given sdevice does not match a sensor accessible to the current partner

The recv_interval field is only present if the sensor is supposed to send data in regular time intervals. It specifies the maximum time interval between sensor transmissions in seconds.

If the recv_after_send field is present, the sensor will receive data only after having transmitted a packet itself. This is typically used in battery powered applications.

The recv_time field contains the timestamp of the last received data from the sensor. It is only present if the sensor has delivered data at least once in its lifetime.

The battery_ok field (type boolean) will be present if the sensor is battery-powered and is capable of signaling a simple “battery ok” (true) or “battery low” (false) condition. If the sensor is capable of reporting detailed battery statistics, the battery_status field will reflect the battery level in percent. The mains_power field might be present if a battery-powered device is currently running on mains power. If the device has the ability to detect a tampering attempt, the tamper_detect field will be present and will show the timestamp of the first detection. Likewise, the presence of the fault_detect field signals a sensor fault condition timestamp.

The box section will list the UUIDs of the box objects that have had contact with the sensor in the last time. Each box will have some meta-information about the connection to the sensor. Possible fields in this section include time (time of the last sensor contact in seconds-since-epoch), rssi (received signal strength indication in dBm) and lqi (link quality indicator, higher value means better signal).

The capabilities section lists the feature attributes of the sensor device.

In the capabilities data subsection, sensor capabilities are displayed as an ordered array of features (thus with an implicit index). The sensor device in the above example has two sensor features, a temperature sensor at index 0 which will yield a temperature in degrees Celsius), and a motion sensor at index 1 which will yield a motion detection duration time in seconds.

In the capabilities action subsection, actor capabilities are displayed as an ordered array of features (thus with an implicit index). The sensor device in the above example has two actor features, a onoff actor at index 0 that can be switched on (1) or off (0) and a text display at index 1.

The following capabilities are defined with their corresponding data format (see GET /api/sensor/(uuid)/data):

temperature: A temperature sensor that has a single JSON number value as data, measured in degree Celsius (°C).
light: An illuminance sensor (typically an ambient light sensor) that has a single JSON number value as data, measured in lux (lx; 1 lx = 1 lm/m² = 1 cd sr/m²).
humidity: A sensor for relative humidity that has a single JSON number value as data, measured in percent.
open: A sensor that monitors the state of an opening such as a door, window, vent or a similar object. The value is a single JSON number that reads 1 if the state is “open”, or 0 if the state is “closed”.
open_percent: A sensor that monitors the state of an opening such as a door, window, vent or a similar object. The value is a percentage, expressed as a single JSON number. The reading is 100 for “open” and 0 if the state is “closed”. Numbers in between signal a half-closed half-open condition.
motion: A motion detection sensor which has a JSON array containing exactly three JSON numbers as data. The first number represents the initial state of the motion sensor (0 for no motion detect, 1 for motion detect), the second number represents a time interval in seconds for this state. The third number represents a time interval for the opposite state. As an example, the data [1, 3, 5] would mean that the initial state of the sensor was “motion detect”, this state lasted for 3 seconds, and afterwards the sensor remained 5 seconds in the state “no motion detect”. The data [0, 100, 1] means that the sensor did not detect motion for 100 seconds, but then a motion detect happened for 1 second.
energy: An energy meter that has a single JSON number value as data, measured in Watt-hours (Wh; 1 Wh = 0.001 kWh = 3600 J [Joule]).
voltage: An electrical voltage sensor that has a single JSON number value as data, measured in Volts (V).
current: An electrical current sensor that has a single JSON number value as data, measured in Amperes (A).
power: An electrical power sensor that has a single JSON number value as data, measured in Watts (W).
power_factor: An electrical power factor. Data is a single JSON number in the range -1..1.
frequency: A frequency counter. The data is represented as a JSON number, measured in Hz (1 Hertz = 1 cycle per second).
onoff: A switch-type sensor that has a single JSON number as a representation. Valid values are 1 (representing the “on” state) and 0 (“off” state).
text: A device that has some sort of text display. The representation is a JSON string which holds the text that is to be displayed with a maximum length of 255 characters.
button: A button-type sensor that has a single JSON number as a representation. There is only one valid value, 1, which represents that the button was pressed.
color_rgb: A color sensor. The data is represented as a JSON array with exactly three JSON numbers, one for each color component: red, green and blue. Values for the individual components range from 0 to 255. As an example, the data [ 255, 255, 0 ] represents a bright yellow.
interval: A time interval expressed as a single JSON number, representing the time period in seconds (s).
datetime: An absolute point in time, expressed as a single JSON number that holds the seconds elapsed since the epoch of Jan 1^st, 1970.
dimmer: A dimmer switch in percent, represented by a single JSON number with values between 0 (completely off) and 100 (completely on).
distance: A physical distance (length), expressed by a single JSON number, representing the distance in meters (m).
mass: A mass, expressed as a single JSON number, representing the mass in kilograms (kg).
mass_flow: A flow rate of mass, expressed as a single JSON number, representing the flow in kilograms per second (kg/s).
volume: A space volume, expressed as a single JSON number, representing the volume in cubic meters (m³).
volume_flow: A flow rate of volume, expressed as a single JSON number, representing the flow in cubic meters per second (m³/s).
fuel_use: A mileage (fuel usage), expressed as a single JSON number, representing the value in liters per 100 km (l/100km).
velocity: A velocity, expressed as a single JSON number, representing the speed in meters per second (m/s).
acceleration: An acceleration, expressed as a single JSON number, representing the speed gain in meters per square second (m/s²).
resistance: An electrical resistance, expressed as a single JSON number, representing the resistance in ohms (Ω).
pressure: A pressure, expressed as a single JSON number, representing the pressure in Pascal (Pa; 1 Pa = 1 N/m²).
force: A force, expressed as a single JSON number, representing the force in Newton (N).
torque: A circular force (torque), expressed as a single JSON number, representing the torque in Newton meters (Nm).
angle: An angle, expressed as a single JSON number, representing the angle in degrees (°, full circle is 360°).
compass: A compass reading, expressed as a single JSON number, in degrees °, clockwise from the north direction (0°) to east (90°), south (180°) and west (270°) back to north (360°).
location: A geographical position. The data is represented as a JSON array with exactly two JSON numbers. The first number represents the longitude, the second number the latitude of the position. Both values are in degrees (°) ranging from -180° to 180°.
concentration: A concentration (ratio of mixture between two components), expressed as a single JSON number, representing the concentration in parts-per-million (ppm).
ph: A pH value, expressed as a single JSON number, representing the pH (no unit, typical values between 1 and 14).
radiation: An ionizing radiation dose. The data is expressed as a single JSON number, representing the dose in Sievert (Sv).
sound_pressure: A sound pressure, expressed as a single JSON number, representing acoustic pressure in dezibels (dB).
level: An otherwise unspecified logarithmic level, expressed as a single JSON number, representing the level in dezibels (dB).
alarm: An alarm sensor. The data is expressed as a single JSON number. Valid values are 0 (“no alarm” state) and 1 (“alarm” state).
gauge: An otherwise unspecified absolute value, expressed as a single JSON number.
counter: An otherwise unspecified counter value, expressed as a single JSON number.
load: An load percentage value, expressed as a single JSON number, representing the load in percent (%).
cycles: A rotary speed value, expressed as a single JSON number, representing the rotary speed in cycles per second (1/s).
binary_8bit: An otherwise unspecified value, expressed as a single JSON integer number with a range between 0 and 255.
binary_16bit: An otherwise unspecified value, expressed as a single JSON integer number with a range between 0 and 65535.
binary_32bit: An otherwise unspecified value, expressed as a single JSON integer number with a range between 0 and 4294967295.
octets: An otherwise unspecified array of octets (binary string), expressed as a single JSON string in Base64 encoding.

The state section contains the most recent up-to-date status of the sensor and action elements. Its structure matches the capabilities section. While the GET /api/sensor/(uuid)/data and GET /api/sensor/(uuid)/action calls can be used to get the precise time series of sensor data and actions, the state section represents the current state of each of the data and action items. For the data items, this is the last sensor data update which was not null, and the the action items, this is that last action command which was not null.

Partner events¶

Event cdr¶

When a user from a partner generates a cdr event, this event is delivered to the elected partner sessions that requested the delivery of events with GET /api/partner/cdr/event.

{
    "cdr": {
        "phone": "+492216698712",
        "id": "2b5e1560-124f-11e4-b449-f8a96351ccd6",
        "date": 1406109196726
        "service": "call",
        "b_number": "+492216698711",
        "t_pre": 4,
        "t_post: 107
    }
}

Event partner_sensor_data¶

When a sensor from a partner delivers data to the cloud, this event is delivered to the elected partner sessions that requested the delivery of sensor data events with GET /api/partner/sensor/event.

{
    "sensor": "ce19884c",
    "data": {
        "1363623247000": [
            20.5,
            [
                0,
                255
            ]
        ]
    }
}

The sensor field holds the sdevice of the sensor object.

The data section lists the new sensor data, typically a single entry.

Event partner_sensor_action¶

When an action was carried out on a sensor, this event is delivered to the partner session that invoked GET /api/partner/sensor/event.

{
    "status": "ok",
    "sensor": "ce19884c",
    "action": {
        "1363623253000": [
            1,
            null
        ]
    },
    "action-uuid": "97a1f558-9167-11e2-892a-0024e8f90cc0"
}

The status field contains ok if the action was carried out. It might contain replaced if the action was superseded by another action while waiting for the sensor to become available for radio transmittion.

The action section lists the action that was carried out, typically a single entry.

The action-uuid field holds the action UUID that corresponds to the action-uuid field in the response of the POST /api/partner/sensor/(sdevice)/action call.

Partner API¶

API Call Reference¶

/api/partner/user¶

/api/partner/phone¶

/api/partner/callfilter¶

/api/partner/cdr¶

/api/partner/emergency¶

/api/partner/usergroup¶

/api/partner/enterprise¶

/api/partner/sensor¶

Partner events¶

Event cdr¶

Event partner_sensor_data¶

Event partner_sensor_action¶

Table of Contents

Related Topics

API email update