Numbers

No voice service without phone numbers. So in order to be able to make use of a subscription - albeit the Microsoft Teams phone system, normal SIP Trunking or any other (future) service - you'll need phone numbers.

To attach phone numbers to a subscription, following options are currently supported:

option 1: select new numbers from our inventory
- this option is the easiest to get started quickly or when you don't have any existing numbers you can (currently) migrate to this platform
- it is possible to select numbers from the inventory as long as the subscription has some number entitlements associated and not yet deleted
option 2: order new numbers from the Gamma inventory (if enabled for your group). See Numbers: Gamma Integration for more details
- it is possible to order numbers from the Gamma inventory
option 3: port in existing numbers from another service provider
- this option allows you to re-use your existing phone numbers through our platform
- you can port in numbers through NPCAT: currently porting is only supported for the Netherlands
- you can port in numbers through Gamma service (if enabled for your group). See Numbers: Gamma Integration for more details

Retrieve Number Inventory Type

This endpoint returns the service used to manage numbers. This value is managed by the draas_external_number_inventory_management_system configuration key.

Request

Endpoint

GET /api/v01/draas/{draas_instance}/groups/{uuid}/number_inventory_typeGET /api/v01/draas/{draas_instance}/tenants/{uuid}/subscriptions/{subscription_id}/number_inventory_type

Authorization

Required role

groups.instance.number_inventory_type.read tenants.instance.subscriptions.instance.number_inventory_type.read

Path Parameters

Parameter	Type	Description
`draas_instance`	`string`	See common parameters
`uuid`	`string`	A system generated unique ID (UUID) identifying the group or the tenant to which the subscription belongs
`sub_id`	`integer`	Index of the subscription for which you want to list the licenses

URL/Query parameters

N/A

Response

Status codes

Parameter	Description
`200`	The inventory type is returned
`500`	Uncatched error on server side

Success

Body

Parameter	Type	Description	Conditional?
`service`	`string`	The inventory type for the specified group or tenant. Could be `gamma` (it will use the Gamma service to manage numbers) or `default` (It will use our NIMS)	no

Example

json

{
  "service": "gamma",
}

List all numbers of a subscription

This endpoint returns all numbers currently assigned to a subscription. The numbers can be used to place and receive calls through the platform.

Request

Endpoint

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

Authorization

Required role

tenants.instance.subscriptions.instance.numbers.list

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`	`integer`	Index of the subscription for which you want to list the licenses

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 25)	no
`page`	`integer`	Used for pagination, determines the returned page from the collection of result pages (defaults to 1)	no
`search`	`string`	Use this parameter to search for all numbers that contains this string. Phone number in e.164 format	no

Response

Status codes

Parameter	Description
`200`	One or more numbers found
`400`	Error while processing the request
`404`	No numbers found
`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?
`results`	`string`	Total count of results that match your query	no
`pageSize`	`string`	Results are not provided all at once. This parameter indicates how many results are returned per page.	no
`pages`	`string`	Total count of result pages that are available	no
`page`	`string`	ID of the page that is currently returned	no
`numbers`	`array`	List containing all number objects for the subscription	no

Number Object

Parameter	Type	Description	Conditional?	Searchable?
`countryCode`	`string`	Country code of the phone number. Typically a + followed by 2 or 3 digits (e.g. +32)	no	yes
`nsn`	`string`	National subscriber number. E.g. in +32-16474942, +32 is the country code and 16474942 is the nsn	no	yes
`fullNumber`	`string`	The fullnumber is the phonenumber in e.164 format	no	yes
`isoCode`	`string`	The ISO 3166 country code	no	yes
`numberType`	`string`	Type of the number in question (e.g. geo, mobile, tollfree, ...)	no	no
`source`	`string`	Indicates where this number comes from. Currently 2 sources are supported: `number_inventory` and `ported_in`	no	no
`status`	`string`	Indicates the status of the number. Used in port in requests, it allows to pre-provision a number before porting has been finally activated. Default is set to `active` for number type `number_inventory`	no	no
`assigned`	`boolean`	Indicates whether or not the number is currently in use	no	no
`assignedTo`	`string`	Provides information to which MS Teams user or access trunk the number is connected. This information is only provided when the number is assigned. See assignedTo object	yes	no

AssignedTo Object

Parameter	Type	Description	Conditional?
`type`	`string`	Can be `sip_trunk` or `ms_teams`	no
`subType`	`string`	In case the type is set to `ms_teams`, this sub-type can take values `user`, `resource_account` or `operator_connect`. This last value means that the number has been linked to an Operator Connect consent but not yet attached to a user	yes
`to`	`integer`	ID referring to the sip trunk or ms teams user to which the number is assigned	no

