Group Trunking Users (Numbers)

Display group’s trunking users list

DEPRECATED URL GET /api/v1/tenants/(string:tenant_id)/groups/(string:group_id)/services/trunk_users/(string:instance_name)/

GET /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/services/trunk_groups/(string: instance_name)/numbers/

Get the details about the list of the trunk users assigned to a trunk group.

It is also possible to get the list of numbers of the trunk users.

Example request:

GET /api/v1/tenants/foo/groups/foogroup/services/trunk_groups/footrunkgroup/numbers/ HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: "application/json"

{
   "users": [
      {
         "userId": "+3228001104@sip.netaxis.be",
         "lastName": "3228001104",
         "firstName": "3228001104",
         "department": "",
         "phoneNumber": "+3228001104",
         "extension": "",
         "emailAddress": ""
      },
      {
         "userId": "+3228001109@sip.netaxis.be",
         "lastName": "3228001109",
         "firstName": "3228001109",
         "department": "",
         "phoneNumber": "+3228001109",
         "extension": "",
         "emailAddress": ""
      }
   ]
}
Response JSON Object:
Status Codes:

Retrieve the list of the users assigned to a trunk group with search criteria.

Example request:

GET /api/v1/tenants/foo/groups/foogroup/services/trunk_groups/footrunkgroup/numbers/ HTTP/1.1
Host: example.com

{
   "insensitiveUserIdStarts": "+322800",
   "insensitiveUserLastNameContains": "9",
   "returnNumbers": true
}
Request JSON Object:

  • sensitiveUserIdStarts (string) – See sensitiveUserIdStarts from Search criteria.

  • sensitiveUserIdContains (string) – See sensitiveUserIdContains from Search criteria.

  • sensitiveUserIdEquals (string) – See sensitiveUserIdEquals from Search criteria.

  • insensitiveUserIdStarts (string) – See insensitiveUserIdStarts from Search criteria.

  • insensitiveUserIdContains (string) – See insensitiveUserIdContains from Search criteria.

  • insensitiveUserIdEquals (string) – See insensitiveUserIdEquals from Search criteria.

  • sensitiveUserLastNameStarts (string) – See sensitiveUserLastNameStarts from Search criteria.

  • sensitiveUserLastNameContains (string) – See sensitiveUserLastNameContains from Search criteria.

  • sensitiveUserLastNameEquals (string) – See sensitiveUserLastNameEquals from Search criteria.

  • insensitiveUserLastNameStarts (string) – See insensitiveUserLastNameStarts from Search criteria.

  • insensitiveUserLastNameContains (string) – See insensitiveUserLastNameContains from Search criteria.

  • insensitiveUserLastNameEquals (string) – See insensitiveUserLastNameEquals from Search criteria.

  • sensitiveUserFirstNameStarts (string) – See sensitiveUserFirstNameStarts from Search criteria.

  • sensitiveUserFirstNameContains (string) – See sensitiveUserFirstNameContains from Search criteria.

  • sensitiveUserFirstNameEquals (string) – See sensitiveUserFirstNameEquals from Search criteria.

  • insensitiveUserFirstNameStarts (string) – See insensitiveUserFirstNameStarts from Search criteria.

  • insensitiveUserFirstNameContains (string) – See insensitiveUserFirstNameContains from Search criteria.

  • insensitiveUserFirstNameEquals (string) – See insensitiveUserFirstNameEquals from Search criteria.

  • insensitivePhoneNumberStarts (string) – See insensitivePhoneNumberStarts from Search criteria.

  • insensitivePhoneNumberContains (string) – See insensitivePhoneNumberContains from Search criteria.

  • insensitivePhoneNumberEquals (string) – See insensitivePhoneNumberEquals from Search criteria.

  • sensitiveEmailAddressStarts (string) – See sensitiveEmailAddressStarts from Search criteria.

  • sensitiveEmailAddressContains (string) – See sensitiveEmailAddressContains from Search criteria.

  • sensitiveEmailAddressEquals (string) – See sensitiveEmailAddressEquals from Search criteria.

  • insensitiveEmailAddressStarts (string) – See insensitiveEmailAddressStarts from Search criteria.

  • insensitiveEmailAddressContains (string) – See insensitiveEmailAddressContains from Search criteria.

  • insensitiveEmailAddressEquals (string) – See insensitiveEmailAddressEquals from Search criteria.

  • insensitiveExtensionStarts (string) – See insensitiveExtensionStarts from Search criteria.

  • insensitiveExtensionContains (string) – See insensitiveExtensionContains from Search criteria.

  • insensitiveExtensionEquals (string) – See insensitiveExtensionEquals from Search criteria.

  • responseSizeLimit (integer) – See responseSizeLimit from Search criteria.

  • returnNumbers (boolean) – Return a list of numbers instead of a list of users

