API docs by Redocly

Provisioning

Download OpenAPI specification:Download

provisioning_0

The provisioning API provides functionality to provision features provided by the platform, such as SIP devices and trunks. It also offers access to log data, usage statistics, documentation and access to API tokens.

Provisioning API Endpoints

Base url: https://api.prod-eu-north-1.iotcomms.io/provisioning

Authorize credentials request from API user.

/device/{domain}/bulk/{bulkId}

GET
Authorizations:
jwtAuthorizer
path Parameters
bulkId
required
string

The id for the bulk, can be anything

domain
required
string

The domain that the devices are provisioned for.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "status": {
    }
}

/device/{domain}/bulk/{bulkId}

PUT

Provision made devices at once by uploading a csv file

Authorizations:
jwtAuthorizer
path Parameters
bulkId
required
string

The id for the bulk, can be anything

domain
required
string

The domain that the devices are provisioned for.

Request Body schema: text/csv
required

This endpoint accepts a csv file as input and is intended to be used to provision large quantities of devices. The file must be under 10MB.

Process

First call this endpoint with a bulk id of your choice with your csv file as the body of the request. This will immedietly respond with a 200 OK. Using the same bulk id, perform a GET request to see the status of the bulk job and the reason for any potential errors.

File format

Basics

Each column in the header of the csv file should correspond to a property in the device object. Consider the following example:

deviceId authType
1234 deviceid
5678 deviceid

In this example we are provisioning two devices, one with the device id of '1234' and one with the device id '5678'. Both of the devices have their authType set to 'deviceid'.

Nested properties

It is possible to configure nested properties. See the following example:

deviceId authType authorized.domain authorized.invite authorized.register password
1234 userid customer47.prod-eu-north-1.iotcomms.io .* true supersecret
5678 userid customer47.prod-eu-north-1.iotcomms.io .* true supersecret

In this example we are provisioning properties inside the authorized object of the device.

Service data

Anything inside the 'serviceData' property must be a valid JSON value. This for example means text will need to be "inside quotes".

deviceId authType serviceData.foo.bar
1234 deviceid "example text"
5678 deviceid "example text"
deviceType
string
Enum: "sipDevice" "alarmbridgeConnect" "groupScheme" "alarmUnit"

Describes what kind of device is registered:

  • SIP Device is used for for devices that use sip credentials to authorize
  • Alarmbridge Connect is used to provision an Alarmbridge Connect gateway Device
  • Group Scheme is used when provisioning a group shceme controller unit, such as a NOW-IP controller
  • Alarm Unit is used for a provisioned device through Alarm Bridge, such as fall sensor behind a group scheme
lastConfigured
number

This property is set with the timestamp of when an Alarmbridge Connect gateway last downloaded it's configuration file.

macAddress
string

This property is used to resolve a device based on MAC address of associated Alarmbridge Connect gateway.

password
string

If authType is set to userid this property is mandatory. It is not used for the other authTypes. deviceId and password are used as credentials for the /authorize API to fetch JWT tokens for SIP authentication.

object

This property is used together with userid authType. The object configure authorization polices for SIP requests sent by the device.

domain
string

The SIP domain that the user is authorized to use.

invite
string

Regular expression evaluated against SIP destinations in invite requests. If match then request is authorized.

register
boolean

Indicates if the user is authorized to send SIP register requests for the domain.

object

This property is an object which store service specific settings for a device.

object

This property is an object which store Alarmbridge specific settings for a device.

heartbeatInterval
integer <int32> >= 300000

If this property is set it enables the heartbeat service for the device. Set the value to be the frequency in milliseconds that the device periodically sends heartbeat events. Note: Add some margin to avoid false alarms. If property is not set the value of defaultHeartbeatInterval set on the Alarmbridge service destination matched for the incoming heartbeat event will be used. The heartbeats are checked by our system every five minutes, so that is the minimum value that can be set (300000 milliseconds).

alarmProtocol
string
Enum: "tt92" "ttnew" "bs8521" "scaip" "nowip"

Set the type of protocol the device is configured to use to alarm events.

emergencyDestination
string

If this property is set for the device it is the destination the devices is connected with when the device sends and alarm event triggering the /newAlarmbridgeEvent callback and the response action is callEmergencyCenter. If property is not set the value of defaultEmergencyDestination set on the Alarmbridge service destination matched for the incoming event will be used.

object

When an alarm event is received by Alarmbridge it is mapped to a common event type format. This property will override the mapped values to allow device specific values to be set regardless of the received values.

usePredefinedDestination
boolean

Set this to signal back to the device to send the voice call to the phone number pre-provisioned in the device. The protocol and device used must support this capabilit. If for example SCAIP protocol is used the callhandlinng property will be set to 61 if this property is set.

description
string <= 200 characters

This property is used to describe or keep notes regarding this device. Maximum 200 characters.

ha1
string

This property is used in conjunction with the credentials authType. It allow a pre-determined SIP password to be set by passing the corresponding ha1 hash. If the property is omitted a password is auto generated and returned in the body of the 200 OK response.

deviceCLI
string

This property is used to resolve a device based on telephone number for incoming calls to for example Alarmbridge service.

authType
required
string
Enum: "credentials" "deviceid" "userid"

Authentication type to be used for the device. Valid values are credentials, deviceid or userid (JWT).

deviceId
required
string^[a-zA-Z0-9\-\._:~+]+$

Unique id identifying the device. Depending on request type and configuration this value is matched against user part in from: header or for SCAIP requests the value of field to authorize service access.

Responses

/device/{domain}/bulk/{bulkId}

OPTIONS
path Parameters
bulkId
required
string

The id for the bulk, can be anything

domain
required
string

The domain that the devices are provisioned for.

Responses

Response samples

Content type
application/json
{ }

/services/aws

GET

Get all AWS SaaS database records.

Authorizations:
jwtAuthorizer

Responses

Response samples

Content type
application/json
{ }

/services/aws

OPTIONS

Responses

Response samples

Content type
application/json
{ }

/alarmeventmapper/{domain}

GET
Authorizations:
jwtAuthorizer
path Parameters
domain
required
string
query Parameters
provisory
string

A boolean indicating if the configurations are to be stored as provisory instead of the working configurations. When stored as provisory the configuration will not be used by the service.

limit
string

An integer to determine a limit of how many entries should be returned from the query. The default value is 100, and it is also the maximum value accepted.

nextToken
string

The token returned from a previous query to this endpoint. Used for pagination. Include this token to get the next results.

Responses

Response samples

Content type
application/json
{
  • "alarmeventmappers": [
    ],
  • "success": true
}

/alarmeventmapper/{domain}

POST

Provision an Alarm Event Mapper with specific id for the domain.

Authorizations:
jwtAuthorizer
path Parameters
domain
required
string
query Parameters
provisory
string

A boolean indicating if the configurations are to be stored as provisory instead of the working configurations. When stored as provisory the configuration will not be used by the service.

Request Body schema: application/json
required

IVR configuration object

.

One of
alarmHandling
required
string
Enum: "callEmergencyCenter" "usePredefinedDestination" "requestCallback" "drop"

Alarmbridge will signal back to the alarm device to clear the alarm event without any subsequent voice call.

required
object
protocol
required
string (Outbound protocol)
Enum: "scaip" "bs8521" "sia-dcs" "ttnewGroupDevice" "nowipGroupDevice" "nowip" "voicecall"

The protocol of the event to be sent to the endpoint

sipAuthUser
string (SIP authentication username)

The username used for SIP authenication.

sipAuthPassword
string (SIP authentication password)

The password used for SIP authenication.

destAddr
required
string (Destination Address)

The address of the endpoint

overrideSipFrom
string (Override userinfo part of SIP From-header)

Override the SIP from header with the information specified.

defaultVoiceDestination
string (Default Voice Destination)

The default voice destination if CRE 61.

object
backupOverrideSipFrom
string (Override userinfo part of SIP From-header)

Override the SIP from header with the information specified.

backupSipAuthPassword
string (SIP authentication password)

The password used for SIP authenication.

backupDefaultVoiceDestination
string (Default Voice Destination)

The default voice destination if CRE 61.

backupSipAuthUser
string (SIP authentication username)

The username used for SIP authenication.

backupDestAddr
string (Destination Address)

The address of the endpoint

deviceIdPadLength
integer <int32> (DeviceId Pad Length) [ 0 .. 10 ]
Default: 0

Enable leading zero padding of deviceId before concatenation. Only used if Map Device Id To Controller Id is activated.

description
string

Description of the service.

mappingRules
object

The mapping rules let protocol specific alarm mapping rules to be specified. See the protocol specific documentation for more details. This is found in the Alarmbridge getting started documentation section, document "Getting Started with Alarmbridge custom event mappings"

unknownAlarmEventVoiceDestination
string

This property is configured with a SIP URI pointing to a fallback voice destination to be used in case an incoming alarm event can't be decoded and there is no calling party phone number. For inbound analogue alarm calls it will connect the incoming call with this destination upon alarm event decode failure.

fromDomain
string (From domain)

Used to override the domain portion portion of the SIP From: header. Usually set to the domain of the tenant. With this field any domain can be set.

maxSessionDuration
number (Maximum session duration)

This can be used to override the default value for the time a session exist in the service.

controllerIdPadLength
integer <int32> (ControllerId Pad Length) [ 0 .. 10 ]
Default: 0

Enable leading zero padding of controllerId before concatenation. Only used if Map Device Id To Controller Id is activated.

name
required
string

A user provided name to identify this service.

mapDeviceIdToControllerId
boolean
Default: false

If true it will concatenate controllerId and deviceId and then remove deviceId from the alarm event.

useVoiceBridge
boolean

Switches the usage of voice bridge on and off.

callerId
string (Caller Id)

Used to override the callerId field in the outbound alarmevent.

id
string

The id of a Bridge Service configuration to be used as sender for the event.

enableDestinationMonitoring
boolean (Enable Destination Monitoring)

Monitor if target or backup is active

Responses

Request samples

Content type
application/json
{
  • "alarmHandling": "callEmergencyCenter",
  • "waitForCallback": 5,
  • "targetEndpoint": {
    },
  • "deviceIdPadLength": 0,
  • "description": "string",
  • "mappingRules": { },
  • "unknownAlarmEventVoiceDestination": "string",
  • "fromDomain": "string",
  • "maxSessionDuration": 0,
  • "controllerIdPadLength": 0,
  • "name": "string",
  • "mapDeviceIdToControllerId": false,
  • "useVoiceBridge": true,
  • "callerId": "string",
  • "id": "string",
  • "enableDestinationMonitoring": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "id": "string"
}

/alarmeventmapper/{domain}

OPTIONS
path Parameters
domain
required
string
query Parameters
provisory
string

A boolean indicating if the configurations are to be stored as provisory instead of the working configurations. When stored as provisory the configuration will not be used by the service.

Responses

Response samples

Content type
application/json
{ }

/services/aws/{domain}

GET

Get AWS SaaS information for the tenant.

Authorizations:
jwtAuthorizer
path Parameters
domain
required
string

Responses

Response samples

Content type
application/json
{ }

/services/aws/{domain}

OPTIONS
path Parameters
domain
required
string

Responses

Response samples

Content type
application/json
{ }

/trunk/{domain}/{trunkId}

GET
Authorizations:
jwtAuthorizer
path Parameters
domain
required
string

The domain that the trunk is provisioned for.

trunkId
required
string