Example

json

{
    "results": 4,
    "pages": 1,
    "pageSize": 25,
    "page": 1,
    "numbers": [
        {
            "countryCode": "+32",
            "nsn": "25405310",
            "fullNumber": "+3225405310",
            "isoCode": "BE",
            "source": "number_inventory",
            "numberType": "None",
            "status": "active",
            "assigned": true,
            "assignedTo": {
                "type": "ms_teams",
                "subType": "user",
                "to": 5
            }
        },
        {
            "countryCode": "+32",
            "nsn": "25405311",
            "fullNumber": "+3225405311",
            "isoCode": "BE",
            "source": "number_inventory",
            "numberType": "None",
            "status": "active",
            "assigned": false
        },
        {
            "countryCode": "+32",
            "nsn": "25405312",
            "fullNumber": "+3225405312",
            "isoCode": "BE",
            "source": "number_inventory",
            "numberType": "None",
            "status": "active",
            "assigned": false
        },
        {
            "countryCode": "+32",
            "nsn": "25405313",
            "fullNumber": "+3225405313",
            "isoCode": "BE",
            "source": "number_inventory",
            "numberType": "None",
            "status": "active",
            "assigned": false
        }
    ]
}

List free numbers of a subscription

This endpoint returns all free numbers still available for assignment in a subscription.

Request

Endpoint

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

Authorization

Required role

tenants.instance.subscriptions.instance.free_numbers.list

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`	`integer`	Index of the subscription for which you want to list the licenses

URL/Query parameters

Parameter	Type	Description	Required?
`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`	Zero, one or more free numbers found
`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?
`freeNumbers`	`array`	List containing all free numbers for the subscription	no

Example

json

{
  "freeNumbers": [
    "+31302861230",
    "+31302861231",
    "+31302861232",
    "+31302861234"
  ]
}

Linked numbers in the inventory

This endpoint allows to browse the number inventory. Only numbers associated to the provided subscription will be returned. By using the status query parameter it is possible to filter out all numbers of a given state (e.g. reserved, disconnected/deleted).

WARNING

This API will only browse the built in number inventory. Numbers that were ported in are not maintained in this inventory.

Request

Endpoint

GET /api/v01/draas/{draas_instance}/tenants/{uuid}/subscriptions/{subscription_id}/number_inventory

Authorization

Required role

tenants.instance.subscriptions.instance.number_inventory.list

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`	`integer`	Index of the subscription for which you want to list the licenses

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 25)	no
`page`	`integer`	Used for pagination, determines the returned page from the collection of result pages (defaults to 1)	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
`number_type`	`string`	Search for all numbers, linked to this subscription, that have a number type that contains this string	no
`country_code`	`string`	Search for all numbers, linked to this subscription, that have a country code that contains this string. A country code is typically a + followed by 2 or 3 digits (e.g. +32)	no
`nsn`	`string`	Search for all numbers, linked to this subscription, that have a national subscriber number that contains this digit string. The nsn is the national part of the e.164 number	no
`region`	`integer`	Search for all numbers that have a region that Use this parameter to search for all numbers that contains this string. The fullnumber is the phonenumber in e.164 format	no

Using multiple search parameters

When multiple search query parameters are provided, results will match all of them.

Multi-search not supported

It is currently not possible to provide a single search string that is matched across the different search parameters

Response

Status codes

Parameter	Description
`200`	One or more numbers found
`400`	Error while processing the request
`404`	No numbers found
`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?	Searchable?
`results`	`string`	Total count of results that match your query	no	no
`pageSize`	`string`	Results are not provided all at once. This parameter indicates how many results are returned per page.	no	no
`pages`	`string`	Total count of result pages that are available	no	no
`page`	`string`	ID of the page that is currently returned	no	no
`next`	`string`	A token generated as long as there are still pages to display in the list. This token may be used in a subsequent call to get the next page. It contains all query parameter from the request so they may be omitted in subsequent call	yes	no
`numbers`	`array`	List containing all number objects found in the NIMS for the subscription	no

NIMS Number Object

Parameter	Type	Description	Conditional?	Searchable?
`id`	`string`	Full number in e.164 format	no	yes
`countryCode`	`string`	Country code of the phone number. Typically a + followed by 2 or 3 digits (e.g. +32)	no	yes
`nsn`	`string`	National subscriber number. E.g. in +32-16474942, +32 is the country code and 16474942 is the nsn.	no	yes
`numberType`	`string`	Type of the number in question (e.g. geo, mobile, tollfree, ...)	no	yes
`region`	`string`	Geographical area to which the number is linked. Will be null if not linked to a region. Only geo-numbers will be linked to a geographical region. When not linked, Will be `null` if not linked	no	yes
`state`	`string`	Current state of the number. Possible values are: `assigned`, `reserved`, `disconnected`.	no	yes
`statusUpdatedOn`	`dateTime`	Indicates where this number comes from. Currently 2 sources are supported: number_inventory and ported_in	no	no

