sipgate REST-API

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

TITLEDESCRIPTIONRESSOURCE
Request all numbers for a given accountRequest all user provided numbers for a given account./{userId}/settings/numbers
Get numbers, that belong to the accountGet every single number from account/{userId}/settings/numbers/list
Get and set outgoing numbersGet and set outgoing numbers/{userId}/settings/numbers/outgoing
listing of extensionsA 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 dataInformation 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 statusYou can get and set the DND status of extensions/{userId}/settings/extensions/{extensionId}/dnd
base product typeInformation about the base product type/{userId}/settings/baseproducttype
registered mobile devicesInformation about the registered mobile devices/{userId}/settings/registeredmobiledevices
Setup mobile extensionSetup a mobile extension with information about the device./{userId}/settings/mobile/extensions
Request a GSM-CodeRequest a GSM-Code for Unified Voicemail Redirection: Forward all conditional calls to the sipgate voicemail system./{userId}/settings/mobile/extensions/unifiedvoicemailgsmcode
EventsListing 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 EventsListing of all call events the authorized user has rights on./{userId}/events/calls
Single Call Eventhandles a specified call event/{userId}/events/calls/{callId}
handles the 'read' propertyCan be used to get or set the 'read' property of a specific call event/{userId}/events/calls/{callId}/read
handles the 'starred' propertyCan be used to get or set the 'starred' property of a specific call event/{userId}/events/calls/{callId}/starred
Fax EventsListing of all fax events the authorized user has rights on./{userId}/events/faxes
Single fax eventHandles a specified fax event/{userId}/events/faxes/{faxId}
handles the 'read' propertyCan be used to get or set the 'read' property of a specific fax event/{userId}/events/faxes/{faxId}/read
handles the 'starred' propertyCan be used to get or set the 'starred' property of a specific fax event/{userId}/events/faxes/{faxId}/starred
Fax preview in different sizesReturns fax previews in different sizes < big, small >/{userId}/events/faxes/{faxId}/preview/{page}/{size}
Fax contentReturns fax pdf or tiff/{userId}/events/faxes/{faxId}/content
SMS EventsListing of all sms events the authorized user has rights on./{userId}/events/sms
Single SMS EventHandles a specific sms event specified by smsId/{userId}/events/sms/{smsId}
handles the 'read' propertyCan be used to get or set the 'read' property of a specific sms event/{userId}/events/sms/{smsId}/read
handles the 'starred' propertyCan be used to get or set the 'starred' property of a specific SMS event/{userId}/events/sms/{smsId}/starred
Voicemail EventsListing of all voicemail events the authorized user has rights on./{userId}/events/voicemails
Single Voicemail EventUsing 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' propertyCan be used to get or set the 'read' property of a specific voicemail event/{userId}/events/voicemails/{voicemailId}/read
handles the 'starred' propertyCan be used to get or set the 'starred' property of a specific voicemail event/{userId}/events/voicemails/{voicemailId}/starred
Voicemail ContentCan be used to retrieve the content of a voicemail/{userId}/events/voicemails/{voicemailId}/content
List of callsDo some action on a list of calls/{userId}/sessions/calls
A specified callUse the {sessionId} to identify a specified call/{userId}/sessions/calls/{sessionId}
Record a callUse the {sessionId} to start or stop recording a running call/{userId}/sessions/calls/{sessionId}/recording
Park a callUse the {sessionId} and the {memberId} to park a specified call/{userId}/sessions/calls/{sessionId}/member/{memberId}/parking
Sets temporary callthrough routingSets 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
ContactsContacts 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 contactSame feature as above with a limit for one contact, specified in contactId/{userId}/contacts/{contactId}
phonebook for specific vendorretrieve a phonebook xml file for 'snom' or 'grandstream'/{userId}/contacts/phonebook/{vendorName}
balancecurrent 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
parametertypedescription
{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
parametertypedescription
versionstring (required)Specifies the handler version
complexitystringSpecifies 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
parametertypedescription
{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
parametertypedescription
versionstring (required)Specifies the handler version
complexitystringSpecifies 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
parametertypedescription
{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
parametertypedescription
versionstring (required)Specifies the handler version
complexitystringSpecifies 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
parametertypedescription
versionstring (required)Specifies the handler version
clipbooleanfalse to set number to anonymous
numberstringaccount's number or userProvided number. for e164 format use tel: as prefix.
extensionIdstring (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
parametertypedescription
{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
parametertypedescription
versionstring (required)Specifies the handler version
complexitystringSpecifies 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}
parametertypedescription
{userId}string (required) internal id of webuser. my is an alias for logged in user, so preferably take this.
extensionIdstring (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
parametertypedescription
versionstring (required)Specifies the handler version
complexitystringSpecifies 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
parametertypedescription
{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
parametertypedescription
versionstring (required)Specifies the handler version
complexitystringSpecifies 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
parametertypedescription
versionstring (required)Specifies the handler version
valueboolean (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
parametertypedescription
{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
parametertypedescription
versionstring (required)Specifies the handler version
complexitystringSpecifies 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
parametertypedescription
{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
parametertypedescription
versionstring (required)Specifies the handler version
complexitystringSpecifies 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
parametertypedescription
{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
parametertypedescription
versionstring (required)Specifies the handler version
complexitystringSpecifies 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
parametertypedescription
versionstring (required)Specifies the handler version
phoneNumberstring (required)phoneNumber of the mobile extension
modelstring (required)model of the mobile extension
vendorstring (required)vendor of the mobile extension
firmwarestring (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
parametertypedescription
{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
parametertypedescription
versionstring (required)Specifies the handler version
complexitystringSpecifies the complexity of the result
statestring (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
parametertypedescription
{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
parametertypedescription
versionstring (required)Specifies the handler version
complexitystringSpecifies 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
parametertypedescription
{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
parametertypedescription
versionstring (required)Specifies the handler version
complexitystringSpecifies 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}
parametertypedescription
{userId}string (required) internal id of webuser. my is an alias for logged in user, so preferably take this.
callIdstring (required)undocumented
Methods
GET /{userId}/events/calls/{callId}/

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

Parameters
parametertypedescription
versionstring (required)Specifies the handler version
complexitystringSpecifies 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
parametertypedescription
versionstring (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
parametertypedescription
versionstring (required)Specifies the handler version
valuestringSet 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
parametertypedescription
{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
parametertypedescription
versionstring (required)Specifies the handler version
complexitystringSpecifies 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
parametertypedescription
versionstring (required)Specifies the handler version
valuebooleanSet 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
parametertypedescription
{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
parametertypedescription
versionstring (required)Specifies the handler version
complexitystringSpecifies 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
parametertypedescription
versionstring (required)Specifies the handler version
valuebooleanSet 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
parametertypedescription
{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
parametertypedescription
versionstring (required)Specifies the handler version
complexitystringSpecifies 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
parametertypedescription
versionstring (required)Specifies the handler version
extensionstringfax extension to send and bill the fax from
targetstringString containing the fax phone numbers of the fax recipients. (May be provided multiple times.)
sourcestringSource telephone number
schedulestringArray 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}
parametertypedescription
{userId}string (required) internal id of webuser. my is an alias for logged in user, so preferably take this.
faxIdstring (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
parametertypedescription
versionstring (required)Specifies the handler version
complexitystringSpecifies 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
parametertypedescription
versionstring (required)Specifies the handler version
valuestringThe 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
parametertypedescription
versionstring (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
parametertypedescription
{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
parametertypedescription
versionstring (required)Specifies the handler version
complexitystringSpecifies 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
parametertypedescription
versionstring (required)Specifies the handler version
valueboolean (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
parametertypedescription
{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
parametertypedescription
versionstring (required)Specifies the handler version
complexitystringSpecifies 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
parametertypedescription
versionstring (required)Specifies the handler version
valueboolean (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}
parametertypedescription
{userId}string (required) internal id of webuser. my is an alias for logged in user, so preferably take this.
sizestring (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
parametertypedescription
versionstring (required)Specifies the handler version
complexitystringSpecifies 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
parametertypedescription
{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
parametertypedescription
versionstring (required)Specifies the handler version
complexitystringSpecifies the complexity of the result
formatstringSpecify 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
parametertypedescription
{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
parametertypedescription
versionstring (required)Specifies the handler version
complexitystringSpecifies 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
parametertypedescription
versionstring (required)Specifies the handler version
targetstringString containing the fax phone numbers of the fax recipients. (May be provided multiple times.)
sourcestringMobile 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!
contentstring (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).
schedulestringArray 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}
parametertypedescription
{userId}string (required) internal id of webuser. my is an alias for logged in user, so preferably take this.
smsIdstring (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
parametertypedescription
versionstring (required)Specifies the handler version
complexitystringSpecifies 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
parametertypedescription
versionstring (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
parametertypedescription
{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
parametertypedescription
versionstring (required)Specifies the handler version
complexitystringSpecifies 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
parametertypedescription
versionstring (required)Specifies the handler version
valuebooleanSet 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
parametertypedescription
{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
parametertypedescription
versionstring (required)Specifies the handler version
complexitystringSpecifies 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
parametertypedescription
versionstring (required)Specifies the handler version
valuebooleanSet 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
parametertypedescription
{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
parametertypedescription
versionstring (required)Specifies the handler version
complexitystringSpecifies 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}
parametertypedescription
{userId}string (required) internal id of webuser. my is an alias for logged in user, so preferably take this.
voicemailIdstring (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
parametertypedescription
versionstring (required)Specifies the handler version
complexitystringSpecifies 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
parametertypedescription
versionstring (required)Specifies the handler version
Example request
PUT /{userId}/events/voicemails/{voicemailId}/

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
parametertypedescription
versionstring (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
parametertypedescription
{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
parametertypedescription
versionstring (required)Specifies the handler version
complexitystringSpecifies 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
parametertypedescription
versionstring (required)Specifies the handler version
valuebooleanSet 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
parametertypedescription
{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
parametertypedescription
versionstring (required)Specifies the handler version
complexitystringSpecifies 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
parametertypedescription
versionstring (required)Specifies the handler version
valuebooleanSet 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
parametertypedescription
{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
parametertypedescription
versionstring (required)Specifies the handler version
complexitystringSpecifies 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
parametertypedescription
{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
parametertypedescription
versionstring (required)Specifies the handler version
complexitystringSpecifies 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
parametertypedescription
versionstring (required)Specifies the handler version
calleestring (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:
callerstring (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:
registerSipstring (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}
parametertypedescription
{userId}string (required) internal id of webuser. my is an alias for logged in user, so preferably take this.
sessionIdstring (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
parametertypedescription
versionstring (required)Specifies the handler version
complexitystringSpecifies 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
parametertypedescription
versionstring (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
parametertypedescription
{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
parametertypedescription
versionstring (required)Specifies the handler version
valuestring (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
parametertypedescription
{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
parametertypedescription
versionstring (required)Specifies the handler version
valuestring (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
parametertypedescription
{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
parametertypedescription
versionstring (required)Specifies the handler version
sourceNumberstring (required)valid E.164 Number used to call returned number
targetNumberstring (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
parametertypedescription
{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
parametertypedescription
versionstring (required)Specifies the handler version
complexitystringSpecifies the complexity of the result
limitintegerLimits amount of results
offsetintegerReturn results beginning at offset. useful for pagination.
filterstringSearch 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}
parametertypedescription
{userId}string (required) internal id of webuser. my is an alias for logged in user, so preferably take this.
contactIdstring (required)undocumented
Methods
GET /{userId}/contacts/{contactId}/

Retrieve one single contact.
see above

Parameters
parametertypedescription
versionstring (required)Specifies the handler version
complexitystringSpecifies 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}
parametertypedescription
{userId}string (required) internal id of webuser. my is an alias for logged in user, so preferably take this.
vendorNamestring (required)undocumented
Methods
GET /{userId}/contacts/phonebook/{vendorName}/

Retrieve the phonebook for a specific vendor
see above

Parameters
parametertypedescription
versionstring (required)Specifies the handler version
complexitystringSpecifies the complexity of the result
Example request

balance

Description:
current balance of the identified account

URL
/{userId}/billing/balance
parametertypedescription
{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
parametertypedescription
versionstring (required)Specifies the handler version
complexitystringSpecifies 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