Operator Connect

This set of API's allow to link a MS Teams Operator Connect consent to the Fusion platform.

Starting the onboarding process

The onboarding process is used to connect an existing Operator Connect consent to an existing Fusion subscription. Unless the direct routing onboarding process, this one is really simple and doesn't require asynchronous executions.

Request

Endpoint

POST /api/v01/draas/{draas_instance}/tenants/{uuid}/subscriptions/{subscription_id}/msteams/oc

Authorization

Required role

tenants.instance.subscriptions.instance.msteams.oc.wizard.start

Path Parameters

Parameter	Type	Description
`draas_instance`	`string`	See common parameters
`uuid`	`string`	A system generated unique ID (UUID) identifying the tenant to which the subscription belongs
`sub_id`	`string`	A system generated ID identifying the subscription for which you want to onboard the Operator Connect consent

URL/Query parameters

N/A

Body

Parameter	Type	Description	Required?
`email`	`string`	One of the emails from the list of Operator Connect consent	no
`companyName`	`string`	Company name from Operator Connect consent	no
`msTenantId`	`string`	The MS Tenant ID as found on Azure AD	no

Only one property

The launching of the wizard is done by using one and only one of the body properties described here above. The logic will retrieve MS Teams tenant and email address to be used for eventual code confirmation from any of these properties.

Example

json

{
  "email": "christophe@netaxisdev.onmicrosoft.com"
}

Response

Status codes

Parameter	Description
`200`	According to the Fusion system flag specifying if code confirmation is required, the tenant is either onboarded or waiting for code confirmation
`400`	The wizard has ended with an error
`403`	The API consumer doesn't have sufficient rights to perform this action
`500`	Uncatched error on server side

Success

Body

Parameter	Type	Description	Conditional?
`message`	`string`	Message specifying the final status of the onboarding process	no

Example

json

{
   "message": "Code sent to contact person for confirmation"
}

Sending the onboarding confirmation code

If set at Fusion system level, onboarding may require a confirmation code to be sent to the email address of a consent user for validation. The received code should then be used by this API to complete the onboarding process.

Request

Endpoint

PUT /api/v01/draas/{draas_instance}/tenants/{uuid}/subscriptions/{subscription_id}/msteams/oc

Authorization

Required role

tenants.instance.subscriptions.instance.msteams.oc.wizard.confirmation

Path Parameters

Parameter	Type	Description
`draas_instance`	`string`	See common parameters
`uuid`	`string`	A system generated unique ID (UUID) identifying the tenant to which the subscription belongs
`sub_id`	`string`	A system generated ID identifying the subscription for which you want to onboard the Operator Connect consent

URL/Query parameters

N/A

Body

Parameter	Type	Description	required?
`code`	`string`	A 4 digits code received by email for confirmation	yes

Example

json

{
    "code": "2652"
}

Response

Status codes

Parameter	Description
`200`	Operator Connect consent has been successfuly linked to the Fusion subscription
`400`	An error occurred or entered code was not valid
`403`	The API consumer doesn't have sufficient rights to perform this action
`404`	The path requested doesn't exists for the provided tenant and subscription ID's or the MS Teams tenant has not been linked yet
`500`	Uncatched error on server side

Success

Body

Parameter	Type	Description	Conditional?
`message`	`string`	Message specifying the final status of the onboarding process	no

Example

json

{
   "message": "MS Teams tenant successfully onboarded to Operator Connect"
}

Use this API to unlink an Operator Connect consent from your subscription. To do so, you will first have to release all provisioned phone numbers by using this API

Request

Endpoint

DELETE /api/v01/draas/{draas_instance}/tenants/{uuid}/subscriptions/{subscription_id}/msteams/oc

Authorization

Required role

tenants.instance.subscriptions.instance.msteams.oc.unlink

Path Parameters

Parameter	Type	Description
`draas_instance`	`string`	See common parameters
`uuid`	`string`	A system generated unique ID (UUID) identifying the tenant to which the subscription belongs
`sub_id`	`string`	A system generated ID identifying the subscription from which you want to unlink the Operator Connect consent

URL/Query parameters

N/A

Body

N/A

Response

Status codes