Example

json

{
    "results": 10,
    "pages": 1,
    "page_size": 10,
    "page": 1,
    "next": "c3RhdHVzPWRpc2Nvbm5lY3RlZCZwYWdlPTI=",
    "numbers": [
        {
            "id": 10001,
            "nsn": "25400000",
            "countryCode": "+32",
            "region": "Brussel",
            "numberType": "geo",
            "state": "reserved",
            "stateUpdatedOn": "2022-01-04T23:58:53"
        },
        {
            "id": 10002,
            "nsn": "25400001",
            "countryCode": "+32",
            "region": "Brussel",
            "numberType": "geo",
            "state": "reserved",
            "stateUpdatedOn": "2022-01-04T23:58:53"
        },
        {
            "id": 10003,
            "nsn": "25400002",
            "countryCode": "+32",
            "region": "Brussel",
            "numberType": "geo",
            "state": "reserved",
            "stateUpdatedOn": "2022-01-04T23:58:53"
        },
        {
            "id": 10004,
            "nsn": "25400003",
            "countryCode": "+32",
            "region": "Brussel",
            "numberType": "geo",
            "state": "reserved",
            "stateUpdatedOn": "2022-01-04T23:58:53"
        },
        {
            "id": 10005,
            "nsn": "25400004",
            "countryCode": "+32",
            "region": "Brussel",
            "numberType": "geo",
            "state": "reserved",
            "stateUpdatedOn": "2022-01-04T23:58:53"
        },
        {
            "id": 10006,
            "nsn": "25400005",
            "countryCode": "+32",
            "region": "Brussel",
            "numberType": "geo",
            "state": "reserved",
            "stateUpdatedOn": "2022-01-04T23:58:53"
        },
        {
            "id": 10007,
            "nsn": "25400006",
            "countryCode": "+32",
            "region": "Brussel",
            "numberType": "geo",
            "state": "reserved",
            "stateUpdatedOn": "2022-01-04T23:58:53"
        },
        {
            "id": 10008,
            "nsn": "25400007",
            "countryCode": "+32",
            "region": "Brussel",
            "numberType": "geo",
            "state": "reserved",
            "stateUpdatedOn": "2022-01-04T23:58:53"
        },
        {
            "id": 10010,
            "nsn": "25400009",
            "countryCode": "+32",
            "region": "Brussel",
            "numberType": "geo",
            "state": "reserved",
            "stateUpdatedOn": "2022-01-04T23:58:53"
        },
        {
            "id": 10009,
            "nsn": "25400008",
            "countryCode": "+32",
            "region": "Brussel",
            "numberType": "geo",
            "state": "reserved",
            "stateUpdatedOn": "2022-01-04T23:58:53"
        }
    ]
}

Add numbers to the subscription

This endpoint allows to associate phone numbers to the subscription. These numbers can then be used by MS Teams users or assigned to SIP trunks. Currently it is only possible to add numbers that are known in our inventory (so native numbers):

any number that is still available. You can get number suggestions using the number suggestion API.
numbers reserved for the subscription (use this API - state: reserved)
numbers previously connected to this subscription but now still in quarantine (use this API - state: disconnected)

The API will associate the numbers to the account and mark them in our inventory as assigned to the provided subscription

WARNING

Make sure the subscription has enough entitlements left for the numbers that you try to assign. If this is not the case, the transaction will be refused and fully rolled back

Request

Endpoint

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

Authorization

Required role