The id of the trunk requested.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "trunk": {
    }
}

/trunk/{domain}/{trunkId}

PUT

Add or modify a trunk to be used with the service.

Authorizations:
jwtAuthorizer
path Parameters
domain
required
string

The domain that the trunks are provisioned for.

trunkId
required
string

The id of the trunk to be updated or deleted.

Request Body schema: application/json
required

Trunk Configuration

Configuration for inbound and outbound calls where routing is based on b-party number. A tenant can have multiple trunks configured, e.g. for different countries or different types of calls.

destinationTarget
required
string

An IP/FQDN pointing at Target domain for trunk.

localCodec
string
Enum: "GSM" "PCMU" "PCMA"
destinationTransport
required
string

The transport protocol for the trunk

Array of strings or strings
Array
Any of
string <ipv4>

A list of either cidr or IPv4.

addTerminatingUriParameters
string

Parameters added to the R-URI sent on outgoing trunk

trunkGroupId
string

Identifier of used trunk group for a call. In INVITE to SIP-servern this will be used to direct call to specific trunk.

usePrivateIP
boolean
destinationMatch
required
string <regex>

A regular expression to match the destinations

transcode
boolean

Specifies if a call should be transcoded or not.

description
string

Optional description of the trunk

type
string
Value: "trunk"

Describes the type of serviceDestination, for trunks always "trunk"

userName
string

To be used with realm and password. To update userName, realm and password fields must also be filled. This is used to generate an ha1. If realm, userName and password are sent in the request, the response will contain a password to the trunks authentication.

destinationRewrite
string

A regular expression to rewrite the destination user

trunksideCodec
string
Enum: "GSM" "PCMU" "PCMA"
forceRtpRelay
boolean

The forceRtpRelay property is set on a SIP trunk to enable the RTP relay feature for calls passing through the trunk. With this setting, the signaling remain unchanged. This setting is typically used when a trunk is used for traffic between two IP networks without any direct IP routing.

password
string

To be used with userName and realm. To update password, realm and username fields must also be filled. This is used to generate an ha1. If realm, userName and password are sent in the request, the response will contain a password to the trunks authentication.

forceNatRewrites
boolean

The forceNatRewrites property is set to enable NAT traversal functionality for the calls passing through the trunk. This will trigger re-write of signaling and enable the RTP relay functionality. This setting is typically used if the system on the remote side of the trunk is placed behind a NAT.

diversionHeader
string

A number to be set in diversion header on outbound calls for trunk

rewriteAnumber
string

Number to replace originating number on a trunk

ha1
string

Used for authenticating the trunk. Alternatively, if realm, userName and password are sent in the body, the ha1 will be generated and a password to authenticate with it will be returned in the request response.

networkId
string

String identifying the terminating network. Multiple trunks may have the same networkId meaning that they are terminated in the same network on the remote side. Used for RTP routing, not SIP routing.

realm
string

To be used with userName and password. To update realm, username and password fields must also be filled to proceed. This is used to generate an ha1. If realm, userName and password are sent in the request, the response will contain a password to the trunks authentication.

blacklistPattern
string

A regular expression to block destinations on the trunk

Responses

Request samples

Content type
application/json
{
  • "destinationTarget": "string",
  • "localCodec": "GSM",
  • "destinationTransport": "string",
  • "sourceNetworks": [
    ],
  • "addTerminatingUriParameters": "string",
  • "trunkGroupId": "string",
  • "usePrivateIP": true,
  • "destinationMatch": "/regex/",
  • "transcode": true,
  • "description": "string",
  • "type": "trunk",
  • "userName": "string",
  • "destinationRewrite": "string",
  • "trunksideCodec": "GSM",
  • "forceRtpRelay": true,
  • "password": "string",
  • "forceNatRewrites": true,
  • "diversionHeader": "string",
  • "rewriteAnumber": "string",
  • "ha1": "string",
  • "networkId": "string",
  • "realm": "string",
  • "blacklistPattern": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "id": "string"
}

/trunk/{domain}/{trunkId}

DELETE

Delete a specified trunk configured for a domain.

Authorizations:
jwtAuthorizer
path Parameters
domain
required
string

The domain that the trunk is provisioned for.

trunkId
required
string

The id of the trunk to get details for.

Responses

Response samples

Content type
application/json
{
  • "success": true
}

/trunk/{domain}/{trunkId}

OPTIONS
path Parameters
domain
required
string

The domain that the trunk is provisioned for.

trunkId
required
string

The id of the trunk to get details for.

Responses

Response samples

Content type
application/json
{ }

/trunk/{domain}/{trunkId}

PATCH

Patch a specified trunk configured for a domain.

Authorizations:
jwtAuthorizer
path Parameters
domain
required
string

The domain that the trunk is provisioned for.

trunkId
required
string

The id of the trunk to get details for.

Request Body schema: application/json
required

The body of the request is an Array of operations as specified in the RFC 6902

Array
path
string

The path of the property inside the object. Should always start with slash (/). E.g.: /serviceData/alarmBridge/sipUri is the path to the deep property sipUri, of the alarmBridge that is a property of serviceData which is a property in root. In javascript this property is accessed like so: serviceData.alarmBridge.sipUri, from object { serviceData: { alarmBridge: { sipUri: 'sip:123test@iotcomms.io' }}}

op
string
Enum: "add" "remove" "replace" "copy" "move" "test"

String defining the operation to be performed. The supported operations are add, remove, replace, copy, move and test.

from
string

A path as described in the path property. Used for copy and move operations indicating where to copy/move from

value
string

The value of the property to be set. Valid for add, replace and test. The value could be of type string, number, object or array.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "reason": "string",
  • "success": true
}

/apiKey/{domain}/{keyId}

DELETE

Delete a specified API key for a domain.

Authorizations:
jwtAuthorizer
path Parameters
domain
required
string

The domain that the API key is provisioned for.

keyId
required
string

The id of the API key to delete. The id can be found in the sk of the response body from a request to the get method of /apiKey/{domain}.

Responses

Response samples

Content type
application/json
{
  • "success": true
}

/apiKey/{domain}/{keyId}

OPTIONS
path Parameters
domain
required
string

The domain that the API key is provisioned for.

keyId
required
string

The id of the API key to delete. The id can be found in the sk of the response body from a request to the get method of /apiKey/{domain}.

Responses

Response samples

Content type
application/json
{ }

/device/{domain}/{deviceId}

GET
Authorizations:
jwtAuthorizer
path Parameters
domain
required
string

The domain that the device is provisioned for.

deviceId
required
string

The id of the device to get details for.

Responses

Response samples

Content type
application/json
{
  • "deviceType": "sipDevice",
  • "reason": "string",
  • "lastConfigured": 0,
  • "description": "string",
  • "deviceCLI": "string",
  • "deviceId": "string",
  • "macAddress": "string",
  • "password": "string",
  • "heartbeatStatus": "online",
  • "success": true,
  • "authorized": {
    },
  • "serviceData": {
    },
  • "ha1": "string",
  • "authType": "credentials",
  • "heartbeatExpiration": 0
}

/device/{domain}/{deviceId}

DELETE

Delete a specified device configured for a domain.

Authorizations:
jwtAuthorizer
path Parameters
domain
required
string

The domain that the device is provisioned for.

deviceId
required
string

The id of the device to get details for.

Responses

Response samples

Content type
application/json
{
  • "success": true
}

/device/{domain}/{deviceId}

OPTIONS
path Parameters
domain
required
string

The domain that the device is provisioned for.

deviceId
required
string

The id of the device to get details for.

Responses

Response samples

Content type
application/json
{ }

/device/{domain}/{deviceId}

PATCH

Modify or add properties to a device.

Authorizations:
jwtAuthorizer
path Parameters
domain
required
string
deviceId
required
string
Request Body schema: application/json
required

The body of the request is an Array of operations as specified in the RFC 6902

Array
path
string

The path of the property inside the object. Should always start with slash (/). E.g.: /serviceData/alarmBridge/sipUri is the path to the deep property sipUri, of the alarmBridge that is a property of serviceData which is a property in root. In javascript this property is accessed like so: serviceData.alarmBridge.sipUri, from object { serviceData: { alarmBridge: { sipUri: 'sip:123test@iotcomms.io' }}}

op
string
Enum: "add" "remove" "replace" "copy" "move" "test"

String defining the operation to be performed. The supported operations are add, remove, replace, copy, move and test.

from
string

A path as described in the path property. Used for copy and move operations indicating where to copy/move from

value
string

The value of the property to be set. Valid for add, replace and test. The value could be of type string, number, object or array.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "reason": "string",
  • "success": true
}

/statistics

GET

Returns a list of cdr types that are used to create the statistics.

Authorizations:
jwtAuthorizer

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "CDRList": {
    }
}

/statistics

OPTIONS

Responses

Response samples

Content type
application/json
{ }

/apiKey/{domain}

GET
Authorizations:
jwtAuthorizer
path Parameters
domain
required
string

The domain that the API keys are provisioned for.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/apiKey/{domain}

PUT

Create a new API key for the organization.

Authorizations:
jwtAuthorizer
path Parameters
domain
required
string

The domain that the API keys are provisioned for.

Request Body schema: application/json
required

Could include an RS256 public key. If none is included a random string token will be generated.

key
required
string

Responses

Request samples

Content type
application/json
{
  • "key": "string"
}

Response samples

Content type
application/json
{ }

/apiKey/{domain}

OPTIONS
path Parameters
domain
required
string

The domain that the API keys are provisioned for.

Responses

Response samples

Content type
application/json
{ }

/cloudsipua/{domain}/testconfiguration/{destination}

GET
Authorizations:
jwtAuthorizer
path Parameters
domain
required
string
destination
required
string

Responses

Response samples

Content type
application/json
{
  • "receiver": "string",
  • "sender": "string",
  • "success": true
}

/cloudsipua/{domain}/testconfiguration/{destination}

OPTIONS
path Parameters
domain
required
string
destination
required
string

Responses

Response samples

Content type
application/json
{ }

/statistics/{domain}/{type}/{bucketsize}

GET

Get service statistics aggregated in time buckets.

Authorizations:
jwtAuthorizer
path Parameters
type
required
string

The type of statistics to get. Supported values are: cdr_siprec.

bucketsize
required
string

The size of the time bucket to use to aggregate the statistics. Supported values are: hour, day or month.

domain
required
string

The domain of the tenant to get statistics for.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "statistics": [
    ]
}

/statistics/{domain}/{type}/{bucketsize}

OPTIONS
path Parameters
type
required
string

The type of statistics to get. Supported values are: cdr_siprec.

bucketsize
required
string

The size of the time bucket to use to aggregate the statistics. Supported values are: hour, day or month.

domain
required
string

The domain of the tenant to get statistics for.

Responses

Response samples

Content type
application/json
{ }

/currentuser/tenants

GET

Get a list of all tenants that the logged in user has access to.

Authorizations:
jwtAuthorizer

Responses

Response samples

Content type
application/json
{
  • "tenants": [
    ],
  • "success": true
}

/currentuser/tenants

OPTIONS

Responses

Response samples

Content type
application/json
{ }

/mediaservice/{domain}

GET
Authorizations:
jwtAuthorizer
path Parameters
domain
required
string
query Parameters
provisory
string

A boolean indicating if the provisory configurations should be fetched instead of the working configurations.

limit
string

An integer to determine a limit of how many entries should be returned from the query. The default value is 100, and it is also the maximum value accepted.

