Group Numbers

Listing available numbers

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

Return the list of numbers assigned to the group.

Example request:

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

Example response:

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

{
   "numbers": [
      "+3225126999",
      "+3226127000",
      "+3226127001",
      "+3226127002",
      "+3252551430"
   ]
}

Response JSON Object:

• numbers (array) – a list of numbers. See Group Numbers attributes.

Example request:

GET /api/v1/tenants/foo/numbers/ HTTP/1.1
Host: example.com

{
   "available": true,
   "assignement": true
}

Note

In case none of the input parameters is provided, assignement_phoneNumbers is returned.

In case both parameters are set to False, assigned_numbers and/or available_numbers are returned as empty lists.

Request JSON Object:

• available (boolean) – indicate if the list of available numbers must be returned.

• assignement (boolean) – indicate if the list of numbers with their assigned Group must be returned.

Example response:

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

{
   "assigned_numbers": [
      {
         "extension": "",
         "firstName": "",
         "lastName": "Test Group",
         "userId": "",
         "userType": "",
         "phoneNumber": "+3225126999",
         "department": {
            "tenantId": "ApioSpTest",
            "groupId": "ApioGrpTest",
            "departmentName": "test_department_initial",
            "fullPathName": "test_department_parent_1 \\ test_department_initial"
         },
         "emailAddress": ""
      },
      {
         "extension": "5001",
         "firstName": "Test1",
         "lastName": "Test1",
         "userId": "ApioUserTest1@sip.netaxis.be",
         "userType": "Normal",
         "phoneNumber": "+3226127000",
         "emailAddress": ""
      },
      {
         "extension": "",
         "firstName": "",
         "lastName": "",
         "userId": "",
         "userType": "",
         "phoneNumber": "+3226127001 - +3226127002",
         "emailAddress": ""
      }
   ],
   "available_numbers": [
      "+3226127001",
      "+3226127002"
   ]
}

Status Codes:

• 200 OK – no error

• 400 Bad Request – failed

Configuration Information for Assigned Numbers Listing

The APIO behaviour is controlled by the following settings:

"FILTER_OUT_GROUP_CLI_NUMBERS": false,
"GROUP_CLI_NUMBER_LAST_NAMES": ['Group Calling Line ID'],
"GROUP_NUMBERS_USE_CC_CLI": false

With following parameters:

• FILTER_OUT_GROUP_CLI_NUMBERS: If true, CLI numbers duplications will be removed from assigned numbers list, and the additional isGroupCLI flag will be added (true for group CLI). If the CLI number is part of a range, it will be returned as a single number with isGroupCLI true, and the range will be modified to exclude the CLI number.

• GROUP_CLI_NUMBER_LAST_NAMES: The array of possible last names assigned by Broadworks to the user the group CLI is assigned to.

• GROUP_NUMBERS_USE_CC_CLI, the OCI documentation says explicitly the numbers will be returned in E164. But it has been reported that sometimes it is not the case, and we have no info from Cisco about this. This parameter is used in some APIs (in this page the answer items assignement_phoneNumbers and available_numbers) to implement a workaround that will assume that the number is in national format if same country code as Grouo CLi. It is based on observations and not on Cisco doc. Therefore toi be used carefully

Assign numbers at Group level

POST /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/numbers/

Assign numbers (available at tenant level) to the group.

Example request:

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

{
   "numbers": [
      {"phoneNumber": "021234567"},
      {"phoneNumber": "041234567"}
   ],
   "range": {
      "minPhoneNumber": "071568000",
      "maxPhoneNumber": "071568002"
   }
}

Request JSON Object:

• numbers (array) – the list of numbers to be added.

• range (array) – the range of numbers to be added as a list of 2 numbers (start and end).

• auto_create (boolean) –

  Optional flag to request that if the number does not exists yet at Tenant level, it is added to at that level. It must be noted that:

  • The automatic creation at Tenant level will only be aplied 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-creation will be performed anyway.

Example response:

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

{
   "result": [
      {"phoneNumber": "021234567", "status": "added"},
      {"phoneNumber": "041234567", "status": "rejected"},
      {"phoneNumber": "071568000", "status": "added"},
      {"phoneNumber": "071568001", "status": "added"},
      {"phoneNumber": "071568002", "status": "added"}
   ]
}