tenants.instance.subscriptions.instance.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`	`integer`	Index of the subscription to which you want to add an entitlement

URL/Query parameters

N/A

Body

Parameter	Type	Description	Required
`countryCode`	`string`	Country code of the numbers that you want to add. All numbers provided in this request are expected to share the same country code	no
`numbers`	`array`	Array of national subscriber numbers(nsn) (`integer`) that you want to add	no
`ranges`	`array`	Array of `arrays` where each array contains 2 national subscriber numbers (both `integer`): range start & range end	no

Example

json

{
    "countryCode":  "+32",
    "numbers": [
        25405220,
        25405221
    ],
    "ranges": [
        [25405230,25405239],
        [25405270,25405279]
    ]
}

Response

Status codes

Parameter	Description
`200`	The numbers were correctly added and assigned
`400`	Error while assigning the numbers to the subscription. This can be caused when you don't have enough entitlement or when you try to assign numbers that are already linked to another subscription (assigned/reserved/disconnected).
`403`	The API consumer doesn't have sufficient rights to perform this action
`404`	Subscription/tenant not found
`500`	Uncatched error on server side

Success

Body

Parameter	Type	Description	Conditional
`total`	`integer`	Total amount of numbers that you tried to add	no
`assigned`	`integer`	Total amount of numbers were really assigned to the subscription	yes
`alreadyAssigned`	`integer`	Total amount of numbers that were provided in the request but that were already added before	no
`failed`	`integer`	Total amount of numbers that could not be added to the subscription	yes

TIP

When some numbers cannot be added (e.g. one of the numbers you provided is already assigned to another subscription) then the entire transaction will be rolled back. However, if your request also contains numbers that were already assigned to the subscription, the assignement will not be rolled back.

So when a transaction is rolled back, 0 numbers will be assigned. However, if the transaction fails then 0 numbers will be failed.

Example

json

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

De-assign numbers from the subscription

This endpoint allows to de-assign phone numbers from the subscription:

numbers with source number_inventory will go into the DISCONNECTED state which means they will remain linked to the subscription but in quarantine mode. After a certain amount of time they will be released and made available for other customers.
numbers with source ported_in will go also go into quarantine mode. However, since they are not owned by us, we will have to return them to the native operator when the quarantine period has come to an end.
numbers into the DISCONNECTED state will be permanently deleted.

WARNING

only numbers that are currently not in use can be deleted

Request

Endpoint

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

Authorization

Required role

tenants.instance.subscriptions.instance.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`	`integer`	Index of the subscription to which you want to add an entitlement

URL/Query parameters

N/A

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 numbers that you want to add. All numbers provided in this request are expected to share the same country code	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": "+32", "nsn": 25405220},
        {"countryCode": "+32", "nsn": 25405221},
        {"countryCode": "+32", "nsn": 25405222}
    ]
}

Response

Status codes

Parameter	Description
`200`	The numbers were correctly de-assigned and put into quarantine
`400`	Error while de-assigning one or more numbers from the subscription (number does not belong to the subscription, it is still linked to a resource or an error occurred while de-assignment)
`403`	The API consumer doesn't have sufficient rights to perform this action
`404`	Subscription/tenant not found
`500`	Uncatched error on server side

Success

Body

Parameter	Type	Description	Conditional
`total`	`integer`	Total amount of numbers that you are trying to de-assign	no
`owned`	`integer`	Total amount of numbers that really belong to your subscription	no
`linked`	`integer`	Total amount of numbers that are still linked to a resource	yes
`deleted`	`integer`	Total amount of numbers that were successfuly de-assigned	yes
`error`	`integer`	Total amount of numbers that went in error while de-assigning and were rolled back	yes

Example

json

{
    "total": 5,
    "owned": 5,
    "linked": 0,
    "deleted": 4,
    "error": 1
}

Port numbers to the subscription

This endpoint allows to port in existing numbers from another service provider. This allows you to re-use your existing phone numbers through our platform

WARNING

Currently porting is only supported for the Netherlands

Pre-activating numbers

When issuing a port in request, numbers will be added to Fusion in a pre-activated status directly after the request has been accepted by the other party. This allows you to already assign these numbers to your MS Teams tenant users. However, these numbers will only be fully available after sending final activation by using this API

Request

Endpoint

POST /api/v01/draas/{draas_instance}/tenants/{uuid}/subscriptions/{subscription_id}/porting/requests

Authorization

Required role