Parameter	Description
`204`	The Operator Connect consent has been successfuly unlinked
`400`	The unlinking process ended with an error or there are still phone numbers provisioned
`403`	The API consumer doesn't have sufficient rights to perform this action
`500`	Uncatched error on server side

Get Operator Connect civic addresses

When adding numbers to Operator Connect, a civic address used as emergency location has to be defined. This API gets the list of existing civic addresses that might be used in such case.

Request

Endpoint

GET /api/v01/draas/{draas_instance}/tenants/{uuid}/subscriptions/{subscription_id}/msteams/oc/civic_addresses

Authorization

Required role

tenants.instance.subscriptions.instance.msteams.oc.civic_addresses.read

Path Parameters

Parameter	Type	Description
`draas_instance`	`string`	See common parameters
`uuid`	`string`	A system generated unique ID (UUID) identifying the tenant to which the subscription belongs
`sub_id`	`string`	A system generated ID identifying the subscription for which you have onboarded to Operator Connect consent

URL/Query parameters

N/A

Body

N/A

Response

Status codes

Parameter	Description
`200`	The list of available civic addresses is returned
`400`	An error has occurred while retrieving the list of civic addresses
`403`	The API consumer doesn't have sufficient rights to perform this action
`404`	The path requested doesn't exists for the provided tenant and subscription ID's or the MS Teams tenant has not been linked yet
`500`	Uncatched error on server side

Success

Body

Parameter	Type	Description	Conditional?
`civicAddresses`	`array`	List of existing civic addresses to be used for adding numbers to Operator Consent	no

Civic Address Object

Parameter	Type	Description	Conditional?
`id`	`string`	Microsoft UUID reference to the civic address, to be used when adding numbers to Operator Connect consent	no
`street`	`string`	Street name of the civic address	no
`number`	`string`	Street number of the civic address	no
`city`	`string`	City name of the civic address	no
`state`	`string`	State name of the civic address	no
`postalCode`	`string`	Postal Code of the civic address	no
`country`	`string`	Country code of the civic address as a ISO 3166 alpha-2 code	no
`companyName`	`string`	Company name of the civic address	no
`description`	`string`	Text describing the civic address	no
`location`	`array`	List of available locations for the civic address	no

Location Object

Parameter	Type	Description	Conditional?
`id`	`string`	Microsoft UUID reference to the location	no
`description`	`string`	Text describing the location	yes
`default`	`boolean`	Flag telling which of the locations is the default one	no

Example

json

{
    "civicAddresses": [
        {
            "id": "0de2d930-a96e-11ec-8511-67212b730a2b",
            "street": "Oosthuizen Drive",
            "number": "23",
            "city": "Roodepoort",
            "state": "Gauteng",
            "postalCode": "1709",
            "country": "ZA",
            "companyName": "Netaxis Dev",
            "description": "South Africa",
            "locations": [
                {
                    "id": "44d95fd4-19b1-4278-b93a-43bb80161958",
                    "description": "South Africa",
                    "default": true
                },
                {
                    "id": "2c2c7310-a96e-11ec-8511-67212b730a2b",
                    "default": false
                },
                {
                    "id": "2fccf260-a96e-11ec-8511-67212b730a2b",
                    "default": false
                }
            ]
        }
    ]
}

Get Operator Connect allowed usages

When adding numbers to Operator Connect, a usage has to be specified. This API gets the list of allowed usages and their characteristics.

Request

Endpoint

GET /api/v01/draas/{draas_instance}/tenants/{uuid}/subscriptions/{subscription_id}/msteams/oc/allowed_usages

Authorization

Required role

tenants.instance.subscriptions.instance.msteams.oc.allowed_usages.read

Path Parameters

Parameter	Type	Description
`draas_instance`	`string`	See common parameters
`uuid`	`string`	A system generated unique ID (UUID) identifying the tenant to which the subscription belongs
`sub_id`	`string`	A system generated ID identifying the subscription for which you have onboarded to Operator Connect consent

URL/Query parameters

N/A

Body

N/A

Response

Status codes

Parameter	Description
`200`	The list of available allowed usages is returned
`400`	An error has occurred while retrieving the list of allowed usages
`403`	The API consumer doesn't have sufficient rights to perform this action
`404`	The path requested doesn't exists for the provided tenant and subscription ID's or the MS Teams tenant has not been linked yet
`500`	Uncatched error on server side

Success