nextToken
string

The token returned from a previous query to this endpoint. Used for pagination. Include this token to get the next results.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "mediaservices": [
    ]
}

/mediaservice/{domain}

POST

Provision a Media Service with specific id for the domain.

Authorizations:
jwtAuthorizer
path Parameters
domain
required
string
query Parameters
provisory
string

A boolean indicating if the provisory configurations should be fetched instead of the working configurations.

Request Body schema: application/json
required

IVR configuration object

.

googleApikey
string

API key used in case the Mediaservice should use Google text to speech services.

disableLateOffer
boolean

By default SIP calls originating from the Mediaservice will not have a SDP to optimize the signaling. Instead the codec offer is sent in the ACK. If the remote system have problems with this a normal invite is sent with a fake media endpoint, and once call is established a re-invite is sent if this property is set to true.

ivrRefresherExpiration
number >= 0

This is an optional property to be set if the mediaservice should act as session refresher for the SIP session in case the remote side has not requested to be refresher. The time value in seconds will be set in the session-expires header.

callbackTimeout
number

Max time (including re-transmission attempts in milliseconds until the HTTPS callback is timing out

destinationMatch
required
string <regex>

Regular expression used to determine if incoming calls to the tenant should be handled by this service destination.

googleServiceKey
object

Google service key object used in case the Mediaservice should use Google text to speech services.

callbackDescription
string

An user given description that helps identifying the callback resource.

description
string

Description of the service destination.

callbackName
string

An user given name that helps identifying the callback resource.

callbackBaseUrl
required
string <uri>

HTTPS base URL where callback requests for the service is sent. NOTE: It must be a URL starting with https://

replySessionExpiration
number >= 0

This is an optional property that control the value of Session-Expires header time value in seconds for call originating from the mediaservice. It will per default set the ;refresher=uas property to request remote side to act as refresher.

required
Array of objects

Array of authentication objects. These objects are used to generate JWT bearer tokens to sign callback requests from the service destinaton. If a callback request authentication fails, the request will be re-sent with a signature generated using the next authentication object in the list until all objects have been used.

Array
sub
string

This property sets the sub property in the JWT signature

object

Object with custom headers to be added to the callback request.

scope
string

This property sets the scope property in the JWT signature

secret
string

This property should be set with the RS256 private key used to sign the JWT token if the type is RS256, the API key if type is token, the user:password base64 hash if type is basic.

type
string
Enum: "RS256" "token" "basic"

This property sets the type of authentication used for the callback requests from the service destination. See the REST API getting started guide for more information about API authentication.

rtpTimeout
number

Overrides the default RTP timeout value of 90 seconds. Set it to the desired value in seconds. If RTP media from remote side been silent for this time the IVR participant will be disconnected and it also triggers a service alarm.

callbackId
string

A generated id used to manage the callback resource.

offeredCodecs
Array of strings (Limit offered codecs)
Items Enum: "opus" "PCMA" "PCMU"

An array of codecs to be offered in case a SIP Invite is received without SDP. If this is not specified all codecs are offered. If incoming invite contains a SDP the answer match in inbound invite codec is set.

name
required
string

A name provided by the user to identify this service destination.

networkId
string

The platform supports network connectivity from many different public or private IP networks. If routing is not possible between these networks they may be assigned a networkId. This is an optional property indicating which networkId the media service should be bound to. If a call would originate or terminate from a SIP trunk assigned a different networkId media will must be anchored in the platform since no direct routing is possible between the networks.

id
string

Unique ID generated for the service destination

Responses

Request samples

Content type
application/json
{
  • "googleApikey": "string",
  • "disableLateOffer": true,
  • "ivrRefresherExpiration": 0,
  • "callbackTimeout": 0,
  • "destinationMatch": "/regex/",
  • "googleServiceKey": { },
  • "callbackDescription": "string",
  • "description": "string",
  • "callbackName": "string",
  • "callbackBaseUrl": "http://example.com",
  • "replySessionExpiration": 0,
  • "restAuthentication": [
    ],
  • "rtpTimeout": 0,
  • "callbackId": "string",
  • "offeredCodecs": [
    ],
  • "name": "string",
  • "networkId": "string",
  • "id": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "id": "string"
}

/mediaservice/{domain}

OPTIONS
path Parameters
domain
required
string
query Parameters
provisory
string

A boolean indicating if the provisory configurations should be fetched instead of the working configurations.

Responses

Response samples

Content type
application/json
{ }

/notificationsettings/{domain}

GET

Get event notification destinations for the service.

Authorizations:
jwtAuthorizer
path Parameters
domain
required
string

Responses

Response samples

Content type
application/json
{
  • "restAuthentication": [
    ],
  • "alarmTopic": "string",
  • "httpTimeout": 0,
  • "sipEventsTopic": "string",
  • "useHttpEvents": true,
  • "alarmEventsRestEndpoint": "string",
  • "sipEventsRestEndpoint": "string",
  • "alarmbridgeCallbackEndpoint": "string"
}

/notificationsettings/{domain}

PUT

Set event notification destinations for the service.

Authorizations:
jwtAuthorizer
path Parameters
domain
required
string
Request Body schema: application/json
required

Notification destination settings object.

Array of objects (restAuthentication)
Array
sub
string

If the REST authentication type is set to RS256, the sub property is added to the payload of the generated JSON Web Token(JWT).

requestHeaders
object

An object with headers to be added in the callback.

scope
string

If the REST authentication type is set to RS256, the scope property is added to the payload of the generated JSON Web Token(JWT).

secret
required
string

The secret property has different values depending on the type set for the REST authentication object. The type basic takes a string to be added to 'Basic ' in the Authorization header. The token type is added as 'Bearer ' to the Authorization header. The RS256 type will use the secret string to sign a JSON Web Token (JWT) to be added as 'Bearer ' to the Authorization header.

type
required
string
Enum: "RS256" "basic" "token"

Determines the content of the Authorization header that will be added to the callback request and how will the secret property be used. The type basic will set the Authorization header to string 'Basic '. The type token will set the Authorization header to 'Bearer '. The type RS256 will generate a JSON Web Token(JWT) signed with .

alarmTopic
string

AWS ARN of SNS topic where the service will post service alarms as specified in the SNS alarmTopic API.

httpTimeout
integer <int32>

Total timeout in milliseconds before callback request including three re-try attempts will fail.

sipEventsTopic
string

AWS ARN of SNS topic where the service will post events as specified in the SNS sipEventsTopic API.

useHttpEvents
boolean

If this is set to true HTTPS will be used for callback notifications and not SNS for sipEvents and alarms.

alarmEventsRestEndpoint
string

this is set to true HTTPS will be used for serve notifications and not SNS for sipEvents and alarms.

sipEventsRestEndpoint
string

REST callback base URL to be used for sipEvents notifications. Must start with http:// or https://

alarmbridgeCallbackEndpoint
string

REST callback base URL to be used for alarmbridge service callbacks. Must start with http:// or https://

Responses

Request samples

Content type
application/json
{
  • "restAuthentication": [
    ],
  • "alarmTopic": "string",
  • "httpTimeout": 0,
  • "sipEventsTopic": "string",
  • "useHttpEvents": true,
  • "alarmEventsRestEndpoint": "string",
  • "sipEventsRestEndpoint": "string",
  • "alarmbridgeCallbackEndpoint": "string"
}

Response samples

Content type
application/json
{
  • "success": true
}

/notificationsettings/{domain}

OPTIONS
path Parameters
domain
required
string

Responses

Response samples

Content type
application/json
{ }

/trunk/{domain}

GET
Authorizations:
jwtAuthorizer
path Parameters
domain
required
string

The domain that the trunks are provisioned for.

query Parameters
limit
string

An integer to determine a limit of how many entries should be returned from the query. The default value is 100, and it is also the maximum value accepted.

nextToken
string

The token returned from a previous query to this endpoint. Used for pagination. Include this token to get the next results.

Responses

Response samples

Content type
application/json
{
  • "trunks": [
    ],
  • "nextToken": "string",
  • "success": true
}

/trunk/{domain}

PUT

Add or modify a trunk to be used with the service.

Authorizations:
jwtAuthorizer
path Parameters
domain
required
string

The domain that the trunks are provisioned for.

Request Body schema: application/json
required

Trunk Configuration

Configuration for inbound and outbound calls where routing is based on b-party number. A tenant can have multiple trunks configured, e.g. for different countries or different types of calls.

trunkId
string

The id of the trunk to be updated. If this property is not specified in the request a new trunk will be created with a new ID. In case no trunk with the specified ID exists a new trunk will be created using this ID.

required
object (Trunks service destination object)
destinationTarget
required
string

An IP/FQDN pointing at Target domain for trunk.

localCodec
string
Enum: "GSM" "PCMU" "PCMA"
destinationTransport
required
string

The transport protocol for the trunk

Array of strings or strings
Array
Any of
string <ipv4>

A list of either cidr or IPv4.

addTerminatingUriParameters
string

Parameters added to the R-URI sent on outgoing trunk

trunkGroupId
string

Identifier of used trunk group for a call. In INVITE to SIP-servern this will be used to direct call to specific trunk.

usePrivateIP
boolean
destinationMatch
required
string <regex>

A regular expression to match the destinations

transcode
boolean

Specifies if a call should be transcoded or not.

description
string

Optional description of the trunk

type
string
Value: "trunk"

Describes the type of serviceDestination, for trunks always "trunk"

userName
string

To be used with realm and password. To update userName, realm and password fields must also be filled. This is used to generate an ha1. If realm, userName and password are sent in the request, the response will contain a password to the trunks authentication.

destinationRewrite
string

A regular expression to rewrite the destination user

trunksideCodec
string
Enum: "GSM" "PCMU" "PCMA"
forceRtpRelay
boolean

The forceRtpRelay property is set on a SIP trunk to enable the RTP relay feature for calls passing through the trunk. With this setting, the signaling remain unchanged. This setting is typically used when a trunk is used for traffic between two IP networks without any direct IP routing.

password
string

To be used with userName and realm. To update password, realm and username fields must also be filled. This is used to generate an ha1. If realm, userName and password are sent in the request, the response will contain a password to the trunks authentication.

forceNatRewrites
boolean

The forceNatRewrites property is set to enable NAT traversal functionality for the calls passing through the trunk. This will trigger re-write of signaling and enable the RTP relay functionality. This setting is typically used if the system on the remote side of the trunk is placed behind a NAT.

diversionHeader
string

A number to be set in diversion header on outbound calls for trunk

rewriteAnumber
string

Number to replace originating number on a trunk

ha1
string

Used for authenticating the trunk. Alternatively, if realm, userName and password are sent in the body, the ha1 will be generated and a password to authenticate with it will be returned in the request response.

networkId
string

String identifying the terminating network. Multiple trunks may have the same networkId meaning that they are terminated in the same network on the remote side. Used for RTP routing, not SIP routing.

realm
string

To be used with userName and password. To update realm, username and password fields must also be filled to proceed. This is used to generate an ha1. If realm, userName and password are sent in the request, the response will contain a password to the trunks authentication.

blacklistPattern
string

A regular expression to block destinations on the trunk

Responses

Request samples

Content type
application/json
{
  • "trunkId": "string",
  • "serviceDestination": {
    }
}

Response samples

Content type
application/json
{ }

/trunk/{domain}

POST

Create a trunk to be used with the service.

Authorizations:
jwtAuthorizer
path Parameters
domain
required
string

The domain that the trunks are provisioned for.

Request Body schema: application/json
required

Trunk Configuration

Configuration for inbound and outbound calls where routing is based on b-party number. A tenant can have multiple trunks configured, e.g. for different countries or different types of calls.

destinationTarget
required
string

An IP/FQDN pointing at Target domain for trunk.

localCodec
string
Enum: "GSM" "PCMU" "PCMA"
destinationTransport
required
string

The transport protocol for the trunk

Array of strings or strings
Array
Any of
string <ipv4>

A list of either cidr or IPv4.

addTerminatingUriParameters
string

Parameters added to the R-URI sent on outgoing trunk

trunkGroupId
string

Identifier of used trunk group for a call. In INVITE to SIP-servern this will be used to direct call to specific trunk.

usePrivateIP
boolean
destinationMatch
required
string <regex>

A regular expression to match the destinations

transcode
boolean

Specifies if a call should be transcoded or not.

description
string

Optional description of the trunk

type
string
Value: "trunk"

Describes the type of serviceDestination, for trunks always "trunk"

userName
string

To be used with realm and password. To update userName, realm and password fields must also be filled. This is used to generate an ha1. If realm, userName and password are sent in the request, the response will contain a password to the trunks authentication.

destinationRewrite
string

A regular expression to rewrite the destination user

trunksideCodec
string
Enum: "GSM" "PCMU" "PCMA"
forceRtpRelay
boolean

The forceRtpRelay property is set on a SIP trunk to enable the RTP relay feature for calls passing through the trunk. With this setting, the signaling remain unchanged. This setting is typically used when a trunk is used for traffic between two IP networks without any direct IP routing.

password
string

To be used with userName and realm. To update password, realm and username fields must also be filled. This is used to generate an ha1. If realm, userName and password are sent in the request, the response will contain a password to the trunks authentication.

forceNatRewrites
boolean

The forceNatRewrites property is set to enable NAT traversal functionality for the calls passing through the trunk. This will trigger re-write of signaling and enable the RTP relay functionality. This setting is typically used if the system on the remote side of the trunk is placed behind a NAT.

diversionHeader
string

A number to be set in diversion header on outbound calls for trunk

rewriteAnumber
string

Number to replace originating number on a trunk

ha1
string

Used for authenticating the trunk. Alternatively, if realm, userName and password are sent in the body, the ha1 will be generated and a password to authenticate with it will be returned in the request response.

networkId
string

String identifying the terminating network. Multiple trunks may have the same networkId meaning that they are terminated in the same network on the remote side. Used for RTP routing, not SIP routing.

realm
string

To be used with userName and password. To update realm, username and password fields must also be filled to proceed. This is used to generate an ha1. If realm, userName and password are sent in the request, the response will contain a password to the trunks authentication.

blacklistPattern
string

A regular expression to block destinations on the trunk

Responses

Request samples

Content type
application/json
{
  • "destinationTarget": "string",
  • "localCodec": "GSM",
  • "destinationTransport": "string",
  • "sourceNetworks": [
    ],
  • "addTerminatingUriParameters": "string",
  • "trunkGroupId": "string",
  • "usePrivateIP": true,
  • "destinationMatch": "/regex/",
  • "transcode": true,
  • "description": "string",
  • "type": "trunk",
  • "userName": "string",
  • "destinationRewrite": "string",
  • "trunksideCodec": "GSM",
  • "forceRtpRelay": true,
  • "password": "string",
  • "forceNatRewrites": true,
  • "diversionHeader": "string",
  • "rewriteAnumber": "string",
  • "ha1": "string",
  • "networkId": "string",
  • "realm": "string",
  • "blacklistPattern": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "id": "string"
}

/trunk/{domain}

OPTIONS
path Parameters
domain
required
string

The domain that the trunks are provisioned for.

Responses

Response samples

Content type
application/json
{ }

/device/{domain}

GET
Authorizations:
jwtAuthorizer
path Parameters
domain
required
string

The domain that the devices are provisioned for.

query Parameters
limit
string

An integer to determine a limit of how many entries should be returned from the query. The default value is 100, and it is also the maximum value accepted.

nextToken
string

The token returned from a previous query to this endpoint. Used for pagination. Include this token to get the next results.

filter
string

A string to filter the devices. The filter returns devices of which deviceid starts with the filter string.

Responses

Response samples

Content type
application/json
{
  • "devices": [
    ],
  • "nextToken": "string",
  • "success": true
}

/device/{domain}

PUT

Add or modify a device to be used with the service.

Authorizations:
jwtAuthorizer
path Parameters
domain
required
string

The domain that the devices are provisioned for.

Request Body schema: application/json
required

The parameters authType, domain and deviceid are required for all requests.

domain *

(string) The SIP domain that the user belongs to. Value is used to authorize originating sip requests.

deviceid *

(string) Unique id identifying the device. Depending on request type and configuration this value is matched against user part in from: header or other service specific configuration to authorize service access. Note: To provision Alarmbridge devices this string should be of format customerSiteId:controllerId:deviceId to authenticate incoming alarm events having these properties. If just a controllerId is in the alarm event the string should be set to controllerId. No customerSiteId is provisioned this and first colon should be omitted.

authType *

(string)

The remaining contents of the request depend on the type of authentication to be used for the device. Valid values are credentials, deviceid or userid (JWT).

  • credentials

Used to generate a device that use SIP digest authentication. The SIP password is automatically generated and returned in response.

  • deviceid

Used to add SCAIP devices to white list. Authentication is done by matching deviceId value with CID in SCAIP body.

  • userid

Used to create access for end users using applications that can authenticate with SIP service using JWT tokens. If this type is used a password is provided to be associated with the user. JWT token is then fetched using the /authorize API endpoint. This request requires the extra parameters password and authorized

password

(string) If authType is set to userid this property is mandatory. It is not used for the other authTypes. deviceId and password are used as credentials for the /authorize API to fetch JWT tokens for SIP authentication.

authorized

(object) This property is used together with userid authType. The object configure authorization polices for SIP requests sent by the device. Contains domain, invite and register:

  • domain (string): The SIP domain that the user is authorized to use.
  • invite (string): Regular expression evalutated against SIP destinations in invite requests. If match then request is authorized.
  • register (boolean): Indicates if the user is authorized to send SIP register requests for the domain.

ha1

(string) If authType is set to credentials this is an optional parameter that allow a SIP ha1 password hash to be provided. This allow a specific SIP password to be set for the device provisioned. If it is not provided an random password will be created automatically.

deviceType
string
Enum: "sipDevice" "alarmbridgeConnect" "groupScheme" "alarmUnit"

Describes what kind of device is registered:

  • SIP Device is used for for devices that use sip credentials to authorize
  • Alarmbridge Connect is used to provision an Alarmbridge Connect gateway Device
  • Group Scheme is used when provisioning a group shceme controller unit, such as a NOW-IP controller
  • Alarm Unit is used for a provisioned device through Alarm Bridge, such as fall sensor behind a group scheme
lastConfigured
number

This property is set with the timestamp of when an Alarmbridge Connect gateway last downloaded it's configuration file.

macAddress
string

This property is used to resolve a device based on MAC address of associated Alarmbridge Connect gateway.

password
string

If authType is set to userid this property is mandatory. It is not used for the other authTypes. deviceId and password are used as credentials for the /authorize API to fetch JWT tokens for SIP authentication.

object

This property is used together with userid authType. The object configure authorization polices for SIP requests sent by the device.

domain
string

The SIP domain that the user is authorized to use.

invite
string

Regular expression evaluated against SIP destinations in invite requests. If match then request is authorized.

register
boolean

Indicates if the user is authorized to send SIP register requests for the domain.

object

This property is an object which store service specific settings for a device.

object

This property is an object which store Alarmbridge specific settings for a device.

heartbeatInterval
integer <int32> >= 300000

If this property is set it enables the heartbeat service for the device. Set the value to be the frequency in milliseconds that the device periodically sends heartbeat events. Note: Add some margin to avoid false alarms. If property is not set the value of defaultHeartbeatInterval set on the Alarmbridge service destination matched for the incoming heartbeat event will be used. The heartbeats are checked by our system every five minutes, so that is the minimum value that can be set (300000 milliseconds).

alarmProtocol
string
Enum: "tt92" "ttnew" "bs8521" "scaip" "nowip"

Set the type of protocol the device is configured to use to alarm events.

emergencyDestination
string

If this property is set for the device it is the destination the devices is connected with when the device sends and alarm event triggering the /newAlarmbridgeEvent callback and the response action is callEmergencyCenter. If property is not set the value of defaultEmergencyDestination set on the Alarmbridge service destination matched for the incoming event will be used.

object

When an alarm event is received by Alarmbridge it is mapped to a common event type format. This property will override the mapped values to allow device specific values to be set regardless of the received values.

usePredefinedDestination
boolean

Set this to signal back to the device to send the voice call to the phone number pre-provisioned in the device. The protocol and device used must support this capabilit. If for example SCAIP protocol is used the callhandlinng property will be set to 61 if this property is set.

description
string <= 200 characters

This property is used to describe or keep notes regarding this device. Maximum 200 characters.

ha1
string

This property is used in conjunction with the credentials authType. It allow a pre-determined SIP password to be set by passing the corresponding ha1 hash. If the property is omitted a password is auto generated and returned in the body of the 200 OK response.

deviceCLI
string

This property is used to resolve a device based on telephone number for incoming calls to for example Alarmbridge service.

authType
required
string
Enum: "credentials" "deviceid" "userid"

Authentication type to be used for the device. Valid values are credentials, deviceid or userid (JWT).

deviceId
required
string^[a-zA-Z0-9\-\._:~+]+$

Unique id identifying the device. Depending on request type and configuration this value is matched against user part in from: header or for SCAIP requests the value of field to authorize service access.

Responses

Request samples

Content type
application/json
{
  • "deviceType": "sipDevice",
  • "lastConfigured": 0,
  • "macAddress": "string",
  • "password": "string",
  • "authorized": {
    },
  • "serviceData": {
    },
  • "description": "string",
  • "ha1": "string",
  • "deviceCLI": "string",
  • "authType": "credentials",
  • "deviceId": "string"
}

Response samples

Content type
application/json
{
  • "password": "string",
  • "success": true
}

/device/{domain}

DELETE

Delete all devices configured for a domain.

Authorizations:
jwtAuthorizer
path Parameters
domain
required
string

The domain that the devices are provisioned for.

Request Body schema: application/json
required
confirmDeleteAll
boolean

If false or absent the request will simulate the deletion without actually removing any devices.

Responses

Request samples

Content type
application/json
{
  • "confirmDeleteAll": true
}

Response samples

Content type
application/json
{
  • "reason": "string",
  • "success": true,
  • "message": "string",
  • "error": { }
}

/device/{domain}

OPTIONS
path Parameters
domain
required
string

The domain that the devices are provisioned for.

Responses

Response samples

Content type
application/json
{ }

/alarmbridge/{domain}

GET
Authorizations:
jwtAuthorizer
path Parameters
domain
required
string
query Parameters
provisory
string

A boolean indicating if the provisory configurations should be fetched instead of the working configurations.

limit
string

An integer to determine a limit of how many entries should be returned from the query. The default value is 100, and it is also the maximum value accepted.

nextToken
string

The token returned from a previous query to this endpoint. Used for pagination. Include this token to get the next results.

Responses

Response samples

Content type
application/json
{
  • "alarmbridges": [
    ],
  • "success": true
}

/alarmbridge/{domain}

POST

Provision an Alarmbridge with specific id for the domain.

Authorizations:
jwtAuthorizer
path Parameters
domain
required
string
query Parameters
provisory
string

A boolean indicating if the provisory configurations should be fetched instead of the working configurations.

Request Body schema: application/json
required

IVR configuration object

.

One of
protocol
required
string (Inbound protocol)
Enum: "api" "bs8521" "deviceProvisioned" "nowip" "scaip" "tt92" "ttnew" "multiprotocol" "voicecall" "nowipcontroller"

This property control which alarm protocol that is expected for incoming events to the service destination. To learn more, head to our Getting Started Alarmbridge guide.

protocolMode
required
string
Enum: "dtmf" "sdmf"

This property set additional configuration for configured protocol. Currently only applicable for tt92 protocol.

alarmEventMapperId
string

Id of the bridge service to be used by this service destination.

defaultHeartbeatInterval
number >= 300000
Default: 300000

Specified, in milliseconds, the default heartbeat interval value to be used for all devices. If this is set the heartbeat service is then enabled for all the devices sending heartbeat messages to this service destination. It could be overridden by setting the property when provisioning a device. The heartbeats are checked by our system every five minutes, so that is the minimum value that can be set (300000 milliseconds).

useVPNConnection
boolean (Use VPN Connection)
Default: false

Setting this property to true it will disable the NAT traversal logic in the SIP server and configure the media server to use private IP addresses.

fallbackAlarmProtocol
string
Enum: "bs8521" "scaip" "tt92" "ttnew"

This property is used in combination with the deviceProvisioned value of protocol property. It is set to the protocol to be used in case no device is found matching the CLI of the incoming alarm event.

callbackTimeout
number
Default: 15000

Max time in milliseconds for a response until a callback request is considered as a failure.

destinationMatch
required
string <regex>

Regular expression used to determine if incoming calls to the tenant should be handled by this service destination.

object

Set properties how to send DTMF tones for Alarmbridge service destination.

calleeDtmfSendType
string
Enum: "2833" "inaudio"

Set this property to control how DTMF tones are sent to remote destinations. Type inaudio which is default injects tones in the audio RTP stream. Type 2833 use RFC2833 tone packets in the RTP stream.

callerDtmfSendType
string
Enum: "2833" "inaudio"

Set this property to control how DTMF tones are sent to remote destinations. Type inaudio which is default injects tones in the audio RTP stream. Type 2833 use RFC2833 tone packets in the RTP stream.

dtmfSendType
string
Enum: "2833" "inaudio"

Set this property to control how DTMF tones are sent to remote destinations. Type inaudio which is default injects tones in the audio RTP stream. Type 2833 use RFC2833 tone packets in the RTP stream.

callbackDescription
string

An user given description that helps identifying the callback resource.

controlCommandsEnabled
boolean
Default: true

If this property is set to true the Alarmbridge will stay in the media path when a subsequent voice call have been established after reception of alarm event. If not set the media path will be straight between alarm device and alarm receiver. To be able to use the /devicecommand API to send commands to the alarm device during voice session this property must be set to true. NOTE: Use of this feature will result in one terminating and one originating Alarmbridge analogue call for the complete duration of the voice session and charged for accordingly.

description
string

Description of the service.

arcDisconnectClearsCall
boolean
Default: true

If this is set to true an incoming call hangup/BYE received from ARC would trigger a clear command to be sent to the connected alarm device before the call is hung up. If not set it is required to use the /alarmbridge/hangupalarmcall API to send the clear command before hanging up the call.

customEventMap
object

Object with rules that define how alarm events should be transformed in callback requests. See the getting-started document "Getting Started with Alarmbridge custom event mappings" for information of the structure of this object.

customerSiteId
string <regex> ^[a-zA-Z0-9_\-\.]+$

If this property is set the value will be copied to the customerSiteId property of /newAlarmbridgeEvent callbacks. It will also be used as to prefix controllerId:deviceId string for alarm device authentication lookup against provisioned devices. A provisioned devices identifier must be unique for a tenant, and this prefix allow different customer sites to use overlapping controllerId:deviceId configurations.

callbackName
string

An user given name that helps identifying the callback resource.

callbackBaseUrl
string <uri>

HTTPS base URL where callback requests for the service is sent. NOTE: It must be a URL starting with https://

Array of objects (Authentication)

This array contain objects used to authenticate callback requests. If the first object fail to authenticate the service will continue with the rest of objects in the list until success. More information of how these objects are constructed is found in the getting-started guide "Getting Started with iotcomms.io REST APIs."

Array
sub
string

If the REST authentication type is set to RS256, the sub property is added to the payload of the generated JSON Web Token(JWT).

requestHeaders
object

An object with headers to be added in the callback.

scope
string

If the REST authentication type is set to RS256, the scope property is added to the payload of the generated JSON Web Token(JWT).

secret
required
string

The secret property has different values depending on the type set for the REST authentication object. The type basic takes a string to be added to 'Basic ' in the Authorization header. The token type is added as 'Bearer ' to the Authorization header. The RS256 type will use the secret string to sign a JSON Web Token (JWT) to be added as 'Bearer ' to the Authorization header.

type
required
string
Enum: "RS256" "basic" "token"

Determines the content of the Authorization header that will be added to the callback request and how will the secret property be used. The type basic will set the Authorization header to string 'Basic '. The type token will set the Authorization header to 'Bearer '. The type RS256 will generate a JSON Web Token(JWT) signed with .

callbackId
string

A generated id used to manage the callback resource.

name
required
string

A name provided by the user to identify this service.

id
string

Unique ID generated for that resource

dataRequestInterval
number

Specifies in milliseconds the time between data request tones send by the service to alarm device. Applicable for bs8521 protocol. Defaults to 1600ms

defaultEmergencyDestination
string

This is the default emergency destination number used for new alarm events. It could be overridden by setting the property when provisioning a device.

Responses

Request samples

Content type
application/json
{
  • "tonePowers": [
    ],
  • "protocol": "api",
  • "protocolCandidates": [
    ],
  • "toneSettings": {
    },
  • "protocolModes": [
    ],
  • "alarmEventMapperId": "string",
  • "defaultHeartbeatInterval": 300000,
  • "useVPNConnection": false,
  • "fallbackAlarmProtocol": "bs8521",
  • "callbackTimeout": 15000,
  • "destinationMatch": "/regex/",
  • "callbackDescription": "string",
  • "controlCommandsEnabled": true,
  • "description": "string",
  • "arcDisconnectClearsCall": true,
  • "customEventMap": { },
  • "customerSiteId": "/regex/",
  • "callbackName": "string",
  • "callbackBaseUrl": "http://example.com",
  • "restAuthentication": [
    ],
  • "callbackId": "string",
  • "name": "string",
  • "id": "string",
  • "dataRequestInterval": 0,
  • "defaultEmergencyDestination": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "id": "string"
}

/alarmbridge/{domain}

OPTIONS
path Parameters
domain
required
string
query Parameters
provisory
string

A boolean indicating if the provisory configurations should be fetched instead of the working configurations.

Responses

Response samples

Content type
application/json
{ }

/device/{domain}/status

GET
Authorizations:
jwtAuthorizer
path Parameters
domain
required
string

The domain that the device is provisioned for.

Responses

Response samples

Content type
application/json
{
  • "expires": "string",
  • "aor": "string",
  • "contact": "string"
}

/device/{domain}/status

OPTIONS
path Parameters
domain
required
string

The domain that the device is provisioned for.

Responses

Response samples

Content type
application/json
{ }

/configuration/{domain}

GET
Authorizations:
jwtAuthorizer
path Parameters
domain
required
string

The domain to download configuration for.

Responses

Response samples

Content type
application/json
{
  • "configuration": { },
  • "success": true
}

/configuration/{domain}

OPTIONS
path Parameters
domain
required
string

The domain to download configuration for.

Responses

Response samples

Content type
application/json
{ }

/cloudsipua/{domain}

GET
Authorizations:
jwtAuthorizer
path Parameters
domain
required
string
query Parameters
provisory
string

A boolean indicating if the provisory configurations should be fetched instead of the working configurations.

limit
string

An integer to determine a limit of how many entries should be returned from the query. The default value is 100, and it is also the maximum value accepted.

nextToken
string

The token returned from a previous query to this endpoint. Used for pagination. Include this token to get the next results.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "cloudsipuas": [
    ]
}