tenants.instance.subscriptions.instance.porting.request.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`	`integer`	Index of the subscription to which you want to add an entitlement

URL/Query parameters

N/A

Body

Parameter	Type	Description	Required
`numbers`	`array`	List of single national subscriber numbers(nsn) you want to port in	no
`ranges`	`array`	List of national subscriber numbers(nsn) ranges you want to port in	no
`donorId`	`integer`	ID of the donnor operator as given by this interface	yes
`contactEmail`	`string`	Email of the contact person for providing information about the porting request	yes
`dueDate`	`string`	Due date for the porting request	yes
`lastName`	`string`	Last name specified at porting creation time	no
`companyName`	`string`	Company name specified at porting creation time	no
`houseNumber`	`string`	House number of the address specified a porting creation time	no
`houseNumberExt`	`string`	House number extension of the address specified a porting creation time	no
`zipCode`	`string`	Zip code of the address specified a porting creation time	no
`customerId`	`string`	Customer ID specified at porting creation time	no
`note`	`string`	Free note specified at porting creation time	no

Number Range Object

Parameter	Type	Description	Required
`from`	`string`	First national subscriber numbers(nsn) of the range you want to port in	yes
`to`	`string`	Last national subscriber numbers(nsn) of the range you want to port in	yes

Example

json

{
  "numbers": [
    "0234200130"
  ],
  "ranges": [
    {
      "from": "0234200135",
      "to": "0234200140"
    }
  ],
  "donorId": 2,
  "contactEmail": "john.doe@netaxis.onmicrosoft.com",
  "dueDate": "2022-02-19T10:34:57",
  "lastName": "Doe",
  "companyName": "Netaxis",
  "houseNumber": "1",
  "houseNumberExt": "bis",
  "zipCode": "1000AP",
  "customerId": "03450CHFR",
  "note": "This is an extended test",
}

Response

Status codes

Parameter	Description
`200`	The porting request has been accepted by NPACT system
`400`	Error while creating the porting request
`403`	The API consumer doesn't have sufficient rights to perform this action
`404`	Subscription/tenant not found
`500`	Uncatched error on server side

Success

Body

Parameter	Type	Description	Conditional
`id`	`integer`	ID of the porting request created in NPACT	no
`portId`	`string`	Port Id used as reference in the COIN database (Porting DB of the Netherlands)	no

Example

json

{
    "id": 67,
    "portId": "WECO-1646381106"
}

Add attachments to a porting request

This endpoint allows to add documents to a porting request. The list of required documents when porting numbers can be checked against this API.

WARNING

Currently porting is only supported for the Netherlands

Request

Endpoint

POST /api/v01/draas/{draas_instance}/tenants/{uuid}/subscriptions/{subscription_id}/porting/requests/{request_id}/attachments

Authorization

Required role

tenants.instance.subscriptions.instance.porting.request.attachment.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`	`integer`	Index of the subscription to which you want to add an entitlement
`request_id`	`integer`	ID of the porting request created in NPACT

URL/Query parameters

N/A

Body

N/A

Multipart Form Data

Parameter	Type	Description	Required
`description`	`string`	Document key as set by the `key` property returned by this API	yes
`content`	`file`	Link to the file you want to upload as attachment	yes

Response

Status codes

Parameter	Description
`200`	The document has been attached to the porting request
`400`	Error while attaching the document to the porting request
`403`	The API consumer doesn't have sufficient rights to perform this action
`404`	Subscription/tenant not found
`500`	Uncatched error on server side

Success

Body

Parameter	Type	Description	Conditional
`id`	`integer`	ID of the attached document in NPACT database	no

Example

json

{
    "id": 2
}

Remove attachments from a porting request

This endpoint allows to remove documents from a porting request.

WARNING

Currently porting is only supported for the Netherlands

Request

Endpoint

DELETE /api/v01/draas/{draas_instance}/tenants/{uuid}/subscriptions/{subscription_id}/porting/requests/{request_id}/attachments/{document_id}

Authorization

Required role

tenants.instance.subscriptions.instance.porting.request.attachment.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`	`integer`	Index of the subscription to which you want to add an entitlement
`request_id`	`integer`	ID of the porting request created in NPACT
`document_id`	`integer`	ID of the document attached to the porting request in NPACT

URL/Query parameters

N/A

Body

N/A

Response

Status codes

Parameter	Description
`204`	The document has been removed from the porting request
`400`	Error while removing the document from the porting request
`403`	The API consumer doesn't have sufficient rights to perform this action
`404`	Subscription/tenant not found
`500`	Uncatched error on server side

Get the list of porting requests for a subscription

This endpoint gives the list of porting requests that have been sent for the subscription

WARNING

Currently porting is only supported for the Netherlands

Request

Endpoint

GET /api/v01/draas/{draas_instance}/tenants/{uuid}/subscriptions/{subscription_id}/porting/requests

Authorization

Required role

tenants.instance.subscriptions.instance.porting.request.list

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`	`integer`	Index of the subscription to which you want to add an entitlement

URL/Query parameters

Parameter	Type	Description	Required?
`size`	`integer`	Used for pagination, determines the maximum number of records on one page of results (defaults to 10)	no
`page_size`	`integer`	Used for pagination, determines the returned page from the collection of result pages (defaults to 1)	no

Body

N/A

Response

Status codes

Parameter	Description
`200`	The list of porting requests for the subscription
`400`	Error while reading the list of porting requests
`403`	The API consumer doesn't have sufficient rights to perform this action
`404`	Subscription/tenant not found
`500`	Uncatched error on server side

