REST API Documentation

Introduction to sipgate REST API

Mit der sipgate API bieten wir Ihnen die Möglichkeit, zentrale sipgate Funktionen innerhalb Ihrer eigenen Software- oder Web-Projekte zu verwenden. Auf diesen Seiten finden Sie eine ausführliche Dokumentation der sipgate API und Beispiele für die Nutzung der Schnittstelle in verschiedenen Programmiersprachen. Die sipgate API steht zur freien Verfügung und kann kostenlos genutzt werden. Beachten Sie jedoch, dass wir für Entwicklungen, die auf der sipgate REST-API basieren keinen Support anbieten.

Functions overview

TITLE	DESCRIPTION	RESSOURCE
Request all numbers for a given account	Request all user provided numbers for a given account.	/{userId}/settings/numbers
Get numbers, that belong to the account	Get every single number from account	/{userId}/settings/numbers/list
Get and set outgoing numbers	Get and set outgoing numbers	/{userId}/settings/numbers/outgoing
listing of extensions	A listing of the authenticated user's extensions. The list covers sms-, fax-, voicemail-, register- and external-extensions: Sms-extensions represent sms-endpoints providing functionality for sms-sending and, depending on the contract, may also allow for receiving sms-messages. Fax-extensions represent fax-endpoints providing functionality for fax-sending and -receiving. Voicemail-extensions represent voicemail-boxes. register-extensions represent sip-endpoints to which adequate hard- or softphones may be registered. External-extensions represent phone-endpoints that are mapped to non-sipgate phone-numbers like landlines or mobile phones.	/{userId}/settings/extensions
extension data	Information about a single specific extension that is specified via the 'extensionId' that is part of its resource path.	/{userId}/settings/extensions/{extensionId}
Get and set extension's DND status	You can get and set the DND status of extensions	/{userId}/settings/extensions/{extensionId}/dnd
base product type	Information about the base product type	/{userId}/settings/baseproducttype
registered mobile devices	Information about the registered mobile devices	/{userId}/settings/registeredmobiledevices
Setup mobile extension	Setup a mobile extension with information about the device.	/{userId}/settings/mobile/extensions
Request a GSM-Code	Request a GSM-Code for Unified Voicemail Redirection: Forward all conditional calls to the sipgate voicemail system.	/{userId}/settings/mobile/extensions/unifiedvoicemailgsmcode
Events	Listing of all events the authorized user has rights on. Events represent calls, faxes, voicemails and sms. This resource provides generic information, specific information that is dependent on the type of represented Events may be accessed via the type-specific event resources (see below).	/{userId}/events
Call Events	Listing of all call events the authorized user has rights on.	/{userId}/events/calls
Single Call Event	handles a specified call event	/{userId}/events/calls/{callId}
handles the 'read' property	Can be used to get or set the 'read' property of a specific call event	/{userId}/events/calls/{callId}/read
handles the 'starred' property	Can be used to get or set the 'starred' property of a specific call event	/{userId}/events/calls/{callId}/starred
Fax Events	Listing of all fax events the authorized user has rights on.	/{userId}/events/faxes
Single fax event	Handles a specified fax event	/{userId}/events/faxes/{faxId}
handles the 'read' property	Can be used to get or set the 'read' property of a specific fax event	/{userId}/events/faxes/{faxId}/read
handles the 'starred' property	Can be used to get or set the 'starred' property of a specific fax event	/{userId}/events/faxes/{faxId}/starred
Fax preview in different sizes	Returns fax previews in different sizes <`big, small`>	/{userId}/events/faxes/{faxId}/preview/{page}/{size}
Fax content	Returns fax pdf or tiff	/{userId}/events/faxes/{faxId}/content
SMS Events	Listing of all sms events the authorized user has rights on.	/{userId}/events/sms
Single SMS Event	Handles a specific sms event specified by smsId	/{userId}/events/sms/{smsId}
handles the 'read' property	Can be used to get or set the 'read' property of a specific sms event	/{userId}/events/sms/{smsId}/read
handles the 'starred' property	Can be used to get or set the 'starred' property of a specific SMS event	/{userId}/events/sms/{smsId}/starred
Voicemail Events	Listing of all voicemail events the authorized user has rights on.	/{userId}/events/voicemails
Single Voicemail Event	Using the HTTP GET method a specific fax event can be requested that is specified via the 'faxId' variable that is part of it's resource path.	/{userId}/events/voicemails/{voicemailId}
handles the 'read' property	Can be used to get or set the 'read' property of a specific voicemail event	/{userId}/events/voicemails/{voicemailId}/read
handles the 'starred' property	Can be used to get or set the 'starred' property of a specific voicemail event	/{userId}/events/voicemails/{voicemailId}/starred
Voicemail Content	Can be used to retrieve the content of a voicemail	/{userId}/events/voicemails/{voicemailId}/content
List of calls	Do some action on a list of calls	/{userId}/sessions/calls
A specified call	Use the `{sessionId}` to identify a specified call	/{userId}/sessions/calls/{sessionId}
Record a call	Use the `{sessionId}` to start or stop recording a running call	/{userId}/sessions/calls/{sessionId}/recording
Park a call	Use the`{sessionId}` and the`{memberId}` to park a specified call	/{userId}/sessions/calls/{sessionId}/member/{memberId}/parking
Sets temporary callthrough routing	Sets temporary callthrough routing for a specific caller number. Calls from this number to the number returned by this resource will be forwarded to the specified target number. Timeframe to start a call defaults to 30 seconds.	/{userId}/sessions/callthrough
Contacts	Contacts of a user. The output/input is very near to the vCard specification to allow developers interact easier with different contact systems.	/{userId}/contacts
Single contact	Same feature as above with a limit for one contact, specified in contactId	/{userId}/contacts/{contactId}
phonebook for specific vendor	retrieve a phonebook xml file for 'snom' or 'grandstream'	/{userId}/contacts/phonebook/{vendorName}
balance	current balance of the identified account	/{userId}/billing/balance

Detailed function description

Request all numbers for a given account

Description:
Request all user provided numbers for a given account.

URL

/{userId}/settings/numbers

parameter	type	description
{userId}	string (required)	internal id of webuser. my is an alias for logged in user, so preferably take this.

Methods

GET /{userId}/settings/numbers/

Request all numbers for a given account
Request all user provided numbers for a given account.

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
complexity	string	Specifies the complexity of the result

Example request

Response

struct Numbers
- boolean allowAdd
- boolean allowEmptyOadc
- struct phonenumbers

Get numbers, that belong to the account

Description:
Get every single number from account

URL

/{userId}/settings/numbers/list

parameter	type	description
{userId}	string (required)	internal id of webuser. my is an alias for logged in user, so preferably take this.

Methods

GET /{userId}/settings/numbers/list/

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
complexity	string	Specifies the complexity of the result

Example request

Response

struct AccountNumbers

Get and set outgoing numbers

Description:
Get and set outgoing numbers

URL

/{userId}/settings/numbers/outgoing

parameter	type	description
{userId}	string (required)	internal id of webuser. my is an alias for logged in user, so preferably take this.

Methods

GET /{userId}/settings/numbers/outgoing/

get outgoing numbers of account
returns all outgoing numbers

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
complexity	string	Specifies the complexity of the result

Example request

Response

struct outgoingNumber

POST /{userId}/settings/numbers/outgoing/

set outgoing numbers of a specific extension
set a number of a specific extension

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
clip	boolean	false to set number to anonymous
number	string	account's number or userProvided number. for e164 format use `tel:` as prefix.
extensionId	string (required)	extensionId for the settings

Example request

