Add SIP Connections

The Add SIP Connections request adds a SIP Connection for the customer. Once you have setup the primary SIP Connection, you can add additional branch sites and then provision SBC prefixes for the users at this site location.

URL

Copy 
{{baseUrl}}/api/v2/customer/{customerGuid}/sitelocation/

HTTP Method

POST

Request Headers

Parameter

Type

Description

X-Ovoc-Channel-Id

integer

The Live Platform channel "id". When specified, data retrieval is scoped to only customerGuid values attached to the specified channel (see Get List of Channels to extract this value).

X-IAM-Account-Id

string

The Live Platform "iamAccountId" of the channel. When specified, data retrieval is scoped to only customerGuid values attached to the specified channel (see Get List of Channels to extract this value).

Request Parameters

Parameter

Type

Description

customerGuid

string($uuid)

'CustomerGuid' value created in the Live Platform customer tenant SQL database directory:

■ Operator Connect: A new OC Essentials service is created when a license is applied to the lead using Create Service from Lead Overview). If this field is null, a license has not yet been applied to the lead.
■ Direct Routing: The unique Id created for the Hosted Essentials service Create Hosted Essentials Service.

Extract this value using Get Services Brief Details (V3) or Get Customers Brief Details (V2) searching for the matching Short Name of the service.

Request Body

Parameter

Type

Description

siteLocationName

string

Desired name of the site location, complying with the following validation rules:

■ The string should be 3-15 characters long
■ The following characters cannot be used: \ / : * ? " < > |audit
■ Can contain letters (lower and upper case), numbers and special characters are allowed, however cannot contain the dot (.) or blank spaces.

ovocCustomerType
■ IPGROUP_TYPE string
■ TENANT_TYPE string
■ IPGROUP_TYPE: An IP Group is created for each new customer based on the Customer Shortname. This type is used for the Access Trunk Direct Routing (used for Direct Routing customers when SIP Registration is required). An link is established with the Live Platform server (OVOC) using this IP group.
■ Tenant ID:-The new customer is created based on the customer's Azure tenant subscription Id. A link is established with the Live Cloud server (OVOC) using this tenant Id.

sbcId

integer

The SBC Id in the Live Platform database (see Get SBC Devices).

sbcOnboardingScript

integer

The SBC Onboarding script value in the Live Platform database (see Get Script Templates).

sbcCleanupScript

integer

The SBC Cleanup script value in the Live Platform database (see Get Script Templates).

sbcConfigurationType

integer

Determines the configuration mode for configuration of the SBC device:

■ SIP Trunk: SIP Trunk used by the Service Provider. When this option is selected, you must select both the SBC device (see 'Region' field below) and the Service Provider Carrier SIP Trunk (see 'Carrier' field below).
■ IP-PBX: Service Provider IP-PBX. When this option is selected, you must select both the SBC device and the Service Provider Carrier SIP Trunk (see 'Region' field below).
■ BYOC: (Bring-Your-Own-Carrier) for integrating customer SIP Trunk services that are different to the SIP Trunk service used by the Service Provider. When this option is selected, you must select both the SBC device (see 'Region' field below) and the Service Provider Carrier SIP Trunk (see 'Carrier' field below).

Known Script parameters

OnlinePstnGateway

string

The FQDN of the Online PSTN Gateway for the SBC device managing calling functionality for the tenant (required for IPGROUP_TYPE and TENANT_TYPE_GW).

Proxy Set

string

SBC Proxy Set

CACProfile

string

Call Admission Control profile name.

CarrierUserName

string

The digest MD5 Authentication username. The valid value is a string of up to 60 characters. By default, no value is defined.

CarrierUserPassword

string

The digest MD5 Authentication password. The valid value is a string of up to 50 characters. Note: The password cannot be configured with wide characters.

CarrierMainLine

string

The AOR username. This appears in REGISTER From/To headers as ContactUser@HostName.

CarrierHostName

string

The Address of Record (AOR) host name. The host name appears in SIP REGISTER From/To headers as ContactUser@HostName.

Custom Script parameters

scriptParameters refers to:

CustomVar.Variable<VariableSequenceNumber>

dictionary

where <VariableSequenceNumber> is the sequence in database that the variable is defined in the 'Customer variables' column for the script properties (see Customer Variables).

For example, when the following IP-PBX variables are defined in the database in the order: IPPBX-ProxyAddress, IPPBX-ProxyAddress-SIPPort, SIP-HostName then Custom variables should be defined as follows:

■ CustomVar.Variable1: <: IPPBX-ProxyAddress>
■ CustomVar.Variable2: < IPPBX-ProxyAddress-SIPPort>
■ CustomVar.Variable3: <SIP-HostName>

 

Custom variables can be defined to update specific parameters on the SBC device. These variables must be predefined in the UMP-365 database (see Customer Variables). Also verify that the custom variables notation has been added to the script (see parameter 'sbcOnboardingScript' above) that you are applying to the request.

There are three fields displayed in the schema additionalProp1-3, however there is no limitation for the number of variables that can be added.

additionalProp1