Success

Body

Parameter	Type	Description	Conditional
`results`	`integer`	Total number of results from the query	no
`pages`	`integer`	Total number of pages according to pagination settings	no
`page`	`integer`	Current displayed page from the set of pages	no
`requests`	`array`	List containing all porting requests for the subscription	no

Porting Request Object

Parameter	Type	Description	Conditional
`id`	`integer`	ID of the porting request created in NPACT	no
`portId`	`string`	Port Id used as reference in the COIN database (Porting DB of the Netherlands)	no
`createdOn`	`string`	Creation date of the porting request in NPACT	no
`dueDate`	`string`	Due date for the porting request	no
`kind`	`string`	Kind of porting request	no
`donor`	`object`	Donnor operator as given by this interface	no
`status`	`string`	Status of the porting request	no
`numbers`	`array`	List of single national subscriber numbers(nsn) required by the port in request	no
`ranges`	`array`	List of national subscriber numbers(nsn) ranges required by the port in request	no

Operator Object

Parameter	Type	Description	Conditional
`id`	`integer`	ID of the operator for porting	no
`name`	`string`	Name of the operator for porting	no

Example

json

{
  "results": 8,
  "pages": 4,
  "page": 4,
  "requests": [
    {
      "id": 55,
      "portId": "WECO-1645453288",
      "createdOn": "2022-02-21T14:21:28",
      "dueDate": "2022-02-19T10:34:57",
      "kind": "PortIn",
      "donor": {
        "id": 2,
        "name": "T108"
      },
      "status": "waiting acceptance",
      "numbers": [
        "0234200101"
      ],
      "ranges": [
        {
          "from": "0234200102",
          "to": "0234200105"
        }
      ]
    },
    {
      "id": 52,
      "portId": "WECO-1645203338",
      "createdOn": "2022-02-18T16:55:38",
      "dueDate": "2022-02-21T00:00:00",
      "kind": "PortIn",
      "donor": {
        "id": 2,
        "name": "T108"
      },
      "status": "ported",
      "ranges": [
        {
          "from": "0234200099",
          "to": "0234200100"
        }
      ]
    }
  ]
}

Get the detail of a porting request for a subscription

This endpoint gives details about a specific porting request that has been sent for the subscription

WARNING

Currently porting is only supported for the Netherlands

Request

Endpoint

GET /api/v01/draas/{draas_instance}/tenants/{uuid}/subscriptions/{subscription_id}/porting/requests/{request_id}

Authorization

Required role