Response JSON Object:

• result (array) – a list of objects containing the number and it’s status (‘added’, ‘rejected’, ‘available’). See Group Numbers Result items for the definition of the objects in the array. Generated only in case auto_delete is enabled.

Status Codes:

• 201 Created – request was processed

• 207 Multi Status – partial success (some numbers are created, other not)

• 400 Bad Request – full error

Configuration Information for Numbers Creation

The APIO behaviour is controlled by the following settings:

"AUTO_CREATE" : {
        "FIXED_NUMBERS" : true,
}

It is used if the parameter auto_create is not present in the request

Remove numbers at Group level

DELETE /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/numbers/

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

Example request:

DELETE /api/v1/tenants/foo/groups/foogroup/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 to be removed.

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

• auto_delete (boolean) –

  Optional flag to request that the numbers are also deleted at Tenant level. It must be noted that:

  • The automatic delete at Tenant level 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.

  • It can be present with value False to trigger the detailed result report analysis. This detailed analysis will verify if the number is still present in the AS if not the case if will be consider as a success (REST philosophy).

Example response:

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

{
   "result": [
      {"phoneNumber": "021234567", "status": "deleted"},
      {"phoneNumber": "041234567", "status": "failed"}
   ]
}

Response JSON Object:

• result (array) – a list of objects containing the number and it’s status (‘deleted’, ‘failed’). See Group Numbers Result items for the definition of the objects in the array. Generated only in case auto_delete is present of enable at global level.

Status Codes:

• 200 OK – request was processed (but the content may content errors)

• 207 Multi Status – partial success (some numbers are deleted, other not)

• 400 Bad Request – full error

Configuration Information for Numbers Deletion

The APIO behaviour is controlled by the following settings:

"AUTO_DELETE" : {
        "FIXED_NUMBERS" : true,
}

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

Retrieve the list of activated and deactivated Numbers in a group.

GET /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/numbers/activation_status/

Retrieve the list of activated and deactivated Numbers in a group. Only Numbers assigned to a user are listed in the response when the number activation Mode is set to “User Activation Enabled”, Numbers assigned to the IMRN pool are never listed in the response.

Authorization rights: minimum Group Admin.

Example request:

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

Example response:

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

{
  "numberActivationMode": "Off",
  "numbers": [
      {
          "phoneNumber": "+3225126770",
          "activated": true
      },
      {
          "phoneNumber": "+3225126778",
          "activated": true
      }
  ]
}

Response JSON Object:

• numberActivationMode (string) – the state of the Activation Number feature. Value comes from list: [“Off”, “User Activation Enabled”, “Group And User Activation Enabled”]. This parameter is configurable at System level only.

• numbers (array) – a list of objects containing the numbers with their activation status. See Group number activation status attributes

Status Codes:

• 200 OK – no error

Update the list of activated and deactivated Numbers in a group.

PUT /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/numbers/activation_status/

Update the list of activated and deactivated Numbers in a group.

Authorization rights: minimum Group Admin.

Example request:

PUT /api/v1/tenants/foo/groups/foogroup/numbers/activation_status/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
      "numbers": [
          {
              "phoneNumber": "+3225126770",
              "activated": false
          },
          {
              "phoneNumber": "+3225126777",
              "activated": true
          },
          {
              "phoneNumber": "+3225126778",
              "activated": false
          }
      ],
      "range": {
          "activated": false,
          "minPhoneNumber": "+3225126779",
          "maxPhoneNumber": "+3225126780"
      }
}

Request JSON Object:

• numbers (array) – a list of objects containing the numbers with their activation status. See Group number activation status attributes

• range (object) – a range of numbers with their activation status. See Group number activation status attributes

Example response:

HTTP/1.1 200 OK

Status Codes:

• 200 OK – no error

• 400 Bad Request –

  unable to update numbers activation status, with possible sub-error codes:

  • 2: INVALID_PARAMETERS, “The phone number has been inserted twice: one to activate it and the other to disable it.”

  • 2: INVALID_PARAMETERS, “The phone number provided is not valid.”

  • 18: INVALID_OPERATION, “Number activation cannot be disabled until all phone numbers assigned to users have been activated.”

  • 45: API_NOT_AVAILABLE_AT_NE, “‘Number Activation’ feature must be enabled to perform the operation.”