Example response:

HTTP/1.1 200 OK
Content-Type: "application/json"

{
   "numbers": ["+3228001109"]
}
Response JSON Object:
Status Codes:

Add Trunks Users to a Trunk Group

POST /api/v1/tenants/foo/groups/foogroup/services/trunk_groups/footrunkgroup/numbers/

Create new Trunk Users for a Trunk Group based on numbers

Example request:

POST /api/v1/tenants/foo/groups/foogroup/numbers/services/trunk_groups/footrunkgroup/numbers/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
   "numbers": [
      {"phoneNumber": "021234567", "extId": "whatever@microsoft.com"},
      {"phoneNumber": "041234567"}
   ],
   "range": {
      "minPhoneNumber": "071568000",
      "maxPhoneNumber": "071568002"
   },
   "templateName": "basic"
}
Request JSON Object:

  • numbers (array) – the list of numbers to be used to create trunk users. When creating Trunk Users with integration with external system (such as MS Teams DR Trunk) an “extId” can be defined. It will not be handled by the GW but will be provided in the answer.

  • range (array) – the range of numbers to be added as a list of 2 numbers (start and end). Note: “extId” is not supported for ranges.

  • templateName (string) – As defined as Template Name.

  • auto_create (boolean) – Optional flag to request that if the number does not exists yet at Tenant or Group level, it is added to at these levels. It must be noted that if not present a global configuration settings will be used.

  • return_linePort (boolean) – Optional flag to request that for successfully created trunk users, the linePort is provided in the answer. Default is False.

  • return_userId (boolean) – Optional flag to request that for successfully created trunk users, the User Id is provided in the answer. Default is false.

  • The automatic creation at Tenant level and Group level will only be aplied is the client has the needed access rights.

  • This feature can also be activated globally at APIO level (see below). In that case if the flag is not present in the request the auto-creation will be performed anyway.

Example response:

HTTP/1.1 207 Multi-Status
Content-Type: "application/json"

{
   "result": [
      {"phoneNumber": "021234567", "status": "added", "extId": "whatever@microsoft.com"},
      {"phoneNumber": "041234567", "status": "rejected"},
      {"phoneNumber": "071568000", "status": "added", "extId": ""},
      {"phoneNumber": "071568001", "status": "added", "extId": ""},
      {"phoneNumber": "071568002", "status": "added", "extId": ""}
   ],
   "trunkingMode": "teamsDR"
}
Response JSON Object:

  • result (array) – a list of objects containing the number, it’s status (‘added’, ‘rejected’, ‘available’) and the “extId” provided in input in case “special” “runk (not present for normal trunk) . See Group Trunking Users Result.

  • trunkingMode (string) – the trunking mode (‘normal’, ‘teamsDR’).

Status Codes:

Move Trunks Users to a Trunk Group

POST /api/v1/tenants/foo/groups/foogroup/services/trunk_groups/footrunkgroup/numbers/

Move Trunk Users, based on numbers, from a Trunk Group to this Trunk Group

Example request:

POST /api/v1/tenants/foo/groups/foogroup/numbers/services/trunk_groups/footrunkgroup/numbers/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
   "migratedNumbers": [
      {"phoneNumber": "021234567"},
      {"phoneNumber": "041234567"}
   ]
}
Request JSON Object:

  • migratedNumbers (array) – the list of numbers that must be moved to another trunk users.

  • migratedRange (array) – the range of numbers that must be moved to another trunk users.

Example response:

HTTP/1.1 200 OK
Content-Type: "application/json"

{
   "result": [
      {"phoneNumber": "021234567", "status": "migrated"},
      {"phoneNumber": "041234567", "status": "failed"}
   ]
}
Response JSON Object:

  • result (array) – a list of objects containing the number and it’s status (‘migrated’,’failed’). See Group Trunking Users Result.

Status Codes:

Template Information for Trunk Users

The template category is trunk_user

The main API from template point of vies is a user creation itlself (See Create an user), the default_values and the actions available are therefore related to this end point.

MS Teams Direct Routing information

If Teams integration is enabled (element “TEAMS_CONFIG” in the configuration settings) the following checks will be done to determine if the Trunk Group is one for MS Teams Direct Routing:

  • Is the a Teams Tenant Domain assigned to the Group (sub-domain of the “CARRIER_DOMAIN”)

  • is the Access Device of the Trunk Group the one for Direct Routing (“DR_SBC_DEVICE”)