tenants.instance.subscriptions.instance.porting.request.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`	`integer`	Index of the subscription to which you want to add an entitlement
`request_id`	`integer`	ID of the porting request created in NPACT

URL/Query parameters

N/A

Body

N/A

Response

Status codes

Parameter	Description
`200`	The details of the porting request for the subscription
`400`	Error while reading the details of the porting request
`403`	The API consumer doesn't have sufficient rights to perform this action
`404`	Subscription/tenant not found
`500`	Uncatched error on server side

Success

Body

Parameter	Type	Description	Conditional
`capabilities`	`object`	Gives a summary through a capabilities object of possible actions and current state of the porting request	no
`instance`	`object`	Gives details about the current NPACT instance controlling the porting request	no
`request`	`object`	Gives details about the current porting requests	no
`attachments`	`array`	List of all documents that have been attached to a porting request	no

Capabilities Object

Parameter	Type	Description	Conditional
`canBeCancelled`	`boolean`	Indicates if the porting request may be canceled by using this API	no
`canBeActivated`	`boolean`	Indicates if the porting request may be activated by using this API	no
`isFinished`	`boolean`	Indicates that the porting request is complete	no
`isError`	`boolean`	Indicates that the porting request is in error	no
`isCancelled`	`boolean`	Indicates that the porting request has been canceled	no
`isRejected`	`boolean`	Indicates that the porting request has been rejected	no

Instance Object

Parameter	Type	Description	Conditional
`createdOn`	`string`	Creation date of the porting request in NPACT	no
`updatedOn`	`string`	Last modification date of the porting request in NPACT	no
`status`	`string`	Running status of the instance controlling the porting request in NPACT	no

Request Object

Parameter	Type	Description	Conditional
`id`	`integer`	ID of the porting request created in NPACT	no
`portId`	`string`	Port Id used as reference in the COIN database (Porting DB of the Netherlands)	no
`dueDate`	`string`	Due date for the porting request	no
`kind`	`string`	Kind of porting request	no
`isoCode`	`string`	The ISO 3166 country code (only "NL" is supported by now)	no
`donor`	`object`	Donnor operator as given by this interface	no
`status`	`string`	Status of the porting request	no
`contactEmail`	`string`	Email of the contact person for providing information about the porting request	no
`lastName`	`string`	Last name specified at porting creation time	yes
`companyName`	`string`	Company name specified at porting creation time	yes
`houseNumber`	`string`	House number of the address specified a porting creation time	yes
`houseNumberExt`	`string`	House number extension of the address specified a porting creation time	yes
`zipCode`	`string`	Zip code of the address specified a porting creation time	yes
`customerId`	`string`	Customer ID specified at porting creation time	yes
`note`	`string`	Free note specified at porting creation time	yes
`serviceType`	`string`	Service type of the porting request	yes
`subscriberData`	`object`	JSON object containing specific informations about the porting request	no
`numbers`	`array`	List of single national subscriber numbers(nsn) required by the port in request	no
`ranges`	`array`	List of national subscriber numbers(nsn) ranges required by the port in request	no

Attachment Object

Parameter	Type	Description	Conditional
`id`	`integer`	ID of the attached document in NPACT database	no
`name`	`string`	Original name of the uploaded document	no
`createdBy`	`string`	ID of the person who uploaded the document	no
`description`	`string`	Document key as set by the `key` property returned by this API	no
`mimeType`	`string`	MIME type of the uploaded document	no
`sizeInBytes`	`integer`	Size in bytes of the uploaded the document	no
`createdBy`	`string`	ID of the person who uploaded the document	no
`createdOn`	`string`	Attachment date of the uploaded document	no

Example

json

{
  "capabilities": {
    "canBeCancelled": false,
    "canBeActivated": false,
    "isFinished": true,
    "isError": false,
    "isCancelled": true,
    "isRejected": false
  },
  "instance": {
    "createdOn": "2022-03-04T08:05:06",
    "updatedOn": "2022-03-07T10:46:26",
    "status": "CLOSED_IN_ERROR"
  },
  "request": {
    "id": 56,
    "portId": "WECO-1646381106",
    "dueDate": "2022-03-07T00:00:00",
    "kind": "PortIn",
    "isoCode": "NL",
    "donor": {
      "id": 2,
      "name": "T108"
    },
    "status": "cancelled",
    "contactEmail": "john.doe@netaxis.be",
    "lastName": "Doe",
    "companyName": "Netaxis",
    "houseNumber": "1",
    "houseNumberExt": "bis",
    "zipCode": "1000AP",
    "customerId": "03450CHFR",
    "note": "This is an extended test",
    "serviceType": "GEOGRAPHIC",
    "subscriberData": {
      "contract": "CONTINUATION"
    },
    "numbers": [
      "0234200130"
    ],
    "ranges": [
      {
        "from": "0234200135",
        "to": "0234200140"
      }
    ]
  },
  "attachments": [
    {
      "id": 2,
      "name": "loa_test.pdf",
      "createdBy": "john.doe",
      "description": "loa",
      "mimeType": "application/pdf",
      "sizeInBytes": 13801,
      "createdOn": "2022-03-09T07:54:28"
    },
    {
      "id": 5,
      "name": "me.jpeg",
      "createdBy": "john.doe",
      "description": "id",
      "mimeType": "image/jpeg",
      "sizeInBytes": 8610,
      "createdOn": "2022-03-09T12:35:45"
    }
  ]
}

Activate a porting request

This endpoint allows to activate an existing port in request. To be able to perform this action, the property canBeActivated of the capabilities object returned by this API should be true.

WARNING

Currently porting is only supported for the Netherlands

Request

Endpoint

PUT /api/v01/draas/{draas_instance}/tenants/{uuid}/subscriptions/{subscription_id}/porting/requests/{request_id}/activate

Authorization

Required role

tenants.instance.subscriptions.instance.porting.request.activate

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`	`integer`	Index of the subscription to which you want to add an entitlement
`request_id`	`integer`	ID of the porting request created in NPACT

URL/Query parameters

N/A

Body

N/A

Response

Status codes

Parameter	Description
`200`	The porting request has been sent for activation to NPACT system
`400`	Error while sending the activation request or at least one phone number has been found in error
`403`	The API consumer doesn't have sufficient rights to perform this action
`404`	Subscription/tenant not found
`500`	Uncatched error on server side

Success

Body

Parameter	Type	Description	Conditional
`total`	`integer`	Total number of phone numbers concerned by the activation of the porting request	no
`alreadyActivated`	`integer`	Total number of phone numbers that already were activated in Fusion database	no
`added`	`integer`	Total number of phone numbers that have been added and activated in Fusion database	no
`activated`	`integer`	Total number of phone numbers that have been activated in Fusion database	no
`error`	`integer`	Total number of phone numbers that ended up in error while modifying them in Fusion database	no