/cloudsipua/{domain}

POST

Provision a Cloud SIP User Agent with specific id for the domain.

Authorizations:
jwtAuthorizer
path Parameters
domain
required
string
query Parameters
provisory
string

A boolean indicating if the provisory configurations should be fetched instead of the working configurations.

Request Body schema: application/json
required

IVR configuration object

.

Array of objects

Array of authentication objects. These objects are used to generate JWT bearer tokens to sign callback requests from the service destinaton. If a callback request authentication fail, the request will be re-sent and signature generated using the next authentication object in the list until all objects been used.

Array
sub
string

This property sets the sub property in the JWT signature

object

Object with custom headers to be added to the callback request.

scope
string

This property sets the scope property in the JWT signature

secret
string

This property should be set with the RS256 private key used to sign the JWT token if the type is RS256, the API key if type is token, the user:password base64 hash if type is basic.

type
string
Enum: "RS256" "token" "basic"

This property sets the type of authentication used for the callback requests from the service destination. See the REST API getting started guide for more information about API authentication.

callbackTimeout
number
callbackId
string

A generated id used to manage the callback resource.

destinationMatch
required
string <regex>

Regular expression used to determine if incoming calls to the tenant should be handled by this service destination.

callbackDescription
string

An user given description that helps identifying the callback resource.