If it is a Direct Routing Trunk Group then the normal logic of line port generation (described below) will be bypassed and the format will always be e164WithPlus@teamsdomain.

It must be noted that the APIO BW GW itself will only take care of the provisioning of Broadworks. The corresponding provisioning inside MS Teams will be done in a workflow intercepting the same API end point.

Configuration Information for Trunk Users Creation

The APIO behaviour is controlled by the following settings:

"TRUNK_GROUP_USERS" : {
        "DOMAIN" : "sip.netaxis.be",
        "KEEP_PLUS_USER_ID" : true,
        "DEFAULT_TEMPLATE_NAME": None,
        "AUTO_CREATE_TRUNK_NUMBERS": false
        "FORMAT_NAMES": 2,
        "DELETE_LIMIT_READ_SINGLE": 1,
        "OVERWRITE_EXISTING_GENERATED_IDS": true
}
"APIO_OBJECT_CREATION": {
    "GENERATED_ID_DATA": true,
},
"AUTOMATIC_ID_RULES": {
    "LINE_PORT_TRUNK_USER": "{{phone_number_e164}}@{{domain}}"
},
      "TEAMS_CONFIG": {
    "DR_SBC_DEVICE": "SBC-team",
    "CARRIER_DOMAIN": "teams-bwks.netaxis.cloud"
}
With following parameters:

  • DOMAIN: the domain to be used for Trunk Users, if not specified it will be the global DEFAULT_DOMAIN

  • KEEP_PLUS_USER_ID: the user ids starts or not with a +

  • DEFAULT_TEMPLATE_NAME: An optional default template if none provided in the inut data

  • AUTO_CREATE_TRUNK_NUMBERS: auto-create the numbers at Tenant and Group levem (if authorized). If not then the number must be already present at Group level. Default if False

  • FORMAT_NAMES: Defines how the number will be used in the First and Last Names (same for both). With possible values:

    • 0: 164 format

    • 1: International format with 00 (international escape code)

    • 2: International format without 00 (international escape code), default value

    • 3: National format with 0 (national escape code)

    • 4: National format without 0 (national escape code)

  • DELETE_LIMIT_READ_SINGLE: Integer. When deleting trunk users we search for their number in the AS first. It can be getting all group numbers or each number one by one. This settings defined from which quantity of numbers to be deleted we fetch all at once (when the limit is crossed). Default is 1 (from 2, APIO will read all numbers).

  • OVERWRITE_EXISTING_GENERATED_IDS: Boolean. When generating an id (the line port) for a trunk user, do we overwrite an existing record in APIO DB or not. The default is true because the default logic is to build the trunking ids based onthe phone number and it is done after it is verified the number belongs to the Group.

  • DR_SBC_DEVICE: it is the name of the System Access Device that has been created for the SBC. (only relevant for MS Teams DR integration)

  • CARRIER_DOMAIN: it is the Teams Carrier Domain. The Teams Tenant Domains will be sub-domains of this one. (only relevant for MS Teams DR integration)

By default the line_port of a Trunk User is of the format e164WithoutPlus@domain such as 3271324354@sip.netaxis.be. If an other format is needed the Automatic Id mechanism can be used.

It must be enabled using the GENERATED_ID_DATA with value True and by specifying a LINE_PORT_TRUNK_USER formatting rule.

In this rule the following variables can be used:

  • phone_number_e164: The phone number in E164 format

  • country_code: The country code of the phone number

  • national_no_0: The national number, without trailing 0, of the phone number

  • domain: the domain

For the password generation (as in the AS a password is mandatory) the generation will, by default, be based on the rules defined in the AS with the possibility (from 1.11.0) to have minium rules defined.

This is controlled by following parameters:

"NEW_PASSWORD_RESET_GEN": true,
"MINIMUM_PASSWORD_RULES": {
     "END_USER" : {
         "PASSWORD_MIN_SPECIAL_CHARACTERS": 1,
         "PASSWORD_MIN_UPPERCASE_LETTERS": 1,
         "PASSWORD_MIN_LOWERCASE_LETTERS": 1,
         "PASSWORD_MIN_DIGITS": 1,
         "PASSWORD_MIN_LENGTH": 8
     }
},
"PASSWORD_RULES": {
     "SPECIAL_CHAR_TRUNK_USER": true
}
Settings description:

  • NEW_PASSWORD_RESET_GEN: If true the new logic based on rules will be used for the random passwords generation. Else the legacy hardcoded config will be used (and the minimum rules ignored). Default is true. Note that this is a global parameter.

  • MINIMUM_PASSWORD_RULES.**END_USER**: (from 1.11.0) minium password rules for End Users, including Trunk Users. Default are the ones in the example. Please note that this settings will also be used when creating hidden users for APIO features.

  • PASSWORD_RULES.**SPECIAL_CHAR_TRUNK_USER**: If true it will be forced to have at least 1 speacial char even tif the rules do not require one. If false there will be no special chart even if the rules ask for one (to be used with care mainly if you want ot override the minimum rules for the trunk users). No value defined by default.