Example

json

{
    "total": 3,
    "alreadyActivated": 0,
    "added": 3,
    "activated": 0,
    "error": 0
}

Cancel a porting request

This endpoint allows to cancel an existing port in request. To be able to perform this action, the property canBeCancelled of the capabilities object returned by this API should be true.

WARNING

Currently porting is only supported for the Netherlands

Request

Endpoint

PUT /api/v01/draas/{draas_instance}/tenants/{uuid}/subscriptions/{subscription_id}/porting/requests/{request_id}/cancel

Authorization

Required role

tenants.instance.subscriptions.instance.porting.request.cancel

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`	`integer`	Index of the subscription to which you want to add an entitlement
`request_id`	`integer`	ID of the porting request created in NPACT

URL/Query parameters

N/A

Body

N/A

Response

Status codes

Parameter	Description
`200`	The porting request has been sent for cancellation to NPACT system
`400`	Error while sending the cancellation request or at least one phone number has been found in error
`403`	The API consumer doesn't have sufficient rights to perform this action
`404`	Subscription/tenant not found
`500`	Uncatched error on server side

Success

Body

Parameter	Type	Description	Conditional
`total`	`integer`	Total number of phone numbers concerned by the activation of the porting request	no
`alreadyDeleted`	`integer`	Total number of phone numbers that already were deleted from Fusion database	no
`deleted`	`integer`	Total number of phone numbers that have been deleted from Fusion database	no
`stillLinked`	`integer`	Total number of phone numbers that couldn't be removed because they are still linked to a MS Teams tenant	no
`error`	`integer`	Total number of phone numbers that ended up in error while deleting them from Fusion database	no

Example

json

{
    "total": 3,
    "alreadyDeleted": 0,
    "deleted": 3,
    "stillLinked": 0,
    "error": 0
}

Numbers ​

Retrieve Number Inventory Type ​

Request ​

Endpoint ​

Authorization ​

Path Parameters ​

URL/Query parameters ​

Response ​

Status codes ​

Success ​

Body ​

Example ​

List all numbers of a subscription ​

Request ​

Endpoint ​

Authorization ​

Path Parameters ​

URL/Query parameters ​

Response ​

Status codes ​

Success ​

Body ​

Number Object ​

AssignedTo Object ​

Example ​

List free numbers of a subscription ​

Request ​

Endpoint ​

Authorization ​

Path Parameters ​

URL/Query parameters ​

Body ​

Response ​

Status codes ​

Success ​

Body ​

Example ​

Linked numbers in the inventory ​

Request ​

Endpoint ​

Authorization ​

Path Parameters ​

URL/Query parameters ​

Response ​

Status codes ​

Success ​

Body ​

NIMS Number Object ​

Example ​

Add numbers to the subscription ​

Request ​

Endpoint ​

Authorization ​

Path Parameters ​

URL/Query parameters ​

Body ​

Example ​

Response ​

Status codes ​

Success ​

Body ​

Example ​

De-assign numbers from the subscription ​

Request ​

Endpoint ​

Authorization ​

Path Parameters ​

URL/Query parameters ​

Body ​

Number to delete object ​

Example ​

Response ​

Status codes ​

Success ​

Body ​

Example ​

Port numbers to the subscription ​

Request ​

Endpoint ​

Authorization ​

Numbers

Retrieve Number Inventory Type

Request

Endpoint

Authorization

Path Parameters

URL/Query parameters

Response

Status codes

Success

Body

Example

List all numbers of a subscription

Request

Endpoint

Authorization

Path Parameters

URL/Query parameters

Response

Status codes

Success

Body

Number Object

AssignedTo Object

Example

List free numbers of a subscription

Request

Endpoint

Authorization

Path Parameters

URL/Query parameters

Body

Response

Status codes

Success

Body

Example

Linked numbers in the inventory

Request

Endpoint

Authorization

Path Parameters

URL/Query parameters

Response

Status codes

Success

Body

NIMS Number Object

Example

Add numbers to the subscription

Request

Endpoint

Authorization

Path Parameters

URL/Query parameters

Body

Example

Response

Status codes

Success

Body

Example

De-assign numbers from the subscription

Request

Endpoint

Authorization

Path Parameters

URL/Query parameters

Body

Number to delete object

Example

Response

Status codes

Success

Body

Example

Port numbers to the subscription

Request

Endpoint

Authorization