name
required
string

A name provided by the user to identify this service.

description
string

Description of the service.

id
string

Unique ID generated for that resouce

callbackName
string

An user given name that helps identifying the callback resource.

callbackBaseUrl
required
string <uri>

HTTPS base URL where callback requests for the service is sent. NOTE: It must be a URL starting with https://

Responses

Request samples

Content type
application/json
{
  • "restAuthentication": [
    ],
  • "callbackTimeout": 0,
  • "callbackId": "string",
  • "destinationMatch": "/regex/",
  • "callbackDescription": "string",
  • "name": "string",
  • "description": "string",
  • "id": "string",
  • "callbackName": "string",
  • "callbackBaseUrl": "http://example.com"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "id": "string"
}

/cloudsipua/{domain}

OPTIONS
path Parameters
domain
required
string
query Parameters
provisory
string

A boolean indicating if the provisory configurations should be fetched instead of the working configurations.

Responses

Response samples

Content type
application/json
{ }

/mediaservice/{domain}/{mediaServiceId}

GET
Authorizations:
jwtAuthorizer
path Parameters
mediaServiceId
required
string
domain
required
string
query Parameters
provisory
string

A boolean indicating if the configurations to be deleted are provisory instead of the working configurations.

Responses

Response samples

Content type
application/json
{
  • "mediaservice": {
    },
  • "success": true
}

/mediaservice/{domain}/{mediaServiceId}

PUT

Overwrite the configurations of an Media Service with specific id.

Authorizations:
jwtAuthorizer
path Parameters
mediaServiceId
required
string
domain
required
string
query Parameters
provisory
string