string

Custom script argument.

additionalProp2

string

Custom script argument.

additionalProp3

string

Custom script argument.

Example Body

Copy 
{
"siteLocationName": "Mitcham",
"OvocCustomerType":"IPGROUP_TYPE",
"sbcOnboardingScript": 2010,
"sbcCleanupScript": 2011,
"sbcId": 8,
"scriptParameters": {
  "OnlinePstnGateway": "sandbox3apac.audiocodes.be",
  "ProxySet": "SIPTrunk",
  "CacProfile": "10 sessions" 
  }
}

Example Response

Copy 
{
    "customerGuid": "b38e5a04-6d32-4be8-95bb-53bf7d6fa95c",
    "siteGuid": "a344470f-e54e-4897-b28e-d1c2c0c404f0",
    "executionMessages": [
        {
            "level": "Information",
            "message": "Skipping SBC CheckIpGroupProgramming."
        },
        {
            "level": "Information",
            "message": "Starting SBC Programming."
        },
        {
            "level": "Information",
            "message": "Sbc is programmed"
        },
        {
            "level": "Information",
            "message": "Site location information saved."
        }
    ]
}

HTTP Responses

■ 200 OK
Parameter Type Description

Customer Id

string($uuid)

Unique Id generated for customer. Search for the customer Id by searching for your customer name using Get Services Brief Details (V3).

siteGuid

string($uuid)

Unique Id generated for the SIP Connection (site location).

executionMessages

list array

List array including the following parameters:

■ level
■ message

level

string

One of the following values:

■ Information
■ Error

message

string

Information message text includes the following strings:

■ Checking SBC IP Group Programming
■ SBC not programmed yet
■ Starting SBC Programming
■ Sbc is programmed
■ Site location information saved
■ 400 Bad Request

Parameter

Type

Description/Examples

errors

string

 Text description of the error.

type

string

"https://tools.ietf.org/html/rfc7231#section-6.5.1"

title

string

Email title. For example "One or more validation errors occurred."

status

error code

HTML error code i.e. 400

detail

string

Additional error details.

traceId

string

Error trace Id

instance

string

Error instance

errorTicket

string

This field may not appear for all return codes.

errorCode

string

This field may not appear for all return codes.

additionalProp1

string

Custom Script variable argument. For example "CacProfile": "5 sessions"

additionalProp2

string

Custom Script argument. For example, ProxySet": "SIPTrunk",

additionalProp3

string

Custom Script argument. For example, "OnlinePstnGateway": "sandbox1.audiocodes.be"
■ 403 Forbidden: this error is raised when an attempt is made to add a SIP connection that belongs to a customer that is not attached to the channel as specified by X-Ovoc-Channel-Id or X-IAM-Account-Id values.

Parameter

Type

Description/Examples

errors

string

 Text description of the error.

type

string

"https://tools.ietf.org/html/rfc7231#section-6.5.1"

title

string

Email title. For example "One or more validation errors occurred."

status

error code

HTML error code i.e. 400

detail

string

Additional error details.

traceId

string

Error trace Id

instance

string

Error instance

errorTicket

string

This field may not appear for all return codes.

errorCode

string

This field may not appear for all return codes.

additionalProp1

string

Custom Script variable argument. For example "CacProfile": "5 sessions"

additionalProp2

string

Custom Script argument. For example, ProxySet": "SIPTrunk",

additionalProp3

string

Custom Script argument. For example, "OnlinePstnGateway": "sandbox1.audiocodes.be"
■ 404 Not Found

Parameter

Type

Description/Examples

errors

string

 Text description of the error.

type

string

"https://tools.ietf.org/html/rfc7231#section-6.5.1"

title

string

Email title. For example "One or more validation errors occurred."

status

error code

HTML error code i.e. 400

detail

string

Additional error details.

traceId

string

Error trace Id

instance

string

Error instance

errorTicket

string

This field may not appear for all return codes.

errorCode

string

This field may not appear for all return codes.

additionalProp1

string

Custom Script variable argument. For example "CacProfile": "5 sessions"

additionalProp2

string

Custom Script argument. For example, ProxySet": "SIPTrunk",

additionalProp3

string

Custom Script argument. For example, "OnlinePstnGateway": "sandbox1.audiocodes.be"
■ 409 Conflict

Parameter

Type

Description/Examples

errors

string

 Text description of the error.

type

string

"https://tools.ietf.org/html/rfc7231#section-6.5.1"

title

string

Email title. For example "One or more validation errors occurred."

status

error code

HTML error code i.e. 400

detail

string

Additional error details.

traceId

string

Error trace Id

instance

string

Error instance

errorTicket

string

This field may not appear for all return codes.

errorCode

string

This field may not appear for all return codes.

additionalProp1

string

Custom Script variable argument. For example "CacProfile": "5 sessions"

additionalProp2

string

Custom Script argument. For example, ProxySet": "SIPTrunk",

additionalProp3

string

Custom Script argument. For example, "OnlinePstnGateway": "sandbox1.audiocodes.be"
■ 500 Internal Server Error