Remove Trunks Users from a Trunk Group

DELETE /api/v1/tenants/foo/groups/foogroup/services/trunk_groups/footrunkgroup/numbers/

Unassign a list or a range of numbers from the group.

Example request:

DELETE /api/v1/tenants/foo/groups/foogroup/numbers/services/trunk_groups/footrunkgroup/numbers/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
   "numbers": [
      {"phoneNumber": "021234567"},
      {"phoneNumber": "041234567"}
   ]
}
Request JSON Object:

  • numbers (array) – The list of numbers (and related trunk users) to be removed.

  • range (array) – The range of numbers (and related trunk users) to be removed as a list of 2 numbers (start and end).

  • _excludedAppIds (array) – (Optional) The delete will delete all EndUserAppData, but it could occur that the caller still needs some of them and will take the responsibility to delete it. It is an array of Application Ids (string). (from 1.11.1)

  • auto_delete (boolean) – Optional flag to request that the numbers are also deleted at Tenant level and Group level. It must be noted that:

  • The automatic delete at Tenant and Group levels will only be applied is the client has the needed access rights.

  • This feature can also be activated globally at APIO level. In that case if the flag is not present in the request the auto-deletion will be performed anyway.

Example response:

HTTP/1.1 207 Multi-Status
Content-Type: "application/json"

{
   "result": [
      {"phoneNumber": "021234567", "status": "deleted"},
      {"phoneNumber": "041234567", "status": "failed", "error_info": "Pilot user can not be deleted."}
   ],
   "trunkingMode": "normal"
}
Response JSON Object:

  • result (array) – a list of objects containing the number and it’s status (‘deleted’, ‘failed’). See Group Trunking Users Result.

  • trunkingMode (string) – the trunking mode (‘normal’, ‘teamsDR’).

Status Codes:

Configuration Information for Numbers Deletion

The APIO behaviour is controlled by the following settings:

"TRUNK_GROUP_USERS" : {
        "AUTO_CREATE_TRUNK_NUMBERS": false
},
    "TEAMS_CONFIG": {
    "DR_SBC_DEVICE": "SBC-team",
    "CARRIER_DOMAIN": "teams-bwks.netaxis.cloud"
}

It is used if the parameter auto_delete is not present in the request.

It has been decided to re-use the auto_create configuration settings as it is logical that we we auto add we auto delete.

Here are the meaning of the other parameters:

  • DR_SBC_DEVICE: it is the name of the System Access Device that has been created for the SBC. (only relevant for MS Teams DR integration)

  • CARRIER_DOMAIN: it is the Teams Carrier Domain. The Teams Tenant Domains will be sub-domains of this one. (only relevant for MS Teams DR integration)

Objects definition

Group Trunking Users List Entry

Name

Type

Method

Description

GET

userId

String

A

The unique user Id

firstName

String

A

The user first name. (see First / Last name)

lastName

String

A

The user last name. (see First / Last name)

department

String

A

The department the user belongs to

phoneNumber

String

A

The user’s phone number (see Phone Number)

extension

String

A

The user extension. (see Extension)

emailAddress

String

A

The user email address

Group Trunking Users Result

In this table the POST /DELETE has to be understood as returned values in case of POST/DELETE and not as input parameters.

Name

Type

Methods

Description

POST

DELETE

numbers

Array

A

A

List of phone numbers. See Group Trunking User Result.

Group Trunking User Result

In this table the POST /DELETE has to be understood as returned values in case of POST/DELETE and not as input parameters.

Name

Type

Methods

Description

POST

DELETE

phoneNumber

String

A

A

The phone number on which the operation was performed.

status

String

A

A

The result status: “added”, “rejected”, “available”, “migrated”, “failed” for POST, “deleted”,”failed” for DELETE

error_info

String

O

O

An optional additional information in case fo failure. Possible values : * “Pilot user can not be deleted.” * “Unable to create the Trunk User: ” followed by a reason * “Unable to create the Trunk User.” * “This phone number does not belong to this Trunk Group”

extId

String

C

N

The External ID requested for that number (for example: UPN for MS Teams DR Trunk).

userId

String

C

N

The user Id of the newly created Trunk User, present if requested in input data.

linePort

String

C

N

The linePort of the newly created Trunk User, present if requested in input data.