listing of extensions

Description:
A listing of the authenticated user's extensions. The list covers sms-, fax-, voicemail-, register- and external-extensions:

Sms-extensions represent sms-endpoints providing functionality for sms-sending and, depending on the contract, may also allow for receiving sms-messages.
Fax-extensions represent fax-endpoints providing functionality for fax-sending and -receiving.
Voicemail-extensions represent voicemail-boxes.
register-extensions represent sip-endpoints to which adequate hard- or softphones may be registered.
External-extensions represent phone-endpoints that are mapped to non-sipgate phone-numbers like landlines or mobile phones.

URL

/{userId}/settings/extensions

parameter	type	description
{userId}	string (required)	internal id of webuser. my is an alias for logged in user, so preferably take this.

Methods

GET /{userId}/settings/extensions/

get listing of extensions
Using the HTTP GET method on this resource, a listing of the authenticated user's extensions (see resource description), can be optained.

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
complexity	string	Specifies the complexity of the result

Example request

Response

struct extensions
- array extensions
  collection of extension elements
  - struct
    - string extensionId
      identifier of the extension
    - string alias
      human readable alias of the extension which may be specified by the user or the system default (e.g. 'Joe's voicemail')
    - string type
      the type of the extension which may be one of 'sms', 'fax', 'voicemail', 'register', or 'external'
    - struct resource
      resource for requesting or optionally modifiying the extension
    - array incomingNumbers
      numbers mapped to the extension for incoming connections
      - string
    - array directDialNumbers
      direct dial numbers mapped to the extension
      - string
    - boolean dnd
      state of the extension's 'Do Not Disturb' flag; when true the extension is not active / can not be reached
    - struct outgoingNumber
      outgoing number mapped to the extension
    - array devices
      for register-extension this is a listing of devices currently registered to the extension
      - struct

extension data

Description:
Information about a single specific extension that is specified via the 'extensionId' that is part of its resource path.

URL

/{userId}/settings/extensions/{extensionId}

parameter	type	description
{userId}	string (required)	internal id of webuser. my is an alias for logged in user, so preferably take this.
extensionId	string (required)	undocumented

Methods

GET /{userId}/settings/extensions/{extensionId}/

get specific extension
Using the HTTP GET method on this resource, data of a specific extension (see '/{userId}/settings/extensions/' resource description), can be optained.

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
complexity	string	Specifies the complexity of the result

Example request

Response

struct extension
- string extensionId
  identifier of the extension
- string alias
  human readable alias of the extension which may be specified by the user or the system default (e.g. 'Joe's voicemail')
- string type
  the type of the extension which may be one of 'sms', 'fax', 'voicemail', 'register', or 'external'
- struct resource
  resource for requesting or optionally modifiying the extension
- array incomingNumbers
  numbers mapped to the extension for incoming connections
  - string
- array directDialNumbers
  direct dial numbers mapped to the extension
  - string
- boolean dnd
  state of the extension's 'Do Not Disturb' flag; when true the extension is not active / can not be reached
- struct outgoingNumber
  outgoing number mapped to the extension
- array devices
  for register-extension this is a listing of devices currently registered to the extension
  - struct
- string sipPassword ~~SIMPLE~~
  for register-extensions this contains the SIP password to be used for registration
- string registerUrl ~~SIMPLE~~
  for register-extensions this contains the SIP registrar server name
- string outboundProxyUrl ~~SIMPLE~~
  for register-extensions this contains the SIP outbound proxy server
- boolean faxIn ~~SIMPLE~~
  for fax-extensions this shows whether incoming fax is available with this extension
- string pin ~~SIMPLE~~
  for voicemail-extensions this contains the PIN to be used for listening to messages on the phone
- string timezone ~~SIMPLE~~
  for voicemail-extensions this contains the configured timezone
- string announcementUrl ~~SIMPLE~~
  for voicemail-extensions this contains the URL from which the current announcement can be downloaded
- string provider ~~SIMPLE~~
  for external-extensions this contains the provider of the external line
- string externalPhonenumber ~~SIMPLE~~
  for external-extensions this contains the phone-number of the external line
- string deviceId ~~SIMPLE~~

Get and set extension's DND status

Description:
You can get and set the DND status of extensions

URL

/{userId}/settings/extensions/{extensionId}/dnd

parameter	type	description
{userId}	string (required)	internal id of webuser. my is an alias for logged in user, so preferably take this.

Methods

GET /{userId}/settings/extensions/{extensionId}/dnd/

get DND status of a specific extension
Using the HTTP GET method on this resource returns true if the extension is set to DND and false if the extension is available.

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
complexity	string	Specifies the complexity of the result

Example request

Response

struct dnd
- boolean value
  Returns the DND status of the extension

POST /{userId}/settings/extensions/{extensionId}/dnd/

set DND status of a specific extension
Using the HTTP POST method on this resource sets the specified extension to DND if value is true.

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
value	boolean (required)	true if you want to set DND, false if you want to unset DND

Example request

base product type

Description:
Information about the base product type

URL

/{userId}/settings/baseproducttype

parameter	type	description
{userId}	string (required)	internal id of webuser. my is an alias for logged in user, so preferably take this.

Methods

GET /{userId}/settings/baseproducttype/

get base product type
Using the HTTP GET method on this resource returns the base product type

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
complexity	string	Specifies the complexity of the result

Example request

Response

struct extension
- string extensionId
  identifier of the extension
- string alias
  human readable alias of the extension which may be specified by the user or the system default (e.g. 'Joe's voicemail')
- string type
  the type of the extension which may be one of 'sms', 'fax', 'voicemail', 'register', or 'external'
- struct resource
  resource for requesting or optionally modifiying the extension
- array incomingNumbers
  numbers mapped to the extension for incoming connections
  - string
- array directDialNumbers
  direct dial numbers mapped to the extension
  - string
- boolean dnd
  state of the extension's 'Do Not Disturb' flag; when true the extension is not active / can not be reached
- struct outgoingNumber
  outgoing number mapped to the extension
- array devices
  for register-extension this is a listing of devices currently registered to the extension
  - struct
- string sipPassword ~~SIMPLE~~
  for register-extensions this contains the SIP password to be used for registration
- string registerUrl ~~SIMPLE~~
  for register-extensions this contains the SIP registrar server name
- string outboundProxyUrl ~~SIMPLE~~
  for register-extensions this contains the SIP outbound proxy server
- boolean faxIn ~~SIMPLE~~
  for fax-extensions this shows whether incoming fax is available with this extension
- string pin ~~SIMPLE~~
  for voicemail-extensions this contains the PIN to be used for listening to messages on the phone
- string timezone ~~SIMPLE~~
  for voicemail-extensions this contains the configured timezone
- string announcementUrl ~~SIMPLE~~
  for voicemail-extensions this contains the URL from which the current announcement can be downloaded
- string provider ~~SIMPLE~~
  for external-extensions this contains the provider of the external line
- string externalPhonenumber ~~SIMPLE~~
  for external-extensions this contains the phone-number of the external line
- string deviceId ~~SIMPLE~~

registered mobile devices

Description:
Information about the registered mobile devices

URL

/{userId}/settings/registeredmobiledevices

parameter	type	description
{userId}	string (required)	internal id of webuser. my is an alias for logged in user, so preferably take this.

Methods

GET /{userId}/settings/registeredmobiledevices/

get all registered mobile devices
Using the HTTP GET method on this resource returns the registered mobile devices

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
complexity	string	Specifies the complexity of the result

Example request

Setup mobile extension

Description:
Setup a mobile extension with information about the device.

URL

/{userId}/settings/mobile/extensions

parameter	type	description
{userId}	string (required)	internal id of webuser. my is an alias for logged in user, so preferably take this.

Methods

GET /{userId}/settings/mobile/extensions/

get all mobile extensions
Using the HTTP GET method on this resource returns all mobile extensions.

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
complexity	string	Specifies the complexity of the result

Example request

POST /{userId}/settings/mobile/extensions/

setup specific extension
Using the HTTP POST method on this resource, you can setup a mobile extension.

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
phoneNumber	string (required)	phoneNumber of the mobile extension
model	string (required)	model of the mobile extension
vendor	string (required)	vendor of the mobile extension
firmware	string (required)	firmware of the mobile extension

Example request

Request a GSM-Code

Description:
Request a GSM-Code for Unified Voicemail Redirection: Forward all conditional calls to the sipgate voicemail system.

URL

/{userId}/settings/mobile/extensions/unifiedvoicemailgsmcode

parameter	type	description
{userId}	string (required)	internal id of webuser. my is an alias for logged in user, so preferably take this.

Methods

GET /{userId}/settings/mobile/extensions/unifiedvoicemailgsmcode/

Request a GSM Code
Using the HTTP GET method on this resource, you can request the GSM Code for conditional forwarding of your mobile phone to your sipgate voicemail.

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
complexity	string	Specifies the complexity of the result
state	string (required)	set to 'activate' / 'deactivate'

Example request

Events

Description:
Listing of all events the authorized user has rights on. Events represent calls, faxes, voicemails and sms. This resource provides generic information, specific information that is dependent on the type of represented Events may be accessed via the type-specific event resources (see below).

URL

/{userId}/events

parameter	type	description
{userId}	string (required)	internal id of webuser. my is an alias for logged in user, so preferably take this.

Methods

GET /{userId}/events/

get all events for authenticated user
Returns all events the authorized user has rights on including calls, faxes, voicemails and sms. To filter by event refer to event's subresources.

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
complexity	string	Specifies the complexity of the result

Example request

Response

struct eventlist
- array events
  collection of user's events
  - struct
    - string id
      unique identifier of the event
    - string comment
      user defined comment
    - string created
      creation date of the event
    - string scheduled
      scheduled time to send
    - string direction
      in/out
    - struct labels
      commaseperated list of labels
    - string location
      event's target (inbox, sent, archive, trash)
    - string get
      link to attached ressource (PDF, MP3)
    - string modify
      link to modify event
    - struct read
      marks the event as read/unread
      - string get
      - string modify
      - boolean value
    - struct starred
      marks the event as important/unimportant
      - string get
      - string modify
      - boolean value
    - string status
      event's state (failed, sent, pending, scheduled)
    - array sources
      event's source (calles number in case of calls)
      - struct
        
        string numberE164
        number in E.164 format
        
        string numberPretty
        number in human readable pretty format
        
        string contactFN
        'FN' (e.g. 'John Doe') entry of the contact matching this endpoint as it is stored in the account's contacts database.
        
        string get
        Reference to the contact's resource in the account's contacts database.
    - array targets
      event's target (called number in case of calls)
      - struct
        
        string numberE164
        number in E.164 format
        
        string numberPretty
        number in human readable pretty format
        
        string contactFN
        'FN' (e.g. 'John Doe') entry of the contact matching this endpoint as it is stored in the account's contacts database.
        
        string get
        Reference to the contact's resource in the account's contacts database.
    - struct extension
      internal endpoint, that handeled the event
      - string id
      - string alias
      - string get
- integer overallCount
  The overall number of events available. While the output may be limited (e.g. for pagination) this covers all that match the request criteria.
- integer count
  Number of elements returned in the result set.

Call Events

Description:
Listing of all call events the authorized user has rights on.

URL

/{userId}/events/calls

parameter	type	description
{userId}	string (required)	internal id of webuser. my is an alias for logged in user, so preferably take this.

Methods

GET /{userId}/events/calls/

get all call events for authenticated user
Returns all call events the authorized user has rights on.

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
complexity	string	Specifies the complexity of the result

Example request

Response

struct events
- array calls
  collection of call elements
  - struct
    - string id
      unique identifier of the event
    - string comment
      user defined comment
    - string created
      creation date of the event
    - string scheduled
      scheduled time to send
    - string direction
      in/out
    - struct labels
      commaseperated list of labels
    - string location
      event's target (inbox, sent, archive, trash)
    - string get
      link to attached ressource (PDF, MP3)
    - string modify
      link to modify event
    - struct read
      marks the event as read/unread
      - string get
      - string modify
      - boolean value
    - struct starred
      marks the event as important/unimportant
      - string get
      - string modify
      - boolean value
    - string status
      event's state (failed, sent, pending, scheduled)
    - array sources
      event's source (calles number in case of calls)
      - struct
        
        string numberE164
        number in E.164 format
        
        string numberPretty
        number in human readable pretty format
        
        string contactFN
        'FN' (e.g. 'John Doe') entry of the contact matching this endpoint as it is stored in the account's contacts database.
        
        string get
        Reference to the contact's resource in the account's contacts database.
    - array targets
      event's target (called number in case of calls)
      - struct
        
        string numberE164
        number in E.164 format
        
        string numberPretty
        number in human readable pretty format
        
        string contactFN
        'FN' (e.g. 'John Doe') entry of the contact matching this endpoint as it is stored in the account's contacts database.
        
        string get
        Reference to the contact's resource in the account's contacts database.
    - struct extension
      internal endpoint, that handeled the event
      - string id
      - string alias
      - string get
- integer overallCount
  The overall number of events available. While the output may be limited (e.g. for pagination) this covers all that match the request criteria.
- integer count
  Number of elements returned in the result set.

Single Call Event

Description:
handles a specified call event

URL

/{userId}/events/calls/{callId}

parameter	type	description
{userId}	string (required)	internal id of webuser. my is an alias for logged in user, so preferably take this.
callId	string (required)	undocumented

Methods

GET /{userId}/events/calls/{callId}/

get a specific call event
Returns one call referenced by {callId}

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
complexity	string	Specifies the complexity of the result

Example request

Response

struct call
- string id
  unique identifier of the event
- string comment
  user defined comment
- string created
  creation date of the event
- string scheduled
  scheduled time to send
- string direction
  in/out
- struct labels
  commaseperated list of labels
- string location
  event's target (inbox, sent, archive, trash)
- string get
  link to attached ressource (PDF, MP3)
- string modify
  link to modify event
- struct read
  marks the event as read/unread
  - string get
  - string modify
  - boolean value
- struct starred
  marks the event as important/unimportant
  - string get
  - string modify
  - boolean value
- string status
  event's state (failed, sent, pending, scheduled)
- array sources
  event's source (calles number in case of calls)
  - struct
    - string numberE164
      number in E.164 format
    - string numberPretty
      number in human readable pretty format
    - string contactFN
      'FN' (e.g. 'John Doe') entry of the contact matching this endpoint as it is stored in the account's contacts database.
    - string get
      Reference to the contact's resource in the account's contacts database.
- array targets
  event's target (called number in case of calls)
  - struct
    - string numberE164
      number in E.164 format
    - string numberPretty
      number in human readable pretty format
    - string contactFN
      'FN' (e.g. 'John Doe') entry of the contact matching this endpoint as it is stored in the account's contacts database.
    - string get
      Reference to the contact's resource in the account's contacts database.
- struct extension
  internal endpoint, that handeled the event
  - string id
  - string alias
  - string get

DELETE /{userId}/events/calls/{callId}/

deletes a specific call event
Moves a call referenced by {callId} to trash

Parameters

parameter	type	description
version	string (required)	Specifies the handler version

Example request

PUT /{userId}/events/calls/{callId}/

Add label to a call event
Using the HTTP PUT method on this resource, the label of a specific call event can be set. The event is specified via the 'callId' variable that is part of it's resource path. The value the attribute is to be set to is specified by the 'value' query parameter documented below.

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
value	string	Set the name of the label to be added.

Example request

handles the 'read' property

Description:
Can be used to get or set the 'read' property of a specific call event

URL

/{userId}/events/calls/{callId}/read

parameter	type	description
{userId}	string (required)	internal id of webuser. my is an alias for logged in user, so preferably take this.

Methods

GET /{userId}/events/calls/{callId}/read/

gets the 'read' property of a specific call event
returns whether or not a specific call event has been marked as 'read'. Please note: the event can be also marked as read/unread on the sipgate website.

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
complexity	string	Specifies the complexity of the result

Example request

Response

struct property
- string name
  the name of our property
- struct value
  the value of our property

PUT /{userId}/events/calls/{callId}/read/

sets the 'read' property of a specific call event
Using the HTTP PUT method on this resource, a specific call event can been marked as 'read' or 'unread'. Please note: the event can be also marked as read/unread on the sipgate website.

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
value	boolean	Set the call event to 'read' (true) or 'unread' (false).

Example request

handles the 'starred' property

Description:
Can be used to get or set the 'starred' property of a specific call event

URL

/{userId}/events/calls/{callId}/starred

parameter	type	description
{userId}	string (required)	internal id of webuser. my is an alias for logged in user, so preferably take this.

Methods

GET /{userId}/events/calls/{callId}/starred/

gets the 'starred' property of a specific call event
returns whether or not a specific call event has been marked as 'starred'. Please note: the event can be also marked as starred/unstarred on the sipgate website.

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
complexity	string	Specifies the complexity of the result

Example request

Response

struct property
- string name
  the name of our property
- struct value
  the value of our property

PUT /{userId}/events/calls/{callId}/starred/

sets the 'starred' property of a specific call event
Using the HTTP PUT method on this resource, a specific call event can been marked as 'starred'. Please note: the event can be also marked as starred/unstarred on the sipgate website.

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
value	boolean	Set the call event to 'starred' (true) or 'unstarred' (false).

Example request

Fax Events

Description:
Listing of all fax events the authorized user has rights on.

URL

/{userId}/events/faxes

parameter	type	description
{userId}	string (required)	internal id of webuser. my is an alias for logged in user, so preferably take this.

Methods

GET /{userId}/events/faxes/

get all fax events for authenticated user
Returns all fax events the authorized user has rights on.

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
complexity	string	Specifies the complexity of the result

Example request

Response

struct eventlist
- array events
  collection of fax elements
  - struct
    - array previews
      list of the previews of the fax's pages
      - struct
        
        integer pageNumber
        pagenumber of the referenced fax-page
        
        struct small
        resource referencing the fax-page content in small version
        
        struct big
        resource referencing the fax-page content in big version
    - integer pageCount
      the number of pages the fax consists of
    - string sent
      date and time (with user's timezone) the fax was sent
    - struct content
      resource that provides the fax content
    - string failReason
      reason of failure (set only if an error has occurred)
    - string id
      unique identifier of the event
    - string comment
      user defined comment
    - string created
      creation date of the event
    - string scheduled
      scheduled time to send
    - string direction
      in/out
    - struct labels
      commaseperated list of labels
    - string location
      event's target (inbox, sent, archive, trash)
    - string get
      link to attached ressource (PDF, MP3)
    - string modify
      link to modify event
    - struct read
      marks the event as read/unread
      - string get
      - string modify
      - boolean value
    - struct starred
      marks the event as important/unimportant
      - string get
      - string modify
      - boolean value
    - string status
      event's state (failed, sent, pending, scheduled)
    - array sources
      event's source (calles number in case of calls)
      - struct
        
        string numberE164
        number in E.164 format
        
        string numberPretty
        number in human readable pretty format
        
        string contactFN
        'FN' (e.g. 'John Doe') entry of the contact matching this endpoint as it is stored in the account's contacts database.
        
        string get
        Reference to the contact's resource in the account's contacts database.
    - array targets
      event's target (called number in case of calls)
      - struct
        
        string numberE164
        number in E.164 format
        
        string numberPretty
        number in human readable pretty format
        
        string contactFN
        'FN' (e.g. 'John Doe') entry of the contact matching this endpoint as it is stored in the account's contacts database.
        
        string get
        Reference to the contact's resource in the account's contacts database.
    - struct extension
      internal endpoint, that handeled the event
      - string id
      - string alias
      - string get
- integer overallCount
  The overall number of events available. While the output may be limited (e.g. for pagination) this covers all that match the request criteria.
- integer count
  Number of elements returned in the result set.

POST /{userId}/events/faxes/

Send a fax
POST to this request with a binary encoded pdf to send a fax to specified targets with an optional schedule parameter. Please keep in mind that the correct content-type (i.e. 'application/pdf') needs to be set.

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
extension	string	fax extension to send and bill the fax from
target	string	String containing the fax phone numbers of the fax recipients. (May be provided multiple times.)
source	string	Source telephone number
schedule	string	Array of strings containing the UTC date and time when the fax should be sent. Format: 'YYYY-MM-DD HH:MM:SS' Please note: currently only one value is allowed in this array.

Example request

Single fax event

Description:
Handles a specified fax event

URL

/{userId}/events/faxes/{faxId}

parameter	type	description
{userId}	string (required)	internal id of webuser. my is an alias for logged in user, so preferably take this.
faxId	string (required)	undocumented

Methods

GET /{userId}/events/faxes/{faxId}/

request specific fax event
Using the HTTP GET method a specific fax event can be requested that is specified via the 'faxId' variable that is part of it's resource path.

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
complexity	string	Specifies the complexity of the result

Example request

Response

struct fax
- array previews
  list of the previews of the fax's pages
  - struct
    - integer pageNumber
      pagenumber of the referenced fax-page
    - struct small
      resource referencing the fax-page content in small version
    - struct big
      resource referencing the fax-page content in big version
- integer pageCount
  the number of pages the fax consists of
- string sent
  date and time (with user's timezone) the fax was sent
- struct content
  resource that provides the fax content
- string failReason
  reason of failure (set only if an error has occurred)
- string id
  unique identifier of the event
- string comment
  user defined comment
- string created
  creation date of the event
- string scheduled
  scheduled time to send
- string direction
  in/out
- struct labels
  commaseperated list of labels
- string location
  event's target (inbox, sent, archive, trash)
- string get
  link to attached ressource (PDF, MP3)
- string modify
  link to modify event
- struct read
  marks the event as read/unread
  - string get
  - string modify
  - boolean value
- struct starred
  marks the event as important/unimportant
  - string get
  - string modify
  - boolean value
- string status
  event's state (failed, sent, pending, scheduled)
- array sources
  event's source (calles number in case of calls)
  - struct
    - string numberE164
      number in E.164 format
    - string numberPretty
      number in human readable pretty format
    - string contactFN
      'FN' (e.g. 'John Doe') entry of the contact matching this endpoint as it is stored in the account's contacts database.
    - string get
      Reference to the contact's resource in the account's contacts database.
- array targets
  event's target (called number in case of calls)
  - struct
    - string numberE164
      number in E.164 format
    - string numberPretty
      number in human readable pretty format
    - string contactFN
      'FN' (e.g. 'John Doe') entry of the contact matching this endpoint as it is stored in the account's contacts database.
    - string get
      Reference to the contact's resource in the account's contacts database.
- struct extension
  internal endpoint, that handeled the event
  - string id
  - string alias
  - string get

PUT /{userId}/events/faxes/{faxId}/

Add label to a fax event
Using the HTTP PUT method on this resource, the label of a specific fax event can be set. The event is specified via the 'callId' variable that is part of it's resource path. The value the attribute is to be set to is specified by the 'value' query parameter documented below.

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
value	string	The name of the label to be added.

Example request

DELETE /{userId}/events/faxes/{faxId}/

delete a specific fax event
Using the HTTP DELETE method on this resource, a specific fax event that is specified via the 'faxId' variable that is part of it's resource path.

Parameters

parameter	type	description
version	string (required)	Specifies the handler version

Example request

handles the 'read' property

Description:
Can be used to get or set the 'read' property of a specific fax event

URL

/{userId}/events/faxes/{faxId}/read

parameter	type	description
{userId}	string (required)	internal id of webuser. my is an alias for logged in user, so preferably take this.

Methods

GET /{userId}/events/faxes/{faxId}/read/

request 'read' attribute
Using the HTTP GET method on this resource, the 'read' attribute of a specific fax event can be requested. The event is specified via the 'faxId' variable that is part of it's resource path.

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
complexity	string	Specifies the complexity of the result

Example request

Response

struct property
- string name
  the name of our property
- struct value
  the value of our property

PUT /{userId}/events/faxes/{faxId}/read/

set 'read' attribute
Using the HTTP PUT method on this resource, the 'read' attribute of a specific fax event can be set. The event is specified via the 'faxId' variable that is part of it's resource path. The value the attribute is to be set to is specified by the 'value' query parameter documented below.

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
value	boolean (required)	Boolean value the 'read' property to be set to. (true = read, false = unread)

Example request

handles the 'starred' property

Description:
Can be used to get or set the 'starred' property of a specific fax event

URL

/{userId}/events/faxes/{faxId}/starred

parameter	type	description
{userId}	string (required)	internal id of webuser. my is an alias for logged in user, so preferably take this.

Methods

GET /{userId}/events/faxes/{faxId}/starred/

request 'starred' attribute
Using the HTTP GET method on this resource, the 'starred' attribute of a specific fax event can be requested. The event is specified via the 'faxId' variable that is part of it's resource path.

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
complexity	string	Specifies the complexity of the result

Example request

Response

struct property
- string name
  the name of our property
- struct value
  the value of our property

PUT /{userId}/events/faxes/{faxId}/starred/

set 'starred' attribute
Using the HTTP PUT method on this resource, the 'starred' attribute of a specific fax event can be set. The event is specified via the 'faxId' variable that is part of it's resource path. The value the attribute is to be set to is specified by the 'value' query parameter documented below.

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
value	boolean (required)	Boolean value the 'starred' property to be set to.

Example request

Fax preview in different sizes

Description:
Returns fax previews in different sizes <big, small>

URL

/{userId}/events/faxes/{faxId}/preview/{page}/{size}

parameter	type	description
{userId}	string (required)	internal id of webuser. my is an alias for logged in user, so preferably take this.
size	string (required)	undocumented

Methods

GET /{userId}/events/faxes/{faxId}/preview/{page}/{size}/

Get fax preview in different sizes
Returns fax previews in different sizes <big, small>

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
complexity	string	Specifies the complexity of the result

Example request

Response

struct page
- integer pageNumber
  pagenumber of the referenced fax-page
- struct small
  resource referencing the fax-page content in small version
- struct big
  resource referencing the fax-page content in big version

Fax content

Description:
Returns fax pdf or tiff

URL

/{userId}/events/faxes/{faxId}/content

parameter	type	description
{userId}	string (required)	internal id of webuser. my is an alias for logged in user, so preferably take this.

Methods

GET /{userId}/events/faxes/{faxId}/content/

Get fax pdf or tiff
Returns fax pdf or tiff

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
complexity	string	Specifies the complexity of the result
format	string	Specify the desired format: 'application/pdf' or 'image/tiff'. Default is 'application/pdf'.

Example request

SMS Events

Description:
Listing of all sms events the authorized user has rights on.

URL

/{userId}/events/sms

parameter	type	description
{userId}	string (required)	internal id of webuser. my is an alias for logged in user, so preferably take this.

Methods

GET /{userId}/events/sms/

Get all SMS events
Returns all SMS events the authorized user has rights on.

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
complexity	string	Specifies the complexity of the result

Example request

Response

struct eventlist
- array events
  collection of sms elements
  - struct
    - string sent
    - string text
    - string id
      unique identifier of the event
    - string comment
      user defined comment
    - string created
      creation date of the event
    - string scheduled
      scheduled time to send
    - string direction
      in/out
    - struct labels
      commaseperated list of labels
    - string location
      event's target (inbox, sent, archive, trash)
    - string get
      link to attached ressource (PDF, MP3)
    - string modify
      link to modify event
    - struct read
      marks the event as read/unread
      - string get
      - string modify
      - boolean value
    - struct starred
      marks the event as important/unimportant
      - string get
      - string modify
      - boolean value
    - string status
      event's state (failed, sent, pending, scheduled)
    - array sources
      event's source (calles number in case of calls)
      - struct
        
        string numberE164
        number in E.164 format
        
        string numberPretty
        number in human readable pretty format
        
        string contactFN
        'FN' (e.g. 'John Doe') entry of the contact matching this endpoint as it is stored in the account's contacts database.
        
        string get
        Reference to the contact's resource in the account's contacts database.
    - array targets
      event's target (called number in case of calls)
      - struct
        
        string numberE164
        number in E.164 format
        
        string numberPretty
        number in human readable pretty format
        
        string contactFN
        'FN' (e.g. 'John Doe') entry of the contact matching this endpoint as it is stored in the account's contacts database.
        
        string get
        Reference to the contact's resource in the account's contacts database.
    - struct extension
      internal endpoint, that handeled the event
      - string id
      - string alias
      - string get
- integer overallCount
  The overall number of events available. While the output may be limited (e.g. for pagination) this covers all that match the request criteria.
- integer count
  Number of elements returned in the result set.

POST /{userId}/events/sms/

Send an SMS
POST to this request with the parameters mentioned below to send a SMS to specified targets with an optional schedule parameter.

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
target	string	String containing the fax phone numbers of the fax recipients. (May be provided multiple times.)
source	string	Mobile phone number that is used as the sender. Please note that the mobile phone number needs to be verified before it can be used as source number!
content	string (required)	The content of the SMS that should be sent. Maximum 160 characters per Message, if more the Message will be split up into multiple messages. The absolute maximum is 460 characters (equals 3 Messages).
schedule	string	Array of strings containing the UTC date and time when the sms should be sent. Format: 'YYYY-MM-DD HH:MM:SS' Please note: currently only one value is allowed in this array.

Example request

Single SMS Event

Description:
Handles a specific sms event specified by smsId

URL

/{userId}/events/sms/{smsId}

parameter	type	description
{userId}	string (required)	internal id of webuser. my is an alias for logged in user, so preferably take this.
smsId	string (required)	undocumented

Methods

GET /{userId}/events/sms/{smsId}/

request specific sms event
Using the HTTP GET method a specific sms event can be requested that is specified via the 'smsId' variable that is part of it's resource path.

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
complexity	string	Specifies the complexity of the result

Example request

Response

struct sms
- string sent
- string text
- string id
  unique identifier of the event
- string comment
  user defined comment
- string created
  creation date of the event
- string scheduled
  scheduled time to send
- string direction
  in/out
- struct labels
  commaseperated list of labels
- string location
  event's target (inbox, sent, archive, trash)
- string get
  link to attached ressource (PDF, MP3)
- string modify
  link to modify event
- struct read
  marks the event as read/unread
  - string get
  - string modify
  - boolean value
- struct starred
  marks the event as important/unimportant
  - string get
  - string modify
  - boolean value
- string status
  event's state (failed, sent, pending, scheduled)
- array sources
  event's source (calles number in case of calls)
  - struct
    - string numberE164
      number in E.164 format
    - string numberPretty
      number in human readable pretty format
    - string contactFN
      'FN' (e.g. 'John Doe') entry of the contact matching this endpoint as it is stored in the account's contacts database.
    - string get
      Reference to the contact's resource in the account's contacts database.
- array targets
  event's target (called number in case of calls)
  - struct
    - string numberE164
      number in E.164 format
    - string numberPretty
      number in human readable pretty format
    - string contactFN
      'FN' (e.g. 'John Doe') entry of the contact matching this endpoint as it is stored in the account's contacts database.
    - string get
      Reference to the contact's resource in the account's contacts database.
- struct extension
  internal endpoint, that handeled the event
  - string id
  - string alias
  - string get

DELETE /{userId}/events/sms/{smsId}/

delete a specific sms event
Using the HTTP DELETE method on this resource, a specific sms event that is specified via the 'smsId' variable that is part of it's resource path.

Parameters

parameter	type	description
version	string (required)	Specifies the handler version

Example request

handles the 'read' property

Description:
Can be used to get or set the 'read' property of a specific sms event

URL

/{userId}/events/sms/{smsId}/read

parameter	type	description
{userId}	string (required)	internal id of webuser. my is an alias for logged in user, so preferably take this.

Methods

GET /{userId}/events/sms/{smsId}/read/

gets the 'read' property of a specific sms event
returns whether or not a specific sms event has been marked as 'read'. Please note: the event can be also marked as read/unread on the sipgate website.

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
complexity	string	Specifies the complexity of the result

Example request

Response

struct property
- string name
  the name of our property
- struct value
  the value of our property

PUT /{userId}/events/sms/{smsId}/read/

sets the 'read' property of a specific sms event
Using the HTTP PUT method on this resource, a specific sms event can been marked as 'read' or 'unread'. Please note: the event can be also marked as read/unread on the sipgate website.

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
value	boolean	Set the SMS event to 'read' (true) or 'unread' (false).

Example request

handles the 'starred' property

Description:
Can be used to get or set the 'starred' property of a specific SMS event

URL

/{userId}/events/sms/{smsId}/starred

parameter	type	description
{userId}	string (required)	internal id of webuser. my is an alias for logged in user, so preferably take this.

Methods

GET /{userId}/events/sms/{smsId}/starred/

gets the 'starred' property of a specific SMS event
returns whether or not a specific sms event has been marked as 'starred'. Please note: the event can be also starred/unstarred on the sipgate website.

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
complexity	string	Specifies the complexity of the result

Example request

Response

struct property
- string name
  the name of our property
- struct value
  the value of our property

PUT /{userId}/events/sms/{smsId}/starred/

sets the 'starred' property of a specific SMSM event
Using the HTTP PUT method on this resource, a specific SMS can be marked as 'starred' or 'unstarred'. Please note: the event can also be starred/unstarred on the sipgate website.

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
value	boolean	Set the SMS event to 'starred' (true) or 'unstarred' (false).

Example request

Voicemail Events

Description:
Listing of all voicemail events the authorized user has rights on.

URL

/{userId}/events/voicemails

parameter	type	description
{userId}	string (required)	internal id of webuser. my is an alias for logged in user, so preferably take this.

Methods

GET /{userId}/events/voicemails/

Get all voicemail events
Returns all voicemail events the authorized user has rights on.

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
complexity	string	Specifies the complexity of the result

Example request

Response

struct eventlist
- array events
  collection of voicemail elements
  - struct
    - string duration
    - string caller
    - struct content
    - string transcription
    - string id
      unique identifier of the event
    - string comment
      user defined comment
    - string created
      creation date of the event
    - string scheduled
      scheduled time to send
    - string direction
      in/out
    - struct labels
      commaseperated list of labels
    - string location
      event's target (inbox, sent, archive, trash)
    - string get
      link to attached ressource (PDF, MP3)
    - string modify
      link to modify event
    - struct read
      marks the event as read/unread
      - string get
      - string modify
      - boolean value
    - struct starred
      marks the event as important/unimportant
      - string get
      - string modify
      - boolean value
    - string status
      event's state (failed, sent, pending, scheduled)
    - array sources
      event's source (calles number in case of calls)
      - struct
        
        string numberE164
        number in E.164 format
        
        string numberPretty
        number in human readable pretty format
        
        string contactFN
        'FN' (e.g. 'John Doe') entry of the contact matching this endpoint as it is stored in the account's contacts database.
        
        string get
        Reference to the contact's resource in the account's contacts database.
    - array targets
      event's target (called number in case of calls)
      - struct
        
        string numberE164
        number in E.164 format
        
        string numberPretty
        number in human readable pretty format
        
        string contactFN
        'FN' (e.g. 'John Doe') entry of the contact matching this endpoint as it is stored in the account's contacts database.
        
        string get
        Reference to the contact's resource in the account's contacts database.
    - struct extension
      internal endpoint, that handeled the event
      - string id
      - string alias
      - string get
- integer overallCount
  The overall number of events available. While the output may be limited (e.g. for pagination) this covers all that match the request criteria.
- integer count
  Number of elements returned in the result set.

Single Voicemail Event

Description:
Using the HTTP GET method a specific fax event can be requested that is specified via the 'faxId' variable that is part of it's resource path.

URL

/{userId}/events/voicemails/{voicemailId}

parameter	type	description
{userId}	string (required)	internal id of webuser. my is an alias for logged in user, so preferably take this.
voicemailId	string (required)	undocumented

Methods

GET /{userId}/events/voicemails/{voicemailId}/

request specific voicemail event
Using the HTTP GET method a specific fax event can be requested that is specified via the 'voicemailId' variable that is part of it's resource path.

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
complexity	string	Specifies the complexity of the result

Example request

Response

struct voicemail
- string duration
- string caller
- struct content
- string transcription
- string id
  unique identifier of the event
- string comment
  user defined comment
- string created
  creation date of the event
- string scheduled
  scheduled time to send
- string direction
  in/out
- struct labels
  commaseperated list of labels
- string location
  event's target (inbox, sent, archive, trash)
- string get
  link to attached ressource (PDF, MP3)
- string modify
  link to modify event
- struct read
  marks the event as read/unread
  - string get
  - string modify
  - boolean value
- struct starred
  marks the event as important/unimportant
  - string get
  - string modify
  - boolean value
- string status
  event's state (failed, sent, pending, scheduled)
- array sources
  event's source (calles number in case of calls)
  - struct
    - string numberE164
      number in E.164 format
    - string numberPretty
      number in human readable pretty format
    - string contactFN
      'FN' (e.g. 'John Doe') entry of the contact matching this endpoint as it is stored in the account's contacts database.
    - string get
      Reference to the contact's resource in the account's contacts database.
- array targets
  event's target (called number in case of calls)
  - struct
    - string numberE164
      number in E.164 format
    - string numberPretty
      number in human readable pretty format
    - string contactFN
      'FN' (e.g. 'John Doe') entry of the contact matching this endpoint as it is stored in the account's contacts database.
    - string get
      Reference to the contact's resource in the account's contacts database.
- struct extension
  internal endpoint, that handeled the event
  - string id
  - string alias
  - string get

DELETE /{userId}/events/voicemails/{voicemailId}/

delete a specific fax event
Using the HTTP DELETE method on this resource, a specific fax event that is specified via the 'faxId' variable that is part of it's resource path.

Parameters

parameter	type	description
version	string (required)	Specifies the handler version

Example request

PUT /{userId}/events/voicemails/{voicemailId}/

Parameters

parameter	type	description
version	string (required)	Specifies the handler version

Example request

handles the 'read' property

Description:
Can be used to get or set the 'read' property of a specific voicemail event

URL

/{userId}/events/voicemails/{voicemailId}/read

parameter	type	description
{userId}	string (required)	internal id of webuser. my is an alias for logged in user, so preferably take this.

Methods

GET /{userId}/events/voicemails/{voicemailId}/read/

gets the 'read' property of a specific voicemail event
returns whether or not a specific voicemail event has been marked as 'read'. Please note: the event can be also marked as read/unread on the sipgate website.

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
complexity	string	Specifies the complexity of the result

Example request

Response

struct property
- string name
  the name of our property
- struct value
  the value of our property

PUT /{userId}/events/voicemails/{voicemailId}/read/

sets the 'read' property of a specific voicemail event
Using the HTTP PUT method on this resource, a specific voicemail event can been marked as 'read' or 'unread'. Please note: the event can be also marked as read/unread on the sipgate website.

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
value	boolean	Set the voicemail event to 'read' (true) or 'unread' (false).

Example request

handles the 'starred' property

Description:
Can be used to get or set the 'starred' property of a specific voicemail event

URL

/{userId}/events/voicemails/{voicemailId}/starred

parameter	type	description
{userId}	string (required)	internal id of webuser. my is an alias for logged in user, so preferably take this.

Methods

GET /{userId}/events/voicemails/{voicemailId}/starred/

gets the 'starred' property of a specific voicemail event
returns whether or not a specific voicemail event has been marked as 'starred'. Please note: the event can be also starred/unstarred on the sipgate website.

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
complexity	string	Specifies the complexity of the result

Example request

Response

struct property
- string name
  the name of our property
- struct value
  the value of our property

PUT /{userId}/events/voicemails/{voicemailId}/starred/

sets the 'starred' property of a specific voicemail event
Using the HTTP PUT method on this resource, a specific voicemail can be marked as 'starred' or 'unstarred'. Please note: the event can also be starred/unstarred on the sipgate website.

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
value	boolean	Set the voicemail event to 'starred' (true) or 'unstarred' (false).

Example request

Voicemail Content

Description:
Can be used to retrieve the content of a voicemail

URL

/{userId}/events/voicemails/{voicemailId}/content

parameter	type	description
{userId}	string (required)	internal id of webuser. my is an alias for logged in user, so preferably take this.

Methods

GET /{userId}/events/voicemails/{voicemailId}/content/

Fetch the content of a Voicemail
Using the HTTP GET method on this resource, the content of a voicemail can be retrieved

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
complexity	string	Specifies the complexity of the result

Example request

Response

struct HandlerResultRedirect
- string url
  URL to which the client is redirected for download.

List of calls

Description:
Do some action on a list of calls

URL

/{userId}/sessions/calls

parameter	type	description
{userId}	string (required)	internal id of webuser. my is an alias for logged in user, so preferably take this.

Methods

GET /{userId}/sessions/calls/

Use HTTP GET method for a request
Using the HTTP GET method the authorized user may receive a list of all incoming and outgoing calls from the past

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
complexity	string	Specifies the complexity of the result

Example request

Response

struct Call
- string sessionId
  The unique identifier of a running call
- string status
  The current state of a call

POST /{userId}/sessions/calls/

Use HTTP GET method for a request
Using the HTTP GET method the authorized user may receive a list of all incoming and outgoing calls from the past

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
callee	string (required)	Number or extension the specified user is calling to. If using a number the string has to start with `tel:` and if using an extension the string has to start with `sip:`
caller	string (required)	Number or extension the specified user is calling from. If using a number the string has to start with `tel:` and if using an extension the string has to start with `sip:`
registerSip	string (required)	Extension the specified user uses to bill from

Example request

Response

struct Call
- string sessionId
  The unique identifier of a running call
- string status
  The current state of a call

A specified call

Description:
Use the {sessionId} to identify a specified call

URL

/{userId}/sessions/calls/{sessionId}

parameter	type	description
{userId}	string (required)	internal id of webuser. my is an alias for logged in user, so preferably take this.
sessionId	string (required)	undocumented

Methods

GET /{userId}/sessions/calls/{sessionId}/

Request information for a single call
Using the HTTP GET method allows the authorized user to receive the current state of the specified call

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
complexity	string	Specifies the complexity of the result

Example request

Response

struct Call
- string sessionId
  The unique identifier of a running call
- string status
  The current state of a call

DELETE /{userId}/sessions/calls/{sessionId}/

Hangup a call
Using the HTTP DELETE method allows the authorized user to hang up the specified call

Parameters

parameter	type	description
version	string (required)	Specifies the handler version

Example request

Response

struct Call
- string sessionId
  The unique identifier of a running call
- string status
  The current state of a call

Record a call

Description:
Use the {sessionId} to start or stop recording a running call

URL

/{userId}/sessions/calls/{sessionId}/recording

parameter	type	description
{userId}	string (required)	internal id of webuser. my is an alias for logged in user, so preferably take this.

Methods

PUT /{userId}/sessions/calls/{sessionId}/recording/

Start or stop recording a running call
Using the HTTP PUT method allows the authorized user to start and stop recording a running call

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
value	string (required)	Set 'true' to start recording and set 'false' to stop recording

Example request

Response

struct Call
- string sessionId
  The unique identifier of a running call
- string status
  The current state of a call

Park a call

Description:
Use the{sessionId} and the{memberId} to park a specified call

URL

/{userId}/sessions/calls/{sessionId}/member/{memberId}/parking

parameter	type	description
{userId}	string (required)	internal id of webuser. my is an alias for logged in user, so preferably take this.

Methods

PUT /{userId}/sessions/calls/{sessionId}/member/{memberId}/parking/

Park or unpark a member of the call
Using the HTTP PUT method allows the authorized user to park or unpark a member on a running call

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
value	string (required)	Set 'true' to park the specified member and set 'false' unpark formerly parked member

Example request

Response

struct Call
- string sessionId
  The unique identifier of a running call
- string status
  The current state of a call

Sets temporary callthrough routing

Description:
Sets temporary callthrough routing for a specific caller number. Calls from this number to the number returned by this resource will be forwarded to the specified target number. Timeframe to start a call defaults to 30 seconds.

URL

/{userId}/sessions/callthrough

parameter	type	description
{userId}	string (required)	internal id of webuser. my is an alias for logged in user, so preferably take this.

Methods

POST /{userId}/sessions/callthrough/

Sets temporary callthrough routing
Sets temporary callthrough routing for a specific caller number. Calls from this number to the number returned by this resource will be forwarded to the specified target number. Timeframe to start a call defaults to 30 seconds.

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
sourceNumber	string (required)	valid E.164 Number used to call returned number
targetNumber	string (required)	valid E.164 Number used as callthrough target

Example request

Response

struct Callthrough
- string number
  Number to call within 30 seconds after request

Contacts

Description:
Contacts of a user. The output/input is very near to the vCard specification to allow developers interact easier with different contact systems.

URL

/{userId}/contacts

parameter	type	description
{userId}	string (required)	internal id of webuser. my is an alias for logged in user, so preferably take this.

Methods

GET /{userId}/contacts/

GET Retrieve a list of user contacts
GET Can be retrieved as vCard as well, if Accept header is set to appropriate MIME-type.

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
complexity	string	Specifies the complexity of the result
limit	integer	Limits amount of results
offset	integer	Return results beginning at offset. useful for pagination.
filter	string	Search for specified string in name and/or phone number

Example request

Response

struct Contacts
- array items
  Collection of single contacts
  - struct
    - array entries
      Liste der einzelnen Kontaktzeilen
      - struct
        
        string entryName
        Name des Eintrags nach vCard-Spezifikation (z.B. TEL, EMAIL, FN, ADR). Eintraege mit demselben Namen k��nnen immer mehrfach vorkommen.
        
        string group
        Gruppenzuordnung des Eintrags. Entspricht bei einer vCard dem Teil vor dem Namen, z.B. gruppe.TEL
        
        array types
        Typen des Eintrags nach vCard-Spezifikation <WORK, HOME, FAX, CELL>
        
        string
        
        string value
        eigentlicher Eintrag
        
        string x-local-value
        Sollte es sich bei dem Eintrag um eine Telefonnummer handeln, wird diese in diesem Feld in lokaler Formatierung zurueckgegeben
        
        string po_box
        Postfach (vorhanden nur bei ADR)
        
        string extended
        Weitere Anschrift (vorhanden nur bei ADR)
        
        string street
        Strasse (vorhanden nur bei ADR)
        
        string city
        Stadt (vorhanden nur bei ADR)
        
        string region
        Region (vorhanden nur bei ADR)
        
        string country
        Land (vorhanden nur bei ADR)
        
        string family
        Nachname (vorhanden nur bei N)
        
        string given
        Vorname (vorhanden nur bei N)
        
        string middle
        Mittelname/Initialien (vorhanden nur bei N)
        
        string prefixes
        Praefix, z.B. Dr., Ph., Graf, Lord. (vorhanden nur bei N)
        
        string suffixes
        Anhang, z.B. MdB (vorhanden nur bei N)
        
        string lat
        Geographische Breite (vorhanden nur bei GEO)
        
        string long
        Geographische Laenge (vorhanden nur bei GEO)
        
        string name
        Firmenname (vorhanden nur bei ORG)
        
        array unit
        Organisationseinheit (vorhanden nur bei ORG)
        
        string
    - struct contactMeta
      beinhaltet Systeminformationen, die nicht zum Kontakt gehoeren
      - string validFrom
        date of creation
      - string UUID
        unique contact id. MUST be UUID
      - string owner
        internal name of contact's owner. Can be mastersipid or webuserid.
- integer overallMatches
  Describes the count of result without limit and offset. You'll need it for pagination.

Single contact

Description:
Same feature as above with a limit for one contact, specified in contactId

URL

/{userId}/contacts/{contactId}

parameter	type	description
{userId}	string (required)	internal id of webuser. my is an alias for logged in user, so preferably take this.
contactId	string (required)	undocumented

Methods

GET /{userId}/contacts/{contactId}/

Retrieve one single contact.
see above

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
complexity	string	Specifies the complexity of the result

Example request

Response

struct Contacts
- array items
  Collection of single contacts
  - struct
    - array entries
      Liste der einzelnen Kontaktzeilen
      - struct
        
        string entryName
        Name des Eintrags nach vCard-Spezifikation (z.B. TEL, EMAIL, FN, ADR). Eintraege mit demselben Namen k��nnen immer mehrfach vorkommen.
        
        string group
        Gruppenzuordnung des Eintrags. Entspricht bei einer vCard dem Teil vor dem Namen, z.B. gruppe.TEL
        
        array types
        Typen des Eintrags nach vCard-Spezifikation <WORK, HOME, FAX, CELL>
        
        string
        
        string value
        eigentlicher Eintrag
        
        string x-local-value
        Sollte es sich bei dem Eintrag um eine Telefonnummer handeln, wird diese in diesem Feld in lokaler Formatierung zurueckgegeben
        
        string po_box
        Postfach (vorhanden nur bei ADR)
        
        string extended
        Weitere Anschrift (vorhanden nur bei ADR)
        
        string street
        Strasse (vorhanden nur bei ADR)
        
        string city
        Stadt (vorhanden nur bei ADR)
        
        string region
        Region (vorhanden nur bei ADR)
        
        string country
        Land (vorhanden nur bei ADR)
        
        string family
        Nachname (vorhanden nur bei N)
        
        string given
        Vorname (vorhanden nur bei N)
        
        string middle
        Mittelname/Initialien (vorhanden nur bei N)
        
        string prefixes
        Praefix, z.B. Dr., Ph., Graf, Lord. (vorhanden nur bei N)
        
        string suffixes
        Anhang, z.B. MdB (vorhanden nur bei N)
        
        string lat
        Geographische Breite (vorhanden nur bei GEO)
        
        string long
        Geographische Laenge (vorhanden nur bei GEO)
        
        string name
        Firmenname (vorhanden nur bei ORG)
        
        array unit
        Organisationseinheit (vorhanden nur bei ORG)
        
        string
    - struct contactMeta
      beinhaltet Systeminformationen, die nicht zum Kontakt gehoeren
      - string validFrom
        date of creation
      - string UUID
        unique contact id. MUST be UUID
      - string owner
        internal name of contact's owner. Can be mastersipid or webuserid.
- integer overallMatches
  Describes the count of result without limit and offset. You'll need it for pagination.

phonebook for specific vendor

Description:
retrieve a phonebook xml file for 'snom' or 'grandstream'

URL

/{userId}/contacts/phonebook/{vendorName}

parameter	type	description
{userId}	string (required)	internal id of webuser. my is an alias for logged in user, so preferably take this.
vendorName	string (required)	undocumented

Methods

GET /{userId}/contacts/phonebook/{vendorName}/

Retrieve the phonebook for a specific vendor
see above

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
complexity	string	Specifies the complexity of the result

Example request

balance

Description:
current balance of the identified account

URL

/{userId}/billing/balance

parameter	type	description
{userId}	string (required)	internal id of webuser. my is an alias for logged in user, so preferably take this.

Methods

GET /{userId}/billing/balance/

request balance
get the current balance

Parameters

parameter	type	description
version	string (required)	Specifies the handler version
complexity	string	Specifies the complexity of the result

Example request

Response

struct balance
structure representing accounts current balance
- string currency
  foo bar baz
- double totalIncludingVat
  total balance including VAT
- double vatPercent
  percentage of VAT
- array smsVouchers ~~SIMPLE~~
  - struct
    - string redeemDate ~~SIMPLE~~
    - string endOfValidityDate ~~SIMPLE~~
    - string creditsInit ~~SIMPLE~~
    - string creditsUsed ~~SIMPLE~~
    - string creditsLeft ~~SIMPLE~~
- array minuteVouchers ~~SIMPLE~~
  - struct
    - string redeemDate ~~SIMPLE~~
    - string endOfValidityDate ~~SIMPLE~~
    - string creditsInit ~~SIMPLE~~
    - string creditsUsed ~~SIMPLE~~
    - string creditsLeft ~~SIMPLE~~
- array faxVouchers ~~SIMPLE~~
  - struct
    - string redeemDate ~~SIMPLE~~
    - string endOfValidityDate ~~SIMPLE~~
    - string creditsInit ~~SIMPLE~~
    - string creditsUsed ~~SIMPLE~~
    - string creditsLeft ~~SIMPLE~~