Body

Parameter	Type	Description	Conditional?
`usages`	`array`	List of allowed usages to be used for adding numbers to Operator Consent	no

Allowed Usage Object

Parameter	Type	Description	Conditional?
`id`	`string`	Microsoft UUID reference to the civic address, to be used when adding numbers to Operator Connect consent	no
`serviceType`	`string`	Street name of the civic address	no
`description`	`string`	Street number of the civic address	no
`addressRequired`	`boolean`	City name of the civic address	no
`capabilities`	`array`	List of available capabilities, posssible values are `InboundCalling` or `OutboundCalling`	no
`allowedNumberTypes`	`array`	List of available phone number types as checked by the Google phonumbers library	no

Example

json

{
    "usages": [
        {
            "id": "CallingUserAssignment",
            "serviceType": "user",
            "description": "Numbers that can be assigned to users",
            "addressRequired": true,
            "capabilities": [
                "InboundCalling",
                "OutboundCalling"
            ],
            "allowedNumberTypes": [
                "FIXED_LINE",
                "VOIP"
            ]
        },
        {
            "id": "FirstPartyAppAssignment",
            "serviceType": "resourceAccount",
            "description": "Numbers that can be assigned to resource users",
            "addressRequired": false,
            "capabilities": [
                "InboundCalling",
                "OutboundCalling"
            ],
            "allowedNumberTypes": [
                "FIXED_LINE",
                "VOIP",
                "TOLLFREE",
                "UAN",
                "PREMIUM_RATE"
            ]
        }
    ]
}

Use this API to list phone numbers added to an Operator Connect consent. Note that this API gives priority to the Microsoft list, meaning you get all numbers of the Operator Connect consent, including numbers that have not been subscribed through the Fusion platform.

Request

Endpoint

GET /api/v01/draas/{draas_instance}/tenants/{uuid}/subscriptions/{subscription_id}/msteams/oc/numbers

Authorization

Required role

tenants.instance.subscriptions.instance.msteams.oc.numbers.read

Path Parameters

Parameter	Type	Description
`draas_instance`	`string`	See common parameters
`uuid`	`string`	A system generated unique ID (UUID) identifying the tenant to which the subscription belongs
`sub_id`	`string`	A system generated ID identifying the subscription for which you have onboarded to Operator Connect consent

URL/Query parameters

Parameter	Type	Description	Required?
`page_size`	`integer`	Used for pagination, determines the maximum number of records on one page of results (defaults to 10)	no
`next`	`string`	A token used to get the next records in the list. This token is taken back from the results of the previous call	no
`search`	`string`	Use this parameter to search for all numbers that contains this string. Phone number in e.164 format	no

Body

N/A

Response

Status codes

Parameter	Description
`200`	The list of numbers that have been added to Operator Connect consent
`400`	An error occurred while retrieving the list of numbers
`403`	The API consumer doesn't have sufficient rights to perform this action
`404`	The path requested doesn't exists for the provided tenant and subscription ID's or the MS Teams tenant has not been linked yet
`500`	Uncatched error on server side

Success

Body

Parameter	Type	Description	Conditional?
`next`	`string`	A token used for infinite scrolling, to be used in the next call to retrieve subsequent records. Only present if the list of numbers has to be continued	yes
`numbers`	`array`	A list of phone number objects enriched with Fusion data if any	no

Resource Account Object

Parameter	Type	Description	Conditional?
`msTeams`	`object`	MS Teams phone number properties as described by a MS Teams phone number object	no
`draas`	`object`	Fusion phone number as described by a Fusion phone number object	yes

MS Teams Phone Number Object

Parameter	Type	Description	Conditional?
`country`	`string`	Country code in ISO 3166 alpha-2 format	no
`number`	`string`	MS Teams phone number in international format	no
`provisionedOnMSTeams`	`boolean`	Flag that indicates if the number has been provisioned in MS Teams	no
`batch`	`string`	MS Teams reference of the uploading batch when the phone number has been provisioned	no
`uploadedOn`	`string`	Date and time when the phone number was uploaded to MS Teams	no
`usage`	`string`	Allowed usage of the phone numbers in Teams	no

Fusion Phone Number Object