A boolean indicating if the configurations to be deleted are provisory instead of the working configurations.

Request Body schema: application/json
required

IVR configuration object

.

googleApikey
string

API key used in case the Mediaservice should use Google text to speech services.

disableLateOffer
boolean

By default SIP calls originating from the Mediaservice will not have a SDP to optimize the signaling. Instead the codec offer is sent in the ACK. If the remote system have problems with this a normal invite is sent with a fake media endpoint, and once call is established a re-invite is sent if this property is set to true.

ivrRefresherExpiration
number >= 0

This is an optional property to be set if the mediaservice should act as session refresher for the SIP session in case the remote side has not requested to be refresher. The time value in seconds will be set in the session-expires header.

callbackTimeout
number

Max time (including re-transmission attempts in milliseconds until the HTTPS callback is timing out

destinationMatch
required
string <regex>

Regular expression used to determine if incoming calls to the tenant should be handled by this service destination.

googleServiceKey
object

Google service key object used in case the Mediaservice should use Google text to speech services.

callbackDescription
string

An user given description that helps identifying the callback resource.

description
string

Description of the service destination.

callbackName
string

An user given name that helps identifying the callback resource.

callbackBaseUrl
required
string <uri>

HTTPS base URL where callback requests for the service is sent. NOTE: It must be a URL starting with https://

replySessionExpiration
number >= 0

This is an optional property that control the value of Session-Expires header time value in seconds for call originating from the mediaservice. It will per default set the ;refresher=uas property to request remote side to act as refresher.

required
Array of objects

Array of authentication objects. These objects are used to generate JWT bearer tokens to sign callback requests from the service destinaton. If a callback request authentication fails, the request will be re-sent with a signature generated using the next authentication object in the list until all objects have been used.

Array
sub
string

This property sets the sub property in the JWT signature

object

Object with custom headers to be added to the callback request.

scope
string

This property sets the scope property in the JWT signature

secret
string

This property should be set with the RS256 private key used to sign the JWT token if the type is RS256, the API key if type is token, the user:password base64 hash if type is basic.

type
string
Enum: "RS256" "token" "basic"

This property sets the type of authentication used for the callback requests from the service destination. See the REST API getting started guide for more information about API authentication.

rtpTimeout
number

Overrides the default RTP timeout value of 90 seconds. Set it to the desired value in seconds. If RTP media from remote side been silent for this time the IVR participant will be disconnected and it also triggers a service alarm.

callbackId
string

A generated id used to manage the callback resource.

offeredCodecs
Array of strings (Limit offered codecs)
Items Enum: "opus" "PCMA" "PCMU"

An array of codecs to be offered in case a SIP Invite is received without SDP. If this is not specified all codecs are offered. If incoming invite contains a SDP the answer match in inbound invite codec is set.

name
required
string

A name provided by the user to identify this service destination.

networkId
string

The platform supports network connectivity from many different public or private IP networks. If routing is not possible between these networks they may be assigned a networkId. This is an optional property indicating which networkId the media service should be bound to. If a call would originate or terminate from a SIP trunk assigned a different networkId media will must be anchored in the platform since no direct routing is possible between the networks.

id
string

Unique ID generated for the service destination

Responses

Request samples

Content type
application/json
{
  • "googleApikey": "string",
  • "disableLateOffer": true,
  • "ivrRefresherExpiration": 0,
  • "callbackTimeout": 0,
  • "destinationMatch": "/regex/",
  • "googleServiceKey": { },
  • "callbackDescription": "string",
  • "description": "string",
  • "callbackName": "string",
  • "callbackBaseUrl": "http://example.com",
  • "replySessionExpiration": 0,
  • "restAuthentication": [
    ],
  • "rtpTimeout": 0,
  • "callbackId": "string",
  • "offeredCodecs": [
    ],
  • "name": "string",
  • "networkId": "string",
  • "id": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "id": "string"
}

/mediaservice/{domain}/{mediaServiceId}

DELETE

Delete a specified Media Service configured for a domain.

Authorizations:
jwtAuthorizer
path Parameters
mediaServiceId
required
string
domain
required
string
query Parameters
provisory
string

A boolean indicating if the configurations to be deleted are provisory instead of the working configurations.

Responses

Response samples

Content type
application/json
{
  • "success": true
}

/mediaservice/{domain}/{mediaServiceId}

OPTIONS
path Parameters
mediaServiceId
required
string
domain
required
string
query Parameters
provisory
string

A boolean indicating if the configurations to be deleted are provisory instead of the working configurations.

Responses

Response samples

Content type
application/json
{ }

/mediaservice/{domain}/{mediaServiceId}

PATCH

Patch a specified Media Service configured for a domain.

Authorizations:
jwtAuthorizer
path Parameters
mediaServiceId
required
string
domain
required
string
query Parameters
provisory
string

A boolean indicating if the configurations to be deleted are provisory instead of the working configurations.

Request Body schema: application/json
required

The body of the request is an Array of operations as specified in the RFC 6902

Array
path
string

The path of the property inside the object. Should always start with slash (/). E.g.: /serviceData/alarmBridge/sipUri is the path to the deep property sipUri, of the alarmBridge that is a property of serviceData which is a property in root. In javascript this property is accessed like so: serviceData.alarmBridge.sipUri, from object { serviceData: { alarmBridge: { sipUri: 'sip:123test@iotcomms.io' }}}

op
string
Enum: "add" "remove" "replace" "copy" "move" "test"

String defining the operation to be performed. The supported operations are add, remove, replace, copy, move and test.

from
string

A path as described in the path property. Used for copy and move operations indicating where to copy/move from

value
string

The value of the property to be set. Valid for add, replace and test. The value could be of type string, number, object or array.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "reason": "string",
  • "success": true
}

/alarmbridge/{domain}/{alarmBridgeId}

GET
Authorizations:
jwtAuthorizer
path Parameters
domain
required
string
alarmBridgeId
required
string
query Parameters
provisory
string

A boolean indicating if the provisory configurations should be fetched instead of the working configurations.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "alarmbridge": {
    }
}

/alarmbridge/{domain}/{alarmBridgeId}

PUT

Overwrite the configurations of an Alarmbridge with specific id.

Authorizations:
jwtAuthorizer
path Parameters
domain
required
string
alarmBridgeId
required
string
query Parameters
provisory
string

A boolean indicating if the provisory configurations should be fetched instead of the working configurations.

Request Body schema: application/json
required

IVR configuration object

.

One of
protocol
required
string (Inbound protocol)
Enum: "api" "bs8521" "deviceProvisioned" "nowip" "scaip" "tt92" "ttnew" "multiprotocol" "voicecall" "nowipcontroller"

This property control which alarm protocol that is expected for incoming events to the service destination. To learn more, head to our Getting Started Alarmbridge guide.

protocolMode
required
string
Enum: "dtmf" "sdmf"

This property set additional configuration for configured protocol. Currently only applicable for tt92 protocol.

alarmEventMapperId
string

Id of the bridge service to be used by this service destination.

defaultHeartbeatInterval
number >= 300000
Default: 300000

Specified, in milliseconds, the default heartbeat interval value to be used for all devices. If this is set the heartbeat service is then enabled for all the devices sending heartbeat messages to this service destination. It could be overridden by setting the property when provisioning a device. The heartbeats are checked by our system every five minutes, so that is the minimum value that can be set (300000 milliseconds).

useVPNConnection
boolean (Use VPN Connection)
Default: false

Setting this property to true it will disable the NAT traversal logic in the SIP server and configure the media server to use private IP addresses.

fallbackAlarmProtocol
string
Enum: "bs8521" "scaip" "tt92" "ttnew"

This property is used in combination with the deviceProvisioned value of protocol property. It is set to the protocol to be used in case no device is found matching the CLI of the incoming alarm event.

callbackTimeout
number
Default: 15000

Max time in milliseconds for a response until a callback request is considered as a failure.

destinationMatch
required
string <regex>

Regular expression used to determine if incoming calls to the tenant should be handled by this service destination.

object

Set properties how to send DTMF tones for Alarmbridge service destination.

calleeDtmfSendType
string
Enum: "2833" "inaudio"

Set this property to control how DTMF tones are sent to remote destinations. Type inaudio which is default injects tones in the audio RTP stream. Type 2833 use RFC2833 tone packets in the RTP stream.

callerDtmfSendType
string
Enum: "2833" "inaudio"

Set this property to control how DTMF tones are sent to remote destinations. Type inaudio which is default injects tones in the audio RTP stream. Type 2833 use RFC2833 tone packets in the RTP stream.

dtmfSendType
string
Enum: "2833" "inaudio"

Set this property to control how DTMF tones are sent to remote destinations. Type inaudio which is default injects tones in the audio RTP stream. Type 2833 use RFC2833 tone packets in the RTP stream.

callbackDescription
string

An user given description that helps identifying the callback resource.

controlCommandsEnabled
boolean
Default: true

If this property is set to true the Alarmbridge will stay in the media path when a subsequent voice call have been established after reception of alarm event. If not set the media path will be straight between alarm device and alarm receiver. To be able to use the /devicecommand API to send commands to the alarm device during voice session this property must be set to true. NOTE: Use of this feature will result in one terminating and one originating Alarmbridge analogue call for the complete duration of the voice session and charged for accordingly.

description
string

Description of the service.

arcDisconnectClearsCall
boolean
Default: true

If this is set to true an incoming call hangup/BYE received from ARC would trigger a clear command to be sent to the connected alarm device before the call is hung up. If not set it is required to use the /alarmbridge/hangupalarmcall API to send the clear command before hanging up the call.

customEventMap
object

Object with rules that define how alarm events should be transformed in callback requests. See the getting-started document "Getting Started with Alarmbridge custom event mappings" for information of the structure of this object.

customerSiteId
string <regex> ^[a-zA-Z0-9_\-\.]+$

If this property is set the value will be copied to the customerSiteId property of /newAlarmbridgeEvent callbacks. It will also be used as to prefix controllerId:deviceId string for alarm device authentication lookup against provisioned devices. A provisioned devices identifier must be unique for a tenant, and this prefix allow different customer sites to use overlapping controllerId:deviceId configurations.

callbackName
string

An user given name that helps identifying the callback resource.

callbackBaseUrl
string <uri>

HTTPS base URL where callback requests for the service is sent. NOTE: It must be a URL starting with https://

Array of objects (Authentication)

This array contain objects used to authenticate callback requests. If the first object fail to authenticate the service will continue with the rest of objects in the list until success. More information of how these objects are constructed is found in the getting-started guide "Getting Started with iotcomms.io REST APIs."

Array
sub
string

If the REST authentication type is set to RS256, the sub property is added to the payload of the generated JSON Web Token(JWT).

requestHeaders
object

An object with headers to be added in the callback.

scope
string

If the REST authentication type is set to RS256, the scope property is added to the payload of the generated JSON Web Token(JWT).

secret
required
string

The secret property has different values depending on the type set for the REST authentication object. The type basic takes a string to be added to 'Basic ' in the Authorization header. The token type is added as 'Bearer ' to the Authorization header. The RS256 type will use the secret string to sign a JSON Web Token (JWT) to be added as 'Bearer ' to the Authorization header.

type
required
string
Enum: "RS256" "basic" "token"

Determines the content of the Authorization header that will be added to the callback request and how will the secret property be used. The type basic will set the Authorization header to string 'Basic '. The type token will set the Authorization header to 'Bearer '. The type RS256 will generate a JSON Web Token(JWT) signed with .

callbackId
string

A generated id used to manage the callback resource.

name
required
string

A name provided by the user to identify this service.

id
string

Unique ID generated for that resource

dataRequestInterval
number

Specifies in milliseconds the time between data request tones send by the service to alarm device. Applicable for bs8521 protocol. Defaults to 1600ms

defaultEmergencyDestination
string

This is the default emergency destination number used for new alarm events. It could be overridden by setting the property when provisioning a device.

Responses

Request samples

Content type
application/json
{
  • "tonePowers": [
    ],
  • "protocol": "api",
  • "protocolCandidates": [
    ],
  • "toneSettings": {
    },
  • "protocolModes": [
    ],
  • "alarmEventMapperId": "string",
  • "defaultHeartbeatInterval": 300000,
  • "useVPNConnection": false,
  • "fallbackAlarmProtocol": "bs8521",
  • "callbackTimeout": 15000,
  • "destinationMatch": "/regex/",
  • "callbackDescription": "string",
  • "controlCommandsEnabled": true,
  • "description": "string",
  • "arcDisconnectClearsCall": true,
  • "customEventMap": { },
  • "customerSiteId": "/regex/",
  • "callbackName": "string",
  • "callbackBaseUrl": "http://example.com",
  • "restAuthentication": [
    ],
  • "callbackId": "string",
  • "name": "string",
  • "id": "string",
  • "dataRequestInterval": 0,
  • "defaultEmergencyDestination": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "id": "string"
}

/alarmbridge/{domain}/{alarmBridgeId}

DELETE

Delete a specified Alarmbridge configured for a domain.

Authorizations:
jwtAuthorizer
path Parameters
domain
required
string
alarmBridgeId
required
string
query Parameters
provisory
string

A boolean indicating if the provisory configurations should be fetched instead of the working configurations.

Responses

Response samples

Content type
application/json
{
  • "success": true
}

/alarmbridge/{domain}/{alarmBridgeId}

OPTIONS
path Parameters
domain
required
string
alarmBridgeId
required
string
query Parameters
provisory
string

A boolean indicating if the provisory configurations should be fetched instead of the working configurations.

Responses

Response samples

Content type
application/json
{ }

/alarmbridge/{domain}/{alarmBridgeId}

PATCH

Patch a specified Alarmbridge configured for a domain.

Authorizations:
jwtAuthorizer
path Parameters
domain
required
string
alarmBridgeId
required
string
query Parameters
provisory
string

A boolean indicating if the provisory configurations should be fetched instead of the working configurations.

Request Body schema: application/json
required

The body of the request is an Array of operations as specified in the RFC 6902

Array
path
string

The path of the property inside the object. Should always start with slash (/). E.g.: /serviceData/alarmBridge/sipUri is the path to the deep property sipUri, of the alarmBridge that is a property of serviceData which is a property in root. In javascript this property is accessed like so: serviceData.alarmBridge.sipUri, from object { serviceData: { alarmBridge: { sipUri: 'sip:123test@iotcomms.io' }}}

op
string
Enum: "add" "remove" "replace" "copy" "move" "test"

String defining the operation to be performed. The supported operations are add, remove, replace, copy, move and test.

from
string

A path as described in the path property. Used for copy and move operations indicating where to copy/move from

value
string

The value of the property to be set. Valid for add, replace and test. The value could be of type string, number, object or array.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "reason": "string",
  • "success": true
}

/currentuser/profile

GET

Get the user profile for the signed in user.

Authorizations:
jwtAuthorizer

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "profile": {
    }
}

/currentuser/profile

PUT

Update the user profile for the signed in user.

Authorizations:
jwtAuthorizer
Request Body schema: application/json
required
firstName
string
lastName
string
emailConsent
integer <int32>

Timestamp of when consent to receive email communication was given

phone
string
company
string
email
string

Responses

Request samples

Content type
application/json
{
  • "firstName": "string",
  • "lastName": "string",
  • "emailConsent": 0,
  • "phone": "string",
  • "company": "string",
  • "email": "string"
}

Response samples

Content type
application/json
{
  • "success": true
}

/currentuser/profile

POST

Create a user profile for a user signing in for the first time.

Authorizations:
jwtAuthorizer
Request Body schema: application/json
required
authProvider
string

Authentication provider used to manage user authentication.

firstName
string
lastName
string
otherInfo
string

Other information.

useCase
string

Target use case for service.

termsAgreed
integer <int32>

Timestamp indicating when the terms and conditions consent was made.

emailConsent
integer <int32>

Timestamp of when consent to receive email communication was given

phone
string
company
string
profileReviewed
boolean

Indicates that the profile has been reviewed by user.

deploymentSize
string

Target deployment size.

email
string

Responses

Request samples

Content type
application/json
{
  • "authProvider": "string",
  • "firstName": "string",
  • "lastName": "string",
  • "otherInfo": "string",
  • "useCase": "string",
  • "termsAgreed": 0,
  • "emailConsent": 0,
  • "phone": "string",
  • "company": "string",
  • "profileReviewed": true,
  • "deploymentSize": "string",
  • "email": "string"
}

Response samples

Content type
application/json
{
  • "success": true
}

/currentuser/profile

OPTIONS

Responses

Response samples

Content type
application/json
{ }

/currentuser/profile

PATCH

Patch a user profile.

Authorizations:
jwtAuthorizer
Request Body schema: application/json
required
firstName
string
lastName
string
emailConsent
integer <int32>

Timestamp of when consent to receive email communication was given

phone
string
company
string
email
string

Responses

Request samples

Content type
application/json
{
  • "firstName": "string",
  • "lastName": "string",
  • "emailConsent": 0,
  • "phone": "string",
  • "company": "string",
  • "email": "string"
}

Response samples

Content type
application/json
{
  • "success": true
}

/cloudsipua/{domain}/{cloudSipUAId}

GET
Authorizations:
jwtAuthorizer
path Parameters
domain
required
string
cloudSipUAId
required
string
query Parameters
provisory
string

A boolean indicating if the provisory configurations should be fetched instead of the working configurations.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "cloudsipua": {
    }
}

/cloudsipua/{domain}/{cloudSipUAId}

PUT

Overwrite the configurations of an Cloud SIP User Agent with specific id.

Authorizations:
jwtAuthorizer
path Parameters
domain
required
string
cloudSipUAId
required
string
query Parameters
provisory
string

A boolean indicating if the configurations to be deleted are provisory instead of the working configurations.

Request Body schema: application/json
required

IVR configuration object

.

Array of objects

Array of authentication objects. These objects are used to generate JWT bearer tokens to sign callback requests from the service destinaton. If a callback request authentication fail, the request will be re-sent and signature generated using the next authentication object in the list until all objects been used.

Array
sub
string

This property sets the sub property in the JWT signature

object

Object with custom headers to be added to the callback request.

scope
string

This property sets the scope property in the JWT signature

secret
string

This property should be set with the RS256 private key used to sign the JWT token if the type is RS256, the API key if type is token, the user:password base64 hash if type is basic.

type
string
Enum: "RS256" "token" "basic"

This property sets the type of authentication used for the callback requests from the service destination. See the REST API getting started guide for more information about API authentication.

callbackTimeout
number
callbackId
string

A generated id used to manage the callback resource.

destinationMatch
required
string <regex>

Regular expression used to determine if incoming calls to the tenant should be handled by this service destination.

callbackDescription
string

An user given description that helps identifying the callback resource.

name
required
string

A name provided by the user to identify this service.

description
string

Description of the service.

id
string

Unique ID generated for that resouce

callbackName
string

An user given name that helps identifying the callback resource.

callbackBaseUrl
required
string <uri>

HTTPS base URL where callback requests for the service is sent. NOTE: It must be a URL starting with https://

Responses

Request samples

Content type
application/json
{
  • "restAuthentication": [
    ],
  • "callbackTimeout": 0,
  • "callbackId": "string",
  • "destinationMatch": "/regex/",
  • "callbackDescription": "string",
  • "name": "string",
  • "description": "string",
  • "id": "string",
  • "callbackName": "string",
  • "callbackBaseUrl": "http://example.com"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "id": "string"
}

/cloudsipua/{domain}/{cloudSipUAId}

DELETE

Delete a specified Cloud SIP User Agent configured for a domain.

Authorizations:
jwtAuthorizer
path Parameters
domain
required
string
cloudSipUAId
required
string
query Parameters
provisory
string

A boolean indicating if the configurations to be deleted are provisory instead of the working configurations.

Responses

Response samples

Content type
application/json
{
  • "success": true
}

/cloudsipua/{domain}/{cloudSipUAId}

OPTIONS
path Parameters
domain
required
string
cloudSipUAId
required
string
query Parameters
provisory
string

A boolean indicating if the configurations to be deleted are provisory instead of the working configurations.

Responses

Response samples

Content type
application/json
{ }

/cloudsipua/{domain}/{cloudSipUAId}

PATCH

Patch a specified Cloud SIP User Agent configured for a domain.

Authorizations:
jwtAuthorizer
path Parameters
domain
required
string
cloudSipUAId
required
string
query Parameters
provisory
string

A boolean indicating if the configurations to be deleted are provisory instead of the working configurations.

Request Body schema: application/json
required

The body of the request is an Array of operations as specified in the RFC 6902

Array
path
string

The path of the property inside the object. Should always start with slash (/). E.g.: /serviceData/alarmBridge/sipUri is the path to the deep property sipUri, of the alarmBridge that is a property of serviceData which is a property in root. In javascript this property is accessed like so: serviceData.alarmBridge.sipUri, from object { serviceData: { alarmBridge: { sipUri: 'sip:123test@iotcomms.io' }}}

op
string
Enum: "add" "remove" "replace" "copy" "move" "test"

String defining the operation to be performed. The supported operations are add, remove, replace, copy, move and test.

from
string

A path as described in the path property. Used for copy and move operations indicating where to copy/move from

value
string

The value of the property to be set. Valid for add, replace and test. The value could be of type string, number, object or array.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "reason": "string",
  • "success": true
}

/alarmbridge/{domain}/testconfiguration/{destination}

GET
Authorizations:
jwtAuthorizer
path Parameters
domain
required
string
destination
required
string

Responses

Response samples

Content type
application/json
{
  • "receiver": "string",
  • "sender": "string",
  • "success": true
}

/alarmbridge/{domain}/testconfiguration/{destination}

OPTIONS
path Parameters
domain
required
string
destination
required
string

Responses

Response samples

Content type
application/json
{ }

/serviceprofile/{domain}

GET

Get service profile information for the tenant of the provided domain.

Authorizations:
jwtAuthorizer
path Parameters
domain
required
string

Responses

Response samples

Content type
application/json
{ }

/serviceprofile/{domain}

OPTIONS
path Parameters
domain
required
string

Responses

Response samples

Content type
application/json
{ }

/mediaservice/{domain}/testconfiguration/{destination}

GET
Authorizations:
jwtAuthorizer
path Parameters
domain
required
string
destination
required
string

Responses

Response samples

Content type
application/json
{
  • "receiver": "string",
  • "sender": "string",
  • "success": true
}

/mediaservice/{domain}/testconfiguration/{destination}

OPTIONS
path Parameters
domain
required
string
destination
required
string

Responses

Response samples

Content type
application/json
{ }

/logs/{domain}/sip

POST

Gets SIP log items for specified domain based on the posted filter criteria.