Parameter	Type	Description	Conditional?
`id`	`integer`	Internal ID of the phone number	no
`connectionId`	`integer`	Internal ID of the connection made between the phone number and a MS Teams user	no
`countryCode`	`string`	Country code of the number you want to delete	no
`nsn`	`integer`	National subscriber number. E.g. in +32-16474942, +32 is the country code and 16474942 is the nsn	no
`fullNumber`	`string`	Phone number assigned to Operator Connect consent in international format	no

Example

json

{
    "next": "cGFnZV9zaXplPTEwJnBhZ2U9Mg==",
    "numbers": [
        {
            "msTeams": {
                "country": "ZA",
                "number": "+27102850041",
                "provisionedOnMSTeams": true,
                "batch": "d536d79d-bd92-4529-b308-9d2582024749",
                "uploadedOn": "5/23/2022 11:42:04 AM (GMT)",
                "usage": "User assignment"
            },
            "draas": {
                "id": 1232,
                "connectionId": 369,
                "countryCode": 27,
                "nsn": "102850041",
                "fullNumber": "+27102850041"
            }
        },
        {
            "msTeams": {
                "country": "ZA",
                "number": "+27102850044",
                "provisionedOnMSTeams": true,
                "batch": "d536d79d-bd92-4529-b308-9d2582024749",
                "uploadedOn": "5/23/2022 11:42:04 AM (GMT)",
                "usage": "User assignment"
            },
            "draas": {
                "id": 1235,
                "connectionId": 365,
                "countryCode": 27,
                "nsn": "102850044",
                "fullNumber": "+27102850044"
            }
        }
    ]
}

Use this API to list phone numbers added to an Operator Connect consent that are still free for assignation to a MS Teams user or resource.

Request

Endpoint

GET /api/v01/draas/{draas_instance}/tenants/{uuid}/subscriptions/{subscription_id}/msteams/oc/free_numbers

Authorization

Required role

tenants.instance.subscriptions.instance.msteams.oc.free_numbers.read

Path Parameters

Parameter	Type	Description
`draas_instance`	`string`	See common parameters
`uuid`	`string`	A system generated unique ID (UUID) identifying the tenant to which the subscription belongs
`sub_id`	`string`	A system generated ID identifying the subscription for which you have onboarded to Operator Connect consent

URL/Query parameters

Parameter	Type	Description	Required?
`usage`	`string`	Allow to filter the phone number list on a specific usage. Allowed values are `CallingUserAssignment` or `FirstPartyAppAssignment` as returned by this API	no
`country`	`string`	Allow to filter the phone number list on a country code in ISO 3166 alpha-2 format	no

Body

N/A

Response

Status codes

Parameter	Description
`200`	The list of numbers that are still free for assignment
`400`	An error occurred while retrieving the list of free numbers
`403`	The API consumer doesn't have sufficient rights to perform this action
`404`	The path requested doesn't exists for the provided tenant and subscription ID's or the MS Teams tenant has not been linked yet
`500`	Uncatched error on server side

Success

Body

Parameter	Type	Description	Conditional?
`freeNumbers`	`array`	A list of phone numbers free for assignment in international format	no

Example

json

{
    "freeNumbers": [
        "+27102850040",
        "+27102850041",
        "+27102850042",
        "+27102850043",
        "+27102850044",
        "+27102850045"
    ]
}

Use this API to add phone numbers to an Operator Connect consent. To add phone numbers, you have to:

Have enough Fusion MS Teams user licenses
Have enough entitlements in a geo region you want to use and enough phone numbers available from this entitlement or valid ported-in numbers

Request

Endpoint

POST /api/v01/draas/{draas_instance}/tenants/{uuid}/subscriptions/{subscription_id}/msteams/oc/numbers

Authorization

Required role

tenants.instance.subscriptions.instance.msteams.oc.numbers.create

Path Parameters

Parameter	Type	Description
`draas_instance`	`string`	See common parameters
`uuid`	`string`	A system generated unique ID (UUID) identifying the tenant to which the subscription belongs
`sub_id`	`string`	A system generated ID identifying the subscription for which you have onboarded to Operator Connect consent

URL/Query parameters

N/A

Body

Parameter	Type	Description	required?
`civicAddressId`	`string`	The civic address `id` as returned by this API	yes
`usage`	`string`	The usage `id` as returned by this API	yes
`numbers`	`array`	Array of international subscriber numbers (`string` starting with `+` sign) that you want to add	no
`ranges`	`array`	Array of `arrays` where each array contains 2 international subscriber numbers (both `string` starting with `+` sign): range start & range end	no

Example

json

{
    "civicAddressId": "0de2d930-a96e-11ec-8511-67212b730a2b",
    "usage": "CallingUserAssignment",
    "countryCode": "+27",
    "numbers": [
      "+27102850040",
      "+27102850041"
    ],
    "ranges": [
      ["+27102850042", "+27102850045"]
    ]
}

Response

Status codes

Parameter	Description
`200`	The numbers have been added to Operator Connect consent
`400`	An error occurred (subscription doesn't own requested numbers or there are not enough MS Teams user licenses available)
`403`	The API consumer doesn't have sufficient rights to perform this action
`404`	The path requested doesn't exists for the provided tenant and subscription ID's or the MS Teams tenant has not been linked yet
`500`	Uncatched error on server side

Success

Body

Parameter	Type	Description	Conditional?
`total`	`integer`	Total amount of numbers you tried to add to the subscription	no
`assigned`	`integer`	Total amount of numbers that really have been assigned to the subscription	no
`alreadyAssigned`	`integer`	Total amount of numbers that were provided in the request but already added before	no

Example

json

{
    "total": 6,
    "assigned": 6,
    "alreadyAssigned": 0
}

Use this API to remove phone numbers from an Operator Connect consent. To remove a phone number, it has to be free and not yet assigned to a MS Teams user or resource.

Request

Endpoint

DELETE /api/v01/draas/{draas_instance}/tenants/{uuid}/subscriptions/{subscription_id}/msteams/oc/numbers

Authorization

Required role

tenants.instance.subscriptions.instance.msteams.oc.numbers.delete

Path Parameters

Parameter	Type	Description
`draas_instance`	`string`	See common parameters
`uuid`	`string`	A system generated unique ID (UUID) identifying the tenant to which the subscription belongs
`sub_id`	`string`	A system generated ID identifying the subscription for which you have onboarded to Operator Connect consent

URL/Query parameters

N/A

Body

Parameter	Type	Description	Required
`numbers`	`array`	List containing all number objects that have to be deleted	no

Number object

Parameter	Type	Description	Required
`countryCode`	`string`	Country code of the number you want to delete	no
`nsn`	`integer`	National subscriber number. E.g. in +32-16474942, +32 is the country code and 16474942 is the nsn	no

Example

json

{
  "numbers": [
    { "countryCode": "+27", "nsn": 102850040 },
    { "countryCode": "+27", "nsn": 102850041 },
    { "countryCode": "+27", "nsn": 102850042 }
  ]
}

Response

Status codes

Parameter	Description
`200`	The numbers have been removed from Operator Connect consent
`400`	An error occurred (some of the numbers are still assigned or doesn't belong to the subscription)
`403`	The API consumer doesn't have sufficient rights to perform this action
`404`	The path requested doesn't exists for the provided tenant and subscription ID's or the MS Teams tenant has not been linked yet
`500`	Uncatched error on server side

Success

Body

Parameter	Type	Description	Required
`numbers`	`array`	List containing all number objects that have to be deleted	no

Number to Delete object

Parameter	Type	Description	Required
`countryCode`	`string`	Country code of the number you want to delete	no
`nsn`	`integer`	National subscriber number. E.g. in +32-16474942, +32 is the country code and 16474942 is the nsn	no

Example

json

{
  "numbers": [
    { "countryCode": "+27", "nsn": 102850040 },
    { "countryCode": "+27", "nsn": 102850041 },
    { "countryCode": "+27", "nsn": 102850042 }
  ]
}

Adds or removes a phone number to or from a user of an Operator Connect consent. Note that to assign a phone number to a user of an Operator Connect consent, the requesting tenant has to hold a valid subscription with some phone numbers assigned to the consent. Trying to add a phone number that is not assigned to an Operator Connect consent or already belonging to another user will result in an error.

Request

Endpoint

PUT /api/v01/draas/{draas_instance}/tenants/{uuid}/subscriptions/{subscription_id}/msteams/oc/users/{ms_user_id}

Authorization

Required role

tenants.instance.subscriptions.instance.msteams.oc.users.instance.update

Path Parameters

Parameter	Type	Description
`draas_instance`	`string`	See common parameters
`uuid`	`string`	A system generated unique ID (UUID) identifying the tenant managing the subscription
`sub_id`	`integer`	Index of a subscription for which you want to create or update the MS Teams administrator
`ms_user_id`	`string`	MS Teams Azure AD Object ID identifying the user

URL/Query parameters

N/A

Body

Parameter	Type	Description	Required
`phoneNumber`	`string` or `null`	Phone number to be assigned to the Operator Connect user. Set to `null` to remove a phone number	yes

Example

json

{
  "phoneNumber": "+27102851554"
}

Response

Status codes

Parameter	Description
`200`	The phone number was successfully added
`204`	The phone number was successfully removed
`400`	Error while modifying the phone number
`403`	The API consumer doesn't have sufficient rights to perform this action
`404`	The path tenant / subscription doesn't exist
`500`	Uncatched error on server side

Success

Body

Parameter	Type	Description	Conditional?
`id`	`integer`	Internal ID of the Operator Connect user	no
`connectionId`	`integer`	Internal ID of the connection made between the phone number and the Operator Connect user	no
`numberId`	`integer`	Internal ID of the phone number linked to the Operator Connect user	no
`phoneNumber`	`string`	Phone number assigned to the Operator Connect user	no

Example

json

{
  "id": 11,
  "connectionId": 8,
  "numberId": 441,
  "phone_number": "+31302861233"
}

Operator Connect ​

Starting the onboarding process ​

Request ​

Endpoint ​

Authorization ​

Path Parameters ​

URL/Query parameters ​

Body ​

Example ​

Response ​

Status codes ​

Success ​

Body ​

Example ​

Sending the onboarding confirmation code ​

Request ​

Endpoint ​

Authorization ​

Path Parameters ​

URL/Query parameters ​

Body ​

Example ​

Response ​

Status codes ​

Success ​

Body ​

Example ​

Unlinking an Operator Connect consent ​

Request ​

Endpoint ​

Authorization ​

Path Parameters ​

URL/Query parameters ​

Body ​

Response ​

Status codes ​

Get Operator Connect civic addresses ​

Request ​

Endpoint ​

Authorization ​

Path Parameters ​

URL/Query parameters ​

Body ​

Response ​

Status codes ​

Success ​

Body ​

Civic Address Object ​

Location Object ​

Example ​

Get Operator Connect allowed usages ​

Request ​

Endpoint ​

Authorization ​

Path Parameters ​

URL/Query parameters ​

Body ​

Response ​

Status codes ​

Success ​

Body ​

Allowed Usage Object ​

Example ​

Get the list of phone numbers added to an Operator Connect consent ​

Request ​

Endpoint ​

Authorization ​

Path Parameters ​

URL/Query parameters ​

Body ​

Response ​

Status codes ​

Success ​

Body ​

Resource Account Object ​

MS Teams Phone Number Object ​

Fusion Phone Number Object ​

Example ​

Get the list of free phone numbers for an Operator Connect consent ​

Request ​

Operator Connect

Starting the onboarding process

Request

Endpoint

Authorization

Path Parameters

URL/Query parameters

Body

Example

Response

Status codes

Success

Body

Example

Sending the onboarding confirmation code

Request

Endpoint

Authorization

Path Parameters

URL/Query parameters

Body

Example

Response

Status codes

Success

Body

Example

Unlinking an Operator Connect consent

Request

Endpoint

Authorization

Path Parameters

URL/Query parameters

Body

Response

Status codes

Get Operator Connect civic addresses

Request

Endpoint

Authorization

Path Parameters

URL/Query parameters

Body

Response

Status codes

Success

Body

Civic Address Object

Location Object

Example

Get Operator Connect allowed usages

Request

Endpoint

Authorization

Path Parameters

URL/Query parameters

Body

Response

Status codes

Success

Body

Allowed Usage Object

Example

Get the list of phone numbers added to an Operator Connect consent

Request

Endpoint

Authorization

Path Parameters

URL/Query parameters

Body

Response

Status codes

Success

Body

Resource Account Object

MS Teams Phone Number Object

Fusion Phone Number Object

Example

Get the list of free phone numbers for an Operator Connect consent

Request