Authorizations:
jwtAuthorizer
path Parameters
domain
required
string
Request Body schema: application/json
required
filterPattern
string

String with filter critera to be matched for returned log items.

limit
integer <int32>

Maximum number of log items to be returned.

startTime
integer <int32>

Timestamp of beginning of interval to fetch log items for.

endTime
integer <int32>

Timestamp of end of interval to fetch log items for.

Responses

Request samples

Content type
application/json
{
  • "filterPattern": "string",
  • "limit": 0,
  • "startTime": 0,
  • "endTime": 0
}

Response samples

Content type
application/json
{
  • "success": true,
  • "logItems": [
    ]
}

/logs/{domain}/sip

OPTIONS
path Parameters
domain
required
string

Responses

Response samples

Content type
application/json
{ }

/authorize/{domain}

POST

Authorize credentials request from API user.

path Parameters
domain
required
string
Request Body schema: application/json
required

authorization body

password
string

Password of to be used for authorization.

userId
string

UserId of user to ne authorized.

Responses

Request samples

Content type
application/json
{
  • "password": "string",
  • "userId": "string"
}

Response samples

Content type
application/json
{
  • "result": true,
  • "authorized": "string"
}

/authorize/{domain}

OPTIONS
path Parameters
domain
required
string

Responses

Response samples

Content type
application/json
{ }

/siprecservice/{domain}

GET

Get siprec service.

Authorizations:
jwtAuthorizer
path Parameters
domain
required
string

Responses

Response samples

Content type
application/json
{
  • "restAuthentication": [
    ],
  • "alarmTopic": "string",
  • "httpTimeout": 0,
  • "sipEventsTopic": "string",
  • "useHttpEvents": true,
  • "alarmEventsRestEndpoint": "string",
  • "sipEventsRestEndpoint": "string",
  • "alarmbridgeCallbackEndpoint": "string"
}

/siprecservice/{domain}

PUT

Set siprec service.

Authorizations:
jwtAuthorizer
path Parameters
domain
required
string
Request Body schema: application/json
required

Siprec service settings object.

Array of objects (restAuthentication)
Array
sub
string

If the REST authentication type is set to RS256, the sub property is added to the payload of the generated JSON Web Token(JWT).

requestHeaders
object

An object with headers to be added in the callback.

scope
string

If the REST authentication type is set to RS256, the scope property is added to the payload of the generated JSON Web Token(JWT).

secret
required
string

The secret property has different values depending on the type set for the REST authentication object. The type basic takes a string to be added to 'Basic ' in the Authorization header. The token type is added as 'Bearer ' to the Authorization header. The RS256 type will use the secret string to sign a JSON Web Token (JWT) to be added as 'Bearer ' to the Authorization header.

type
required
string
Enum: "RS256" "basic" "token"

Determines the content of the Authorization header that will be added to the callback request and how will the secret property be used. The type basic will set the Authorization header to string 'Basic '. The type token will set the Authorization header to 'Bearer '. The type RS256 will generate a JSON Web Token(JWT) signed with .

alarmTopic
string

AWS ARN of SNS topic where the service will post service alarms as specified in the SNS alarmTopic API.

httpTimeout
integer <int32>

Total timeout in milliseconds before callback request including three re-try attempts will fail.

sipEventsTopic
string

AWS ARN of SNS topic where the service will post events as specified in the SNS sipEventsTopic API.

useHttpEvents
boolean

If this is set to true HTTPS will be used for callback notifications and not SNS for sipEvents and alarms.

alarmEventsRestEndpoint
string

this is set to true HTTPS will be used for serve notifications and not SNS for sipEvents and alarms.

sipEventsRestEndpoint
string

REST callback base URL to be used for sipEvents notifications. Must start with http:// or https://

alarmbridgeCallbackEndpoint
string

REST callback base URL to be used for alarmbridge service callbacks. Must start with http:// or https://

Responses

Request samples

Content type
application/json
{
  • "restAuthentication": [
    ],
  • "alarmTopic": "string",
  • "httpTimeout": 0,
  • "sipEventsTopic": "string",
  • "useHttpEvents": true,
  • "alarmEventsRestEndpoint": "string",
  • "sipEventsRestEndpoint": "string",
  • "alarmbridgeCallbackEndpoint": "string"
}

Response samples

Content type
application/json
{
  • "success": true
}

/siprecservice/{domain}

OPTIONS
path Parameters
domain
required
string

Responses

Response samples

Content type
application/json
{ }

/alarmeventmapper/{domain}/{alarmEventMapperId}

GET
Authorizations:
jwtAuthorizer
path Parameters
alarmEventMapperId
required
string
domain
required
string
query Parameters
provisory
string

A boolean indicating if the provisory configurations should be fetched instead of the working configurations.

Responses

Response samples

Content type
application/json
{
  • "alarmeventmapper": {
    },
  • "success": true
}

/alarmeventmapper/{domain}/{alarmEventMapperId}

PUT

Overwrite the configurations of an Alarm Event Mapper with specific id.

Authorizations:
jwtAuthorizer
path Parameters
alarmEventMapperId
required
string
domain
required
string
query Parameters
provisory
string

A boolean indicating if the provisory configurations should be fetched instead of the working configurations.

Request Body schema: application/json
required

IVR configuration object

.

One of
alarmHandling
required
string
Enum: "callEmergencyCenter" "usePredefinedDestination" "requestCallback" "drop"

Alarmbridge will signal back to the alarm device to clear the alarm event without any subsequent voice call.

required
object
protocol
required
string (Outbound protocol)
Enum: "scaip" "bs8521" "sia-dcs" "ttnewGroupDevice" "nowipGroupDevice" "nowip" "voicecall"

The protocol of the event to be sent to the endpoint

sipAuthUser
string (SIP authentication username)

The username used for SIP authenication.

sipAuthPassword
string (SIP authentication password)

The password used for SIP authenication.

destAddr
required
string (Destination Address)

The address of the endpoint

overrideSipFrom
string (Override userinfo part of SIP From-header)

Override the SIP from header with the information specified.

defaultVoiceDestination
string (Default Voice Destination)

The default voice destination if CRE 61.

object
backupOverrideSipFrom
string (Override userinfo part of SIP From-header)

Override the SIP from header with the information specified.

backupSipAuthPassword
string (SIP authentication password)

The password used for SIP authenication.

backupDefaultVoiceDestination
string (Default Voice Destination)

The default voice destination if CRE 61.

backupSipAuthUser
string (SIP authentication username)

The username used for SIP authenication.

backupDestAddr
string (Destination Address)

The address of the endpoint

deviceIdPadLength
integer <int32> (DeviceId Pad Length) [ 0 .. 10 ]
Default: 0

Enable leading zero padding of deviceId before concatenation. Only used if Map Device Id To Controller Id is activated.

description
string

Description of the service.

mappingRules
object

The mapping rules let protocol specific alarm mapping rules to be specified. See the protocol specific documentation for more details. This is found in the Alarmbridge getting started documentation section, document "Getting Started with Alarmbridge custom event mappings"

unknownAlarmEventVoiceDestination
string

This property is configured with a SIP URI pointing to a fallback voice destination to be used in case an incoming alarm event can't be decoded and there is no calling party phone number. For inbound analogue alarm calls it will connect the incoming call with this destination upon alarm event decode failure.

fromDomain
string (From domain)

Used to override the domain portion portion of the SIP From: header. Usually set to the domain of the tenant. With this field any domain can be set.

maxSessionDuration
number (Maximum session duration)

This can be used to override the default value for the time a session exist in the service.

controllerIdPadLength
integer <int32> (ControllerId Pad Length) [ 0 .. 10 ]
Default: 0

Enable leading zero padding of controllerId before concatenation. Only used if Map Device Id To Controller Id is activated.

name
required
string

A user provided name to identify this service.

mapDeviceIdToControllerId
boolean
Default: false

If true it will concatenate controllerId and deviceId and then remove deviceId from the alarm event.

useVoiceBridge
boolean

Switches the usage of voice bridge on and off.

callerId
string (Caller Id)

Used to override the callerId field in the outbound alarmevent.

id
string

The id of a Bridge Service configuration to be used as sender for the event.

enableDestinationMonitoring
boolean (Enable Destination Monitoring)

Monitor if target or backup is active

Responses

Request samples

Content type
application/json
{
  • "alarmHandling": "callEmergencyCenter",
  • "waitForCallback": 5,
  • "targetEndpoint": {
    },
  • "deviceIdPadLength": 0,
  • "description": "string",
  • "mappingRules": { },
  • "unknownAlarmEventVoiceDestination": "string",
  • "fromDomain": "string",
  • "maxSessionDuration": 0,
  • "controllerIdPadLength": 0,
  • "name": "string",
  • "mapDeviceIdToControllerId": false,
  • "useVoiceBridge": true,
  • "callerId": "string",
  • "id": "string",
  • "enableDestinationMonitoring": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "id": "string"
}

/alarmeventmapper/{domain}/{alarmEventMapperId}

DELETE

Delete a specified Alarm Event Mapper configured for a domain.

Authorizations:
jwtAuthorizer
path Parameters
alarmEventMapperId
required
string
domain
required
string
query Parameters
provisory
string

A boolean indicating if the provisory configurations should be fetched instead of the working configurations.

Responses

Response samples

Content type
application/json
{
  • "success": true
}

/alarmeventmapper/{domain}/{alarmEventMapperId}

OPTIONS
path Parameters
alarmEventMapperId
required
string
domain
required
string
query Parameters
provisory
string

A boolean indicating if the provisory configurations should be fetched instead of the working configurations.

Responses

Response samples

Content type
application/json
{ }

/alarmeventmapper/{domain}/{alarmEventMapperId}

PATCH

Patch a specified Alarm Event Mapper configured for a domain.

Authorizations:
jwtAuthorizer
path Parameters
alarmEventMapperId
required
string
domain
required
string
query Parameters
provisory
string

A boolean indicating if the provisory configurations should be fetched instead of the working configurations.

Request Body schema: application/json
required

The body of the request is an Array of operations as specified in the RFC 6902

Array
path
string

The path of the property inside the object. Should always start with slash (/). E.g.: /serviceData/alarmBridge/sipUri is the path to the deep property sipUri, of the alarmBridge that is a property of serviceData which is a property in root. In javascript this property is accessed like so: serviceData.alarmBridge.sipUri, from object { serviceData: { alarmBridge: { sipUri: 'sip:123test@iotcomms.io' }}}

op
string
Enum: "add" "remove" "replace" "copy" "move" "test"

String defining the operation to be performed. The supported operations are add, remove, replace, copy, move and test.

from
string

A path as described in the path property. Used for copy and move operations indicating where to copy/move from

value
string

The value of the property to be set. Valid for add, replace and test. The value could be of type string, number, object or array.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "reason": "string",
  • "success": true
}

/grandstream/{domain}/{mac}

GET
Authorizations:
jwtAuthorizerAsShortParameter
path Parameters
mac
required
string

The MAC address of the device to fetch configuration for.

domain
required
string

The domain of the tenant to get device configuration for.

query Parameters
k
required
string

Valid API secret to authenticate the device.

Responses

/grandstream/{domain}/{mac}

OPTIONS
path Parameters
mac
required
string

The MAC address of the device to fetch configuration for.

domain
required
string

The domain of the tenant to get device configuration for.

Responses

Response samples

Content type
application/json
{ }