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_type

GET /api/v01/draas/{draas_instance}/distributors/{uuid}/number_inventory_type

GET /api/v01/draas/{draas_instance}/resellers/{uuid}/number_inventory_type

GET /api/v01/draas/{draas_instance}/tenants/{uuid}/number_inventory_type

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

Authorization

Required role

groups.instance.number_inventory_type.read distributors.instance.number_inventory_type.read resellers.instance.number_inventory_type.read tenants.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, the distributor, the reseller or the tenant (to which the subscription belongs)
sub_id	integer	Index of the subscription for which you want to retrieve the inventory type (only for the subscription endpoint)

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, distributor, reseller, tenant or subscription. Could be gamma (it will use the Gamma service to manage numbers) or default (It will use our NIMS)	no

Example

{
  "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?
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
page_size	integer	Used for pagination, determines the maximum number of records on one page of results (defaults to 10)	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
filters	object	Used to perform advanced filtering on the query. See the Numbers Filters Object.	no

Numbers Filters Object

Parameter	Type	Description	Required?
addressId	string,null	The address ID	no
countryCode	string	The country code	no

Response

Status codes

Parameter	Description
200	One or more numbers found
400	Error while processing the request
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
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?
id	integer	ID of the number in database	no	no
address	boolean	The address assigned to the number	no	no
addressId	boolean	ID of the address linked to a number	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
countryCode	string	Country code of the phone number. Typically a + followed by 2 or 3 digits (e.g. +32)	no	yes
fullNumber	string	The fullnumber is the phonenumber in e.164 format	no	yes
isoCode	string	The ISO 3166 country code	no	yes
nsn	string	National subscriber number. E.g. in +32-16474942, +32 is the country code and 16474942 is the nsn	no	yes
numberDivert	string	The number to divert to in e164 format	no	no
numberRewrite	string	The number to rewrite to in e164 format	no	no
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

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

{
    "numbers": [
        {
            "address": "Rue du Trône, 59, Ixelles, Belgium",
            "addressId": 3,
            "addressVerified": false,
            "assigned": true,
            "assignedTo": {
                "ref": "IDAL trunk",
                "to": 2,
                "type": "sip_trunk"
            },
            "countryCode": "+32",
            "fullNumber": "+3225409941",
            "id": 3,
            "isoCode": "BE",
            "nsn": 25409941,
            "numberDivert": "+32478604964",
            "numberRewrite": "+32478604964",
            "numberType": "geo",
            "source": "number_inventory",
            "status": "active"
        },
        {
            "assigned": true,
            "assignedTo": {
                "ref": "IDAL trunk",
                "to": 2,
                "type": "sip_trunk"
            },
            "countryCode": "+32",
            "fullNumber": "+3225409942",
            "id": 4,
            "isoCode": "BE",
            "nsn": 25409942,
            "numberDivert": "+3222449904",
            "numberRewrite": "+3222449907",
            "numberType": "geo",
            "source": "number_inventory",
            "status": "active"
        },
        {
            "assigned": true,
            "assignedTo": {
                "ref": "IDAL trunk",
                "to": 2,
                "type": "sip_trunk"
            },
            "countryCode": "+32",
            "fullNumber": "+3225409943",
            "id": 5,
            "isoCode": "BE",
            "nsn": 25409943,
            "numberDivert": "+3222449903",
            "numberRewrite": "+3222449902",
            "numberType": "geo",
            "source": "number_inventory",
            "status": "active"
        },
        {
            "assigned": false,
            "countryCode": "+32",
            "fullNumber": "+3225409945",
            "id": 7,
            "isoCode": "BE",
            "nsn": 25409945,
            "numberDivert": "",
            "numberRewrite": "",
            "numberType": "geo",
            "source": "number_inventory",
            "status": "active"
        },
        {
            "address": "Rue du Trône, 59, Ixelles, Belgium",
            "addressId": 3,
            "addressVerified": true,
            "assigned": false,
            "countryCode": "+32",
            "fullNumber": "+3225429900",
            "id": 2,
            "isoCode": "BE",
            "nsn": 25429900,
            "numberDivert": "",
            "numberRewrite": "",
            "numberType": "geo",
            "source": "number_inventory",
            "status": "active"
        }
    ],
    "page": 1,
    "pages": 1,
    "results": 5
}

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

{
  "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 10)	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
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

{
    "results": 10,
    "pages": 1,
    "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"
        }
    ]
}

Reserve or free numbers in the inventory

Use this endpoint to reserve numbers of the number inventory for a subscription, or to cancel an existing reservation (the numbers become available again). Reserved numbers can later be added to the subscription (see Add numbers to the subscription).

A request handles numbers of a single country code: send one request per country code.

Request

Endpoint

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

Authorization

Required role

tenants.instance.subscriptions.instance.number_inventory.reserve

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
subscription_id	integer	Index of the subscription for which you want to reserve or free numbers

URL/Query parameters

N/A

Body

Parameter	Type	Description	Required?
countryCode	string	Country code of the numbers. All numbers provided in this entry are expected to share the same country code	yes
reserve	array	Array of national subscriber numbers (integer) to reserve for the subscription	yes
cancelReservation	array	Array of national subscriber numbers (integer) currently reserved for the subscription for which the reservation has to be cancelled	yes

Example

{
    "countryCode": "+32",
    "reserve": [
        25405220,
        25405221
    ],
    "cancelReservation": [
        25405230
    ]
}

Response

Status codes

Parameter	Description
200	The numbers were correctly reserved / freed
400	Error while processing the request (e.g. numbers not available or not reserved for this subscription)
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

N/A

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

Once completed, a notification will be sent through webhook or email (if enabled) as described on add_number_subscription event

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

{
    "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

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

Modify a number

Use this endpoint to modify an existing number for a subscription.

Once completed, a notification will be sent through webhook or email (if enabled) as described on update_number_subscription event

Request

Endpoint

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

Authorization

Required role

tenants.instance.subscriptions.instance.numbers.instance.update

Path Parameters

Parameter	Type	Description
draas_instance	string	See common parameters
uuid	string	A system generated unique ID (UUID) identifying the tenant for which you want to modify the address
sub_id	integer	Index of the subscription for which you want to update a address
number	string	Phone numbers in e164 format you want to update

<URL/Query parameters>

N/A

Body

Parameter	Type	Description	Conditional?
addressId	integer	The address to be assigned to the number	no
numberDivert	string	The number to divert to in e164 format	no
numberRewrite	string	The number to rewrite to in e164 format	no
disasterRecoveryNumber	string	The number to disaster recovery to in e164 format	no

Example

{
    "addressId": 15,
    "numberDivert": "+32478604964",
    "numberRewrite": "+32478604966",
    "disasterRecoveryNumber": ""
}

Response

Status codes

Parameter	Description
200	The number has been correctly updated
400	Error while updating the number
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 number in database	no
address	boolean	The address assigned to a number	no
addressId	boolean	ID of the address linked to a number	no
assigned	boolean	Indicates whether or not the number is currently in use	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
countryCode	string	Country code of the phone number. Typically a + followed by 2 or 3 digits (e.g. +32)	no
disasterRecoveryNumber	string	The number to disaster recovery to in e164 format	no
fullNumber	string	The fullnumber is the phonenumber in e.164 format	no
isoCode	string	The ISO 3166 country code	no
nsn	string	National subscriber number. E.g. in +32-16474942, +32 is the country code and 16474942 is the nsn	no
numberDivert	string	The number to divert to in e164 format	no
numberRewrite	string	The number to rewrite to in e164 format	no
numberType	string	Type of the number in question (e.g. geo, mobile, tollfree, ...)	no
source	string	Indicates where this number comes from. Currently 2 sources are supported: number_inventory and ported_in	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

Example

{
    "address": "Rue du Trône, 59, Ixelles, Belgium",
    "addressId": 3,
    "addressVerified": true,
    "assigned": false,
    "countryCode": "+32",
    "disasterRecoveryNumber": "",
    "fullNumber": "+3225429900",
    "id": 2,
    "isoCode": "BE",
    "nsn": 25429900,
    "numberDivert": "",
    "numberRewrite": "",
    "numberType": "geo",
    "source": "number_inventory",
    "status": "active"
}

Bulk modify numbers

Use this endpoint to modify several numbers of a subscription at once. The same divert, rewrite and disaster recovery settings are applied to all numbers in the request.

Request

Endpoint

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

Authorization

Required role

tenants.instance.subscriptions.instance.numbers.bulk.update

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
subscription_id	integer	Index of the subscription for which you want to update the numbers

URL/Query parameters

N/A

Body

Parameter	Type	Description	Required?
numbers	array	List of phone numbers (string) in e164 format that you want to update	yes
addressId	integer	The address to be assigned to the numbers	no
numberDivert	string	The number to divert to in e164 format	no
numberRewrite	string	The number to rewrite to in e164 format	no
disasterRecoveryNumber	string	The number to disaster recovery to in e164 format	no

Example

{
    "numbers": [
        "+3225409941",
        "+3225409942"
    ],
    "numberDivert": "+32478604964",
    "numberRewrite": "+32478604966",
    "disasterRecoveryNumber": ""
}

Response

Status codes

Parameter	Description
200	The numbers have been correctly updated
400	Error while updating the numbers
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

N/A

Modify the global breakout of a number

Use this endpoint to set or remove the global breakout of a number of a subscription. The allowed values are managed by the draas_enabled_global_breakout configuration key (comma separated list). The current value is returned in the extra.global_breakout property of the number object.

Request

Endpoint

PUT /api/v01/draas/{draas_instance}/tenants/{uuid}/subscriptions/{subscription_id}/numbers/{number}/breakout

Authorization

Required role

tenants.instance.subscriptions.instance.numbers.instance.breakout.update

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
subscription_id	integer	Index of the subscription to which the number belongs
number	string	Phone number in e164 format you want to update

URL/Query parameters

N/A

Body

Parameter	Type	Description	Required?
value	string	The global breakout to apply to the number. Must be one of the values of the draas_enabled_global_breakout configuration key. Use null to remove the global breakout	yes

Example

{
    "value": "gamma"
}

Response

Status codes

Parameter	Description
200	The global breakout of the number has been correctly updated
400	Error while updating the global breakout (e.g. value not allowed)
403	The API consumer doesn't have sufficient rights to perform this action
404	Subscription/tenant/number not found
500	Uncatched error on server side

Success

Body

N/A

Check the validation status of address to number

Use this endpoint to check the validation status of an address that has been linked to a number for a subscription.

Request

Endpoint

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

Authorization

Required role

tenants.instance.subscriptions.instance.numbers.instance.verify

Path Parameters

Parameter	Type	Description
draas_instance	string	See common parameters
uuid	string	A system generated unique ID (UUID) identifying the tenant for which you want to check the validation status
sub_id	integer	Index of the subscription for which you want to check the validation status
number	string	Phone numbers in e164 format you want to check the validation status

<URL/Query parameters>

Parameter	Type	Description	Required?
ref	string	Reference code for verifying an address	yes

Body

N/A

Response

Status codes

Parameter	Description
200	The address linked to a number has been not verified yet
400	Error while verifying the address linked to a number
500	Uncatched error on server side

Success

Body

Parameter	Type	Description	Conditional?
number	integer	The phone number	no
address	integer	The address	no

Example

{
  "address": "Rue du Trône, 69, Ixelles, Belgium",
  "number": "+3225405643"
}

Verify address linked to number

Use this endpoint to verify an address that has been linked to a number for a subscription. An address can be verified only once.

Request

Endpoint

PUT /api/v01/draas/{draas_instance}/tenants/{uuid}/subscriptions/{subscription_id}/numbers/{number}/address_verify

PUT /api/v01/public/{draas_instance}/tenants/{uuid}/subscriptions/{subscription_id}/numbers/{number}/address_verify

Authorization

Required role

tenants.instance.subscriptions.instance.numbers.instance.verify

Path Parameters

Parameter	Type	Description
draas_instance	string	See common parameters
uuid	string	A system generated unique ID (UUID) identifying the tenant for which you want to verify an address
sub_id	integer	Index of the subscription for which you want to verify an address
number	string	Phone numbers in e164 format you want to verify

<URL/Query parameters>

Parameter	Type	Description	Required?
ref	string	Reference code for verifying an address	yes

Body

N/A

Response

Status codes

Parameter	Description
200	The address linked to a number has been verified correctly
400	Error while verifying the address linked to a number
500	Uncatched error on server side

Success

Body

N/A

Check the validation status of multi address linked to numbers

Use this endpoint to check the validation status of multi addresses that has been linked to numbers of a group.

Request

Endpoint

GET /api/v01/draas/{draas_instance}/groups/{uuid}/numbers/multi_address_verify

Authorization

Required role

groups.instance.numbers.list.multi_address_verify

Path Parameters

Parameter	Type	Description
draas_instance	string	See common parameters
uuid	string	A system generated unique ID (UUID) identifying the group

<URL/Query parameters>

Parameter	Type	Description	Required?
ref	string	Reference code for verifying an address	yes
nsns	strijg	Reference of addresses-phone numbers to be verified	yes

Body

N/A

Response

Status codes

Parameter	Description
200	The addresses linked to the numbers has been verified
400	Error while verifying the address linked to a number
500	Uncatched error on server side

Success

Body

Parameter	Type	Description	Conditional?
results	array	List containing the verification results	no

Multi Address-Numbers Verification Object

Parameter	Type	Description	Conditional?
address	string	The address	no
code	string	The reference code	no
number	string	The number	no
valid	boolean	The valid. Only if valid.	yes

Example

{
  "results": [
    {
        "address": "Rue du Trône 2.0, 69, Ixelles, Belgium",
        "code": "2b377c885de97fc3d0ef3f7ba6c5e69a80e9e2012688634c25e6b61876dcaaf7",
        "number": "+3225409944",
        "valid": true
    },
    {
        "address": "Rue du Trône 2.0, 69, Ixelles, Belgium",
        "number": "+3225409941",
        "valid": false
    },
    {
        "address": "Rue du Trône, 59, Ixelles, Belgium",
        "code": "0516435525fb93954e7d8a7883db72e31b0416846f609445935bdd1078306b3a",
        "number": "+3225409942",
        "valid": true
    }
  ]
}

Verify multi address linked to numbers

Use this endpoint to verify a list of addresses that has been linked to numbers of a group. Can be verified only once, already verified address-numbers will be ignored.

Request

Endpoint

PUT /api/v01/draas/{draas_instance}/groups/{uuid}/numbers/multi_address_verify

Authorization

Required role

groups.instance.numbers.list.multi_address_verify

Path Parameters

Parameter	Type	Description
draas_instance	string	See common parameters
uuid	string	A system generated unique ID (UUID) identifying the group

<URL/Query parameters>

N/A

Body

Parameter	Type	Description	Required?
ref	string	Reference code for verifying an address	yes
nsns	array	The list of phone numbers to be verified with the addresses	yes

Example

{
  "ref": "MGQ5YTFjZTg4MWQ2YzBhNTU5NTE0OGRmOTJmNGM3NDRmODNhMWIwMzVjNzMzY2I1ZjRkNDI3NjAzNWNlOTIxMCwwNTE2NDM1NTI1ZmI5Mzk1NGU3ZDhhNzg4M2RiNzJlMzFiMDQxNjg0NmY2MDk0NDU5MzViZGQxMDc4MzA2YjNhLDJiMzc3Yzg4NWRlOTdmYzNkMGVmM2Y3YmE2YzVlNjlhODBlOWUyMDEyNjg4NjM0YzI1ZTZiNjE4NzZkY2FhZjc=",
  "nsns": [
    "+3225409944",
    "+3225409941",
    "+3225409942"
  ]
}

Response

Status codes

Parameter	Description
200	The addresses linked to the numbers has been verified
400	Error while verifying the address linked to a number
500	Uncatched error on server side

Success

Body

Parameter	Type	Description	Conditional?
errors	integer	The amount of errors	no
ignored	integer	The amount of ignored address-numbers	no
modified	integer	The amount of modified address-numbers	no
total	integer	The amount of total address-numbers	no

Example

{
    "errors": 0,
    "ignored": 1,
    "modified": 2,
    "total": 3
}

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.

Once completed, a notification will be sent through webhook or email (if enabled) as described on remove_numbers_subscription_event

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

{
    "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

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

De-assign completely numbers from the subscription

This endpoint allows to de-assign completely 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.

Once completed, a notification will be sent through webhook or email (if enabled) as described on remove_completely_numbers_subscription_event

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/unquarantine

Authorization

Required role

tenants.instance.subscriptions.instance.numbers.unquarantine.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

{
    "numbers": [
        {"countryCode": "+32", "nsn": 25405220},
        {"countryCode": "+32", "nsn": 25405221},
        {"countryCode": "+32", "nsn": 25405222}
    ]
}

Response

Status codes

Parameter	Description
200	The numbers were correctly unquarantined
400	Error while unquarantining 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
unquarantined	integer	Total amount of numbers that were successfuly unquarantined	no
error	integer	Total amount of numbers that went in error while de-assigning and were rolled back	no

Example

{
    "total": 3,
    "unquarantined": 3,
    "error": 0
}

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

{
  "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

{
    "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

{
    "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

{
  "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

{
  "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

{
    "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

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

Get a number inventory range

This endpoint returns the details of a single number range of the number inventory. The list of ranges is described in Get all number ranges known in the NIMS.

Request

Endpoint

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

Authorization

Required role

groups.instance.number_inventory.ranges.instance.read tenants.instance.subscriptions.instance.number_inventory.ranges.instance.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
subscription_id	integer	Index of the subscription (only for the subscription endpoint)
id	integer	Index of the number range you want to retrieve

URL/Query parameters

N/A

Response

Status codes

Parameter	Description
200	The number range is returned
400	Error while processing the request
403	The API consumer doesn't have sufficient rights to perform this action
404	Number range not found
500	Uncatched error on server side

Success

Body

Parameter	Type	Description	Conditional?
id	integer	Internal index of the range	no
countryCode	string	Country code of the numbers in this range	no
rangeStart	integer	Start of the range (national subscriber number)	no
rangeEnd	integer	End of the range (national subscriber number)	no
numberType	string	Number type of the numbers in this range (see number types)	no
vanityType	string	Vanity type of the numbers in this range (see vanity types). null if not set	yes
supplier	string	Supplier of the range (see suppliers). null if not set	yes
region	integer	Geographical region to which this number range is assigned (only relevant for certain numberTypes)	yes
nbAvailable	integer	Amount of numbers still available for assignment in this range	no
nbTotal	integer	Total amount of numbers in this range	no
createdOn	DateTime	Timestamp when this entry was added in the backend	no
updatedOn	DateTime	Timestamp when this entry was last updated in the backend	no

Example

{
    "id": 2,
    "countryCode": "+32",
    "rangeStart": 25400000,
    "rangeEnd": 25409999,
    "numberType": "geo",
    "vanityType": null,
    "supplier": null,
    "region": 2,
    "nbAvailable": 9990,
    "nbTotal": 10000,
    "createdOn": "2022-01-03T01:59:11",
    "updatedOn": "2022-01-03T01:59:11"
}

Get the number statuses of a number inventory range

This endpoint returns, for a given range of the number inventory, the sub-ranges of numbers grouped by state from the point of view of the subscription (e.g. numbers still available or reserved for the subscription). It is used to select the numbers to reserve or free (see Reserve or free numbers in the inventory).

Request

Endpoint

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

Authorization

Required role

tenants.instance.subscriptions.instance.number_inventory.ranges.instance.statuses.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
subscription_id	integer	Index of the subscription
id	integer	Index of the number range

URL/Query parameters

Parameter	Type	Description	Required?
status	string	Only return the sub-ranges in this state. Possible values are available and reserved	no
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

Response

Status codes

Parameter	Description
200	The statuses of the range are returned
400	Error while processing the request
403	The API consumer doesn't have sufficient rights to perform this action
404	Number range/subscription/tenant not found
500	Uncatched error on server side

Success

Body

Parameter	Type	Description	Conditional?
statuses	array	List of range status objects	no
next	string	Token used for infinite scrolling, to be used in the next call to retrieve subsequent records. Only present if the list has to be continued	yes

Range Status Object

Parameter	Type	Description	Conditional?
start	integer	First national subscriber number of the sub-range	no
end	integer	Last national subscriber number of the sub-range	no
state	string	State of the numbers in the sub-range (e.g. available, reserved)	no

Example

{
    "statuses": [
        {
            "start": 25400000,
            "end": 25400009,
            "state": "reserved"
        },
        {
            "start": 25400020,
            "end": 25400029,
            "state": "reserved"
        }
    ]
}

Create a number inventory range

Use this endpoint to add a new number range to the number inventory of a group.

Request

Endpoint

POST /api/v01/draas/{draas_instance}/groups/{uuid}/number_inventory/ranges

Authorization

Required role

groups.instance.number_inventory.ranges.create

Path Parameters

Parameter	Type	Description
draas_instance	string	See common parameters
uuid	string	A system generated unique ID (UUID) identifying the group

URL/Query parameters

N/A

Body

Parameter	Type	Description	Required?
countryCode	string	Country code of the numbers in the range (e.g. +32)	yes
start	integer	Start of the range (national subscriber number)	yes
end	integer	End of the range (national subscriber number)	yes
numberType	string	Name of the number type of the numbers in the range	yes
vanityType	integer	ID of the vanity type of the numbers in the range	no
supplier	string	External ID (externalId) of the supplier of the range	no
region	integer	ID of the geographical region to which this number range is assigned (only relevant for certain numberTypes). Can be null	yes

Example

{
    "countryCode": "+32",
    "start": 25400000,
    "end": 25409999,
    "numberType": "geo",
    "vanityType": 1,
    "supplier": "SUP-001",
    "region": 2
}

Response

Status codes

Parameter	Description
200	The number range has been correctly created
400	Error while creating the number range (e.g. overlapping range)
403	The API consumer doesn't have sufficient rights to perform this action
404	Group not found
500	Uncatched error on server side

Success

Body

The created range. See Get a number inventory range for the description of the fields.

Modify a number inventory range

Use this endpoint to modify an existing number range of the number inventory of a group. The boundaries and the country code of a range cannot be modified.

Request

Endpoint

PUT /api/v01/draas/{draas_instance}/groups/{uuid}/number_inventory/ranges/{id}

Authorization

Required role

groups.instance.number_inventory.ranges.instance.update

Path Parameters

Parameter	Type	Description
draas_instance	string	See common parameters
uuid	string	A system generated unique ID (UUID) identifying the group
id	integer	Index of the number range you want to modify

URL/Query parameters

N/A

Body

Parameter	Type	Description	Required?
numberType	string	Name of the number type of the numbers in the range	yes
vanityType	integer	ID of the vanity type of the numbers in the range. Use null to remove it	no
supplier	string	External ID (externalId) of the supplier of the range. Use null to remove it	no
region	integer	ID of the geographical region to which this number range is assigned. Use null to remove it	yes

Example

{
    "numberType": "geo",
    "vanityType": null,
    "supplier": "SUP-001",
    "region": 2
}

Response

Status codes

Parameter	Description
200	The number range has been correctly updated
400	Error while updating the number range
403	The API consumer doesn't have sufficient rights to perform this action
404	Number range/group not found
500	Uncatched error on server side

Success

Body

The updated range. See Get a number inventory range for the description of the fields.

Delete a number inventory range

Use this endpoint to remove a number range from the number inventory of a group.

Request

Endpoint

DELETE /api/v01/draas/{draas_instance}/groups/{uuid}/number_inventory/ranges/{id}

Authorization

Required role

groups.instance.number_inventory.ranges.instance.delete

Path Parameters

Parameter	Type	Description
draas_instance	string	See common parameters
uuid	string	A system generated unique ID (UUID) identifying the group
id	integer	Index of the number range you want to delete

URL/Query parameters

N/A

Body

N/A

Response

Status codes

Parameter	Description
204	The number range was deleted successfully
400	Error while deleting the number range (e.g. numbers of the range still in use)
403	The API consumer doesn't have sufficient rights to perform this action
404	Number range/group not found
500	Uncatched error on server side

Success

Body

N/A

Bulk create/update number ranges

Bulk API to handle number ranges.

This endpoint internally will call the create/update APIs. This means that, once completed, a notification will be sent through email (if enabled).

Request

Endpoint

PUT /api/v01/draas/{draas_instance}/groups/{uuid}/number_ranges/bulk

Authorization

Required role

groups.instance.number_ranges.bulk

Path Parameters

Parameter	Type	Description
draas_instance	string	See common parameters
uuid	string	A system generated unique ID (UUID) identifying the group

URL/Query parameters

N/A

Body

Parameter	Type	Description	Required
name	string	Bulk job descriptive name	yes
data	array	List of number ranges bulk data objects to be created/updated	yes

Example

{
  "bulks": [
    {
      "created_on": "2025-12-05T12:07:50.329334",
      "id": 64,
      "job_id": "1764936470",
      "kind": "number_ranges",
      "status": "success",
      "success_count": 1,
      "title": "Create number range",
      "total_count": 1,
      "updated_on": "2025-12-05T12:07:52.451631"
    }
  ],
  "page": 1,
  "pages": 1,
  "results": 1
}

Response

Status codes

Parameter	Description
200	All number ranges were successfully created/updated
400	None of number ranges were successfully created/updated
403	The API consumer doesn't have sufficient rights to perform this action
404	The path tenant / subscription doesn't exist
500	Uncaught error on server side

Body

Parameter	Type	Description	Conditional?
code	integer	Error code (see below for a complete error list)	no
reason	string	Message providing more context to the error that occurred	no

Success example

{
    "code": 3073,
    "reason": "Number Ranges bulk provisioning process is started"
}

Number ranges bulk data objects

Parameter	Type	Description	Conditional?
countryCode	string	The country code	no
start	integer	The number range start	no
end	integer	The number range end	no
numberType	string	The number type	no
supplier	string	The supplier name	no
vanityType	string	The vanity type	no

Get number ranges bulk jobs history

Retrieve the history of number ranges bulk jobs runs related to the given group.

Request

Endpoint

GET /api/v01/draas/{draas_instance}/groups/{uuid}/number_range/bulk_jobs

Authorization

Required role

groups.instance.number_range.bulk.jobs

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
subscription_id	integer	Index of a subscription to retrieve the bulk jobs history for

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	A case insensitive search on the bulk job title or kind (that contains the passed value)	no
filters	array	An object representing the conditions to filter out the results	no

Response

Status codes

Parameter	Description
200	The list of the bulk jobs has been retrieved
400	Error while processing the request
403	The API consumer doesn't have sufficient rights to perform this action
404	No bulk history found or the path tenant / subscription doesn't exist
500	Uncaught error on server side

Success

Body

Parameter	Type	Description	Conditional?
bulks	array	The list of the bulk jobs related to the given subscription_id	no
results	integer	Total number of bulk jobs retrieved	no
pages	integer	Total number of pages	no
page	integer	Current page	no
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 bulk jobs has to be continued	yes

Example

{
    "bulks": [
        {
            "created_on": "2025-12-05T12:07:50.329334",
            "id": 64,
            "job_id": "1764936470",
            "kind": "number_ranges",
            "status": "success",
            "success_count": 1,
            "title": "Create number range",
            "total_count": 1,
            "updated_on": "2025-12-05T12:07:52.451631"
        },
        {
            "created_on": "2025-12-05T12:07:30.415663",
            "id": 63,
            "job_id": "1764936450",
            "kind": "number_ranges",
            "status": "success",
            "success_count": 1,
            "title": "Create number range",
            "total_count": 1,
            "updated_on": "2025-12-05T12:07:31.652068"
        },
        {
            "created_on": "2025-12-05T12:03:49.107570",
            "id": 62,
            "job_id": "1764936228",
            "kind": "number_ranges",
            "status": "error",
            "success_count": 0,
            "title": "Create number range",
            "total_count": 1,
            "updated_on": "2025-12-05T12:03:50.285350"
        }
    ],
    "page": 1,
    "pages": 1,
    "results": 3
}

List number types

This endpoint returns all number types defined for the group. Number types are used to classify the numbers of the number inventory ranges.

Request

Endpoint

GET /api/v01/draas/{draas_instance}/groups/{uuid}/number_types

Authorization

Required role

groups.instance.number_types.list

Path Parameters

Parameter	Type	Description
draas_instance	string	See common parameters
uuid	string	A system generated unique ID (UUID) identifying the group

URL/Query parameters

N/A

Response

Status codes

Parameter	Description
200	The list of number types is returned
400	Error while processing the request
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?
numberTypes	array	List of number type objects	no

Number Type Object

Parameter	Type	Description	Conditional?
id	integer	Internal index of the number type	no
name	string	Name of the number type (e.g. geo, mobile, tollfree, ...). This is the value used as numberType in number ranges and numbers	no
description	string	Description optionally providing more information	no
createdOn	DateTime	Timestamp when this entry was added in the backend	no
updatedOn	DateTime	Timestamp when this entry was last updated in the backend	no

Example

{
    "numberTypes": [
        {
            "id": 1,
            "name": "geo",
            "description": "Geographical numbers",
            "createdOn": "2024-03-12T10:21:33",
            "updatedOn": "2024-03-12T10:21:33"
        },
        {
            "id": 2,
            "name": "tollfree",
            "description": "Toll free numbers",
            "createdOn": "2024-03-12T10:22:01",
            "updatedOn": "2024-03-12T10:22:01"
        }
    ]
}

Create a number type

Use this endpoint to create a new number type for the group.

Request

Endpoint

POST /api/v01/draas/{draas_instance}/groups/{uuid}/number_types

Authorization

Required role

groups.instance.number_types.create

Path Parameters

Parameter	Type	Description
draas_instance	string	See common parameters
uuid	string	A system generated unique ID (UUID) identifying the group

URL/Query parameters

N/A

Body

Parameter	Type	Description	Required?
name	string	Name of the number type (e.g. geo, mobile, tollfree, ...). This is the value used as numberType in number ranges and numbers	yes
description	string	Description optionally providing more information	no

Example

{
    "name": "geo",
    "description": "Geographical numbers"
}

Response

Status codes

Parameter	Description
200	The number type has been correctly created
400	Error while creating the number type (e.g. a number type with the same name already exists)
403	The API consumer doesn't have sufficient rights to perform this action
404	Group not found
500	Uncatched error on server side

Success

Body

The created number type object.

Example

{
    "id": 1,
    "name": "geo",
    "description": "Geographical numbers",
    "createdOn": "2024-03-12T10:21:33",
    "updatedOn": "2024-03-12T10:21:33"
}

Modify a number type

Use this endpoint to modify an existing number type of the group.

Request

Endpoint

PUT /api/v01/draas/{draas_instance}/groups/{uuid}/number_types/{id}

Authorization

Required role

groups.instance.number_types.instance.update

Path Parameters

Parameter	Type	Description
draas_instance	string	See common parameters
uuid	string	A system generated unique ID (UUID) identifying the group
id	integer	Index of the number type you want to modify

URL/Query parameters

N/A

Body

Parameter	Type	Description	Required?
name	string	Name of the number type (e.g. geo, mobile, tollfree, ...). This is the value used as numberType in number ranges and numbers	yes
description	string	Description optionally providing more information	no

Example

{
    "name": "geo",
    "description": "Geographical numbers"
}

Response

Status codes

Parameter	Description
200	The number type has been correctly updated
400	Error while updating the number type
403	The API consumer doesn't have sufficient rights to perform this action
404	Number type/group not found
500	Uncatched error on server side

Success

Body

The updated number type object.

Example

{
    "id": 1,
    "name": "geo",
    "description": "Geographical numbers",
    "createdOn": "2024-03-12T10:21:33",
    "updatedOn": "2024-03-12T10:21:33"
}

Delete a number type

Use this endpoint to delete a number type of the group.

Request

Endpoint

DELETE /api/v01/draas/{draas_instance}/groups/{uuid}/number_types/{id}

Authorization

Required role

groups.instance.number_types.instance.delete

Path Parameters

Parameter	Type	Description
draas_instance	string	See common parameters
uuid	string	A system generated unique ID (UUID) identifying the group
id	integer	Index of the number type you want to delete

URL/Query parameters

N/A

Body

N/A

Response

Status codes

Parameter	Description
204	The number type was deleted successfully
400	Error while deleting the number type (e.g. still used by a number range)
403	The API consumer doesn't have sufficient rights to perform this action
404	Number type/group not found
500	Uncatched error on server side

Success

Body

N/A

List vanity types

This endpoint returns all vanity types available at the given level. Vanity types are defined at group level and can be linked to number inventory ranges.

Request

Endpoint

GET /api/v01/draas/{draas_instance}/groups/{uuid}/vanity_typesGET /api/v01/draas/{draas_instance}/distributors/{uuid}/vanity_typesGET /api/v01/draas/{draas_instance}/resellers/{uuid}/vanity_typesGET /api/v01/draas/{draas_instance}/tenants/{uuid}/vanity_typesGET /api/v01/draas/{draas_instance}/tenants/{uuid}/subscriptions/{subscription_id}/vanity_types

Authorization

Required role

groups.instance.vanity_types.list distributors.instance.vanity_types.list resellers.instance.vanity_types.list tenants.instance.vanity_types.list tenants.instance.subscriptions.instance.vanity_types.list

Path Parameters

Parameter	Type	Description
draas_instance	string	See common parameters
uuid	string	A system generated unique ID (UUID) identifying the group, the distributor, the reseller or the tenant (to which the subscription belongs)
subscription_id	integer	Index of the subscription (only for the subscription endpoint)

URL/Query parameters

N/A

Response

Status codes

Parameter	Description
200	The list of vanity types is returned
400	Error while processing the request
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?
vanityTypes	array	List of vanity type objects	no

Vanity Type Object

Parameter	Type	Description	Conditional?
id	integer	Internal index of the vanity type	no
type	string	Name of the vanity type. Vanity numbers are numbers that have a very nice/special format (e.g. end with 0000)	no
description	string	Description optionally providing more information	no
createdOn	DateTime	Timestamp when this entry was added in the backend	no
updatedOn	DateTime	Timestamp when this entry was last updated in the backend	no

Example

{
    "vanityTypes": [
        {
            "id": 1,
            "type": "gold",
            "description": "Numbers ending with 000",
            "createdOn": "2024-03-12T10:25:10",
            "updatedOn": "2024-03-12T10:25:10"
        },
        {
            "id": 2,
            "type": "silver",
            "description": "Numbers ending with 00",
            "createdOn": "2024-03-12T10:25:42",
            "updatedOn": "2024-03-12T10:25:42"
        }
    ]
}

Create a vanity type

Use this endpoint to create a new vanity type for the group.

Request

Endpoint

POST /api/v01/draas/{draas_instance}/groups/{uuid}/vanity_types

Authorization

Required role

groups.instance.vanity_types.create

Path Parameters

Parameter	Type	Description
draas_instance	string	See common parameters
uuid	string	A system generated unique ID (UUID) identifying the group

URL/Query parameters

N/A

Body

Parameter	Type	Description	Required?
type	string	Name of the vanity type. Vanity numbers are numbers that have a very nice/special format (e.g. end with 0000)	yes
description	string	Description optionally providing more information	no

Example

{
    "type": "gold",
    "description": "Numbers ending with 000"
}

Response

Status codes

Parameter	Description
200	The vanity type has been correctly created
400	Error while creating the vanity type (e.g. a vanity type with the same type already exists)
403	The API consumer doesn't have sufficient rights to perform this action
404	Group not found
500	Uncatched error on server side

Success

Body

The created vanity type object.

Example

{
    "id": 1,
    "type": "gold",
    "description": "Numbers ending with 000",
    "createdOn": "2024-03-12T10:25:10",
    "updatedOn": "2024-03-12T10:25:10"
}

Modify a vanity type

Use this endpoint to modify an existing vanity type of the group.

Request

Endpoint

PUT /api/v01/draas/{draas_instance}/groups/{uuid}/vanity_types/{id}

Authorization

Required role

groups.instance.vanity_types.instance.update

Path Parameters

Parameter	Type	Description
draas_instance	string	See common parameters
uuid	string	A system generated unique ID (UUID) identifying the group
id	integer	Index of the vanity type you want to modify

URL/Query parameters

N/A

Body

Parameter	Type	Description	Required?
type	string	Name of the vanity type. Vanity numbers are numbers that have a very nice/special format (e.g. end with 0000)	yes
description	string	Description optionally providing more information	no

Example

{
    "type": "gold",
    "description": "Numbers ending with 000"
}

Response

Status codes

Parameter	Description
200	The vanity type has been correctly updated
400	Error while updating the vanity type
403	The API consumer doesn't have sufficient rights to perform this action
404	Vanity type/group not found
500	Uncatched error on server side

Success

Body

The updated vanity type object.

Example

{
    "id": 1,
    "type": "gold",
    "description": "Numbers ending with 000",
    "createdOn": "2024-03-12T10:25:10",
    "updatedOn": "2024-03-12T10:25:10"
}

Delete a vanity type

Use this endpoint to delete a vanity type of the group.

Request

Endpoint

DELETE /api/v01/draas/{draas_instance}/groups/{uuid}/vanity_types/{id}

Authorization

Required role

groups.instance.vanity_types.instance.delete

Path Parameters

Parameter	Type	Description
draas_instance	string	See common parameters
uuid	string	A system generated unique ID (UUID) identifying the group
id	integer	Index of the vanity type you want to delete

URL/Query parameters

N/A

Body

N/A

Response

Status codes

Parameter	Description
204	The vanity type was deleted successfully
400	Error while deleting the vanity type (e.g. still used by a number range)
403	The API consumer doesn't have sufficient rights to perform this action
404	Vanity type/group not found
500	Uncatched error on server side

Success

Body

N/A

List suppliers

This endpoint returns all number suppliers known for the group. Suppliers can be linked to number inventory ranges.

Request

Endpoint

GET /api/v01/draas/{draas_instance}/groups/{uuid}/suppliers

Authorization

Required role

groups.instance.suppliers.list

Path Parameters

Parameter	Type	Description
draas_instance	string	See common parameters
uuid	string	A system generated unique ID (UUID) identifying the group

URL/Query parameters

N/A

Response

Status codes

Parameter	Description
200	The list of suppliers is returned
400	Error while processing the request
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?
suppliers	array	List of supplier objects	no

Supplier Object

Parameter	Type	Description	Conditional?
id	integer	Internal index of the supplier	no
externalId	string	Reference of the supplier. This is the value used as supplier in number ranges	no
name	string	Name of the supplier	no
createdOn	DateTime	Timestamp when this entry was added in the backend	no
updatedOn	DateTime	Timestamp when this entry was last updated in the backend	no

Example

{
    "suppliers": [
        {
            "id": 1,
            "externalId": "SUP-001",
            "name": "Supplier A",
            "createdOn": "2024-03-12T10:30:00",
            "updatedOn": "2024-03-12T10:30:00"
        }
    ]
}

Lookup a number in the group

This endpoint searches a (partial) phone number across all tenants and subscriptions of a group, and returns where the matching numbers are assigned.

Request

Endpoint

GET /api/v01/draas/{draas_instance}/groups/{uuid}/lookups/numbers

Authorization

Required role

groups.instance.lookups.numbers.list

Path Parameters

Parameter	Type	Description
draas_instance	string	See common parameters
uuid	string	A system generated unique ID (UUID) identifying the group

URL/Query parameters

Parameter	Type	Description	Required?
search	string	The (partial) national subscriber number to look for	yes
filters	object	Used to perform advanced filtering on the query. See the Number Lookup Filters Object	no
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

Number Lookup Filters Object

Parameter	Type	Description	Required?
countryCode	string	Country code of the number to look for (e.g. +32)	no

Response

Status codes

Parameter	Description
200	Zero or more numbers found
400	Error while processing the request
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?
numbers	array	List of number objects matching the search. When assigned, the assignedTo property is a lookup assignedTo object	no
next	string	Token used for infinite scrolling, to be used in the next call to retrieve subsequent records. Only present if the list has to be continued	yes

Lookup 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
ref	string	Name of the MS Teams user or trunk to which the number is assigned	no
tenantUUID	string	UUID of the tenant owning the number	yes
tenantName	string	Name of the tenant owning the number	yes
subscriptionID	string	Index of the subscription owning the number	yes
subscriptionName	string	Name of the subscription owning the number	yes

Example

{
    "numbers": [
        {
            "assigned": true,
            "assignedTo": {
                "ref": "IDAL trunk",
                "to": 2,
                "type": "sip_trunk",
                "tenantUUID": "0b6e2b52-5a8f-4f5e-9c3a-2d6f1c1f4a11",
                "tenantName": "Acme",
                "subscriptionID": "12",
                "subscriptionName": "Acme SIP"
            },
            "countryCode": "+32",
            "fullNumber": "+3225409941",
            "isoCode": "BE",
            "nsn": "25409941",
            "numberType": "geo",
            "source": "number_inventory",
            "status": "active"
        }
    ]
}

Lookup a number in the distributor

This endpoint searches a (partial) phone number across all tenants and subscriptions under a distributor, and returns where the matching numbers are assigned.

Request

Endpoint

GET /api/v01/draas/{draas_instance}/distributors/{uuid}/lookups/numbers

Authorization

Required role

distributors.instance.lookups.numbers.list

Path Parameters

Parameter	Type	Description
draas_instance	string	See common parameters
uuid	string	A system generated unique ID (UUID) identifying the distributor within which to search

URL/Query parameters

Parameter	Type	Description	Required?
search	string	The (partial) national subscriber number to look for	yes
filters	object	Used to perform advanced filtering on the query. See the Number Lookup Filters Object	no
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

Number Lookup Filters Object

Parameter	Type	Description	Required?
countryCode	string	Country code of the number to look for (e.g. +32)	no

Response

Status codes

Parameter	Description
200	Zero or more numbers found
400	Error while processing the request
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?
numbers	array	List of number objects matching the search. When assigned, the assignedTo property is a lookup assignedTo object	no
next	string	Token used for infinite scrolling, to be used in the next call to retrieve subsequent records. Only present if the list has to be continued	yes

Lookup 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
ref	string	Name of the MS Teams user or trunk to which the number is assigned	no
tenantUUID	string	UUID of the tenant owning the number	yes
tenantName	string	Name of the tenant owning the number	yes
subscriptionID	string	Index of the subscription owning the number	yes
subscriptionName	string	Name of the subscription owning the number	yes

Example

{
    "numbers": [
        {
            "assigned": true,
            "assignedTo": {
                "ref": "IDAL trunk",
                "to": 2,
                "type": "sip_trunk",
                "tenantUUID": "0b6e2b52-5a8f-4f5e-9c3a-2d6f1c1f4a11",
                "tenantName": "Acme",
                "subscriptionID": "12",
                "subscriptionName": "Acme SIP"
            },
            "countryCode": "+32",
            "fullNumber": "+3225409941",
            "isoCode": "BE",
            "nsn": "25409941",
            "numberType": "geo",
            "source": "number_inventory",
            "status": "active"
        }
    ]
}

Lookup a number in the reseller

This endpoint searches a (partial) phone number across all tenants and subscriptions under a reseller, and returns where the matching numbers are assigned.

Request

Endpoint

GET /api/v01/draas/{draas_instance}/resellers/{uuid}/lookups/numbers

Authorization

Required role

resellers.instance.lookups.numbers.list

Path Parameters

Parameter	Type	Description
draas_instance	string	See common parameters
uuid	string	A system generated unique ID (UUID) identifying the reseller within which to search

URL/Query parameters

Parameter	Type	Description	Required?
search	string	The (partial) national subscriber number to look for	yes
filters	object	Used to perform advanced filtering on the query. See the Number Lookup Filters Object	no
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

Number Lookup Filters Object

Parameter	Type	Description	Required?
countryCode	string	Country code of the number to look for (e.g. +32)	no

Response

Status codes

Parameter	Description
200	Zero or more numbers found
400	Error while processing the request
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?
numbers	array	List of number objects matching the search. When assigned, the assignedTo property is a lookup assignedTo object	no
next	string	Token used for infinite scrolling, to be used in the next call to retrieve subsequent records. Only present if the list has to be continued	yes

Lookup 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
ref	string	Name of the MS Teams user or trunk to which the number is assigned	no
tenantUUID	string	UUID of the tenant owning the number	yes
tenantName	string	Name of the tenant owning the number	yes
subscriptionID	string	Index of the subscription owning the number	yes
subscriptionName	string	Name of the subscription owning the number	yes

Example

{
    "numbers": [
        {
            "assigned": true,
            "assignedTo": {
                "ref": "IDAL trunk",
                "to": 2,
                "type": "sip_trunk",
                "tenantUUID": "0b6e2b52-5a8f-4f5e-9c3a-2d6f1c1f4a11",
                "tenantName": "Acme",
                "subscriptionID": "12",
                "subscriptionName": "Acme SIP"
            },
            "countryCode": "+32",
            "fullNumber": "+3225409941",
            "isoCode": "BE",
            "nsn": "25409941",
            "numberType": "geo",
            "source": "number_inventory",
            "status": "active"
        }
    ]
}

Lookup a number in the tenant

This endpoint searches a (partial) phone number across all subscriptions of a tenant, and returns where the matching numbers are assigned.

Request

Endpoint

GET /api/v01/draas/{draas_instance}/tenants/{uuid}/lookups/numbers

Authorization

Required role

tenants.instance.lookups.numbers.list

Path Parameters

Parameter	Type	Description
draas_instance	string	See common parameters
uuid	string	A system generated unique ID (UUID) identifying the tenant within which to search

URL/Query parameters

Parameter	Type	Description	Required?
search	string	The (partial) national subscriber number to look for	yes
filters	object	Used to perform advanced filtering on the query. See the Number Lookup Filters Object	no
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

Number Lookup Filters Object

Parameter	Type	Description	Required?
countryCode	string	Country code of the number to look for (e.g. +32)	no

Response

Status codes

Parameter	Description
200	Zero or more numbers found
400	Error while processing the request
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?
numbers	array	List of number objects matching the search. When assigned, the assignedTo property is a lookup assignedTo object	no
next	string	Token used for infinite scrolling, to be used in the next call to retrieve subsequent records. Only present if the list has to be continued	yes

Lookup 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
ref	string	Name of the MS Teams user or trunk to which the number is assigned	no
subscriptionID	string	Index of the subscription owning the number	yes
subscriptionName	string	Name of the subscription owning the number	yes

Example

{
    "numbers": [
        {
            "assigned": true,
            "assignedTo": {
                "ref": "IDAL trunk",
                "to": 2,
                "type": "sip_trunk",
                "subscriptionID": "12",
                "subscriptionName": "Acme SIP"
            },
            "countryCode": "+32",
            "fullNumber": "+3225409941",
            "isoCode": "BE",
            "nsn": "25409941",
            "numberType": "geo",
            "source": "number_inventory",
            "status": "active"
        }
    ]
}

Lookup a number in the subscription

This endpoint searches a (partial) phone number within a subscription, and returns where the matching numbers are assigned.

Request

Endpoint

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

Authorization

Required role

tenants.instance.subscriptions.instance.lookups.numbers.list

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
subscription_id	integer	Index of the subscription within which to search

URL/Query parameters

Parameter	Type	Description	Required?
search	string	The (partial) national subscriber number to look for	yes
filters	object	Used to perform advanced filtering on the query. See the Number Lookup Filters Object	no
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

Number Lookup Filters Object

Parameter	Type	Description	Required?
countryCode	string	Country code of the number to look for (e.g. +32)	no

Response

Status codes

Parameter	Description
200	Zero or more numbers found
400	Error while processing the request
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?
numbers	array	List of number objects matching the search. When assigned, the assignedTo property is a lookup assignedTo object	no
next	string	Token used for infinite scrolling, to be used in the next call to retrieve subsequent records. Only present if the list has to be continued	yes

Lookup 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
ref	string	Name of the MS Teams user or trunk to which the number is assigned	no

Example

{
    "numbers": [
        {
            "assigned": true,
            "assignedTo": {
                "ref": "IDAL trunk",
                "to": 2,
                "type": "sip_trunk"
            },
            "countryCode": "+32",
            "fullNumber": "+3225409941",
            "isoCode": "BE",
            "nsn": "25409941",
            "numberType": "geo",
            "source": "number_inventory",
            "status": "active"
        }
    ]
}

Download the number lookup results of the group

Use this endpoint to download, as a JSON, CSV or XLSX file, the results of a number lookup in the group: the (partial) phone number searched across all tenants and subscriptions under a group.

Request

Endpoint

POST /api/v01/draas/{draas_instance}/groups/{uuid}/downloads/number_lookups

Path Parameters

Parameter	Type	Description
draas_instance	string	See common parameters
uuid	string	A system generated unique ID (UUID) identifying the group within which to search

URL/Query parameters

N/A

Body parameters

Parameter	Type	Description	Required?
format	string	The file format. Possible values are: csv, json, xlsx.	yes
filename	string	The file name (without extension). If not provided a default file name will be autogenerated	no
countryCode	string	Country code of the numbers to look for (e.g. +32)	yes
search	string	The (partial) national subscriber number to look for. If not provided, all the numbers of the country code are returned	no

Example

{
    "format": "csv",
    "filename": "number_lookups_group_adb26c5a-38bf-469c-87e2-20445fa1e64d_20250610",
    "countryCode": "+32",
    "search": "2540"
}

Response

The API directly returns the file in the requested format as a downloadable attachment.

Status codes

Parameter	Description
200	The file with the lookup results has been returned (the list of results may be empty)
400	Error while processing the request
403	The API consumer doesn't have sufficient rights to perform this action
500	Uncatched error on server side

Download the number lookup results of the distributor

Use this endpoint to download, as a JSON, CSV or XLSX file, the results of a number lookup in the distributor: the (partial) phone number searched across all tenants and subscriptions of a distributor.

Request

Endpoint

POST /api/v01/draas/{draas_instance}/distributors/{uuid}/downloads/number_lookups

Path Parameters

Parameter	Type	Description
draas_instance	string	See common parameters
uuid	string	A system generated unique ID (UUID) identifying the distributor within which to search

URL/Query parameters

N/A

Body parameters

Parameter	Type	Description	Required?
format	string	The file format. Possible values are: csv, json, xlsx.	yes
filename	string	The file name (without extension). If not provided a default file name will be autogenerated	no
countryCode	string	Country code of the numbers to look for (e.g. +32)	yes
search	string	The (partial) national subscriber number to look for. If not provided, all the numbers of the country code are returned	no

Example

{
    "format": "csv",
    "filename": "number_lookups_distributor_adb26c5a-38bf-469c-87e2-20445fa1e64d_20250610",
    "countryCode": "+32",
    "search": "2540"
}

Response

The API directly returns the file in the requested format as a downloadable attachment.

Status codes

Parameter	Description
200	The file with the lookup results has been returned (the list of results may be empty)
400	Error while processing the request
403	The API consumer doesn't have sufficient rights to perform this action
500	Uncatched error on server side

Download the number lookup results of the reseller

Use this endpoint to download, as a JSON, CSV or XLSX file, the results of a number lookup in the reseller: the (partial) phone number searched across all tenants and subscriptions of a reseller.

Request

Endpoint

POST /api/v01/draas/{draas_instance}/resellers/{uuid}/downloads/number_lookups

Path Parameters

Parameter	Type	Description
draas_instance	string	See common parameters
uuid	string	A system generated unique ID (UUID) identifying the reseller within which to search

URL/Query parameters

N/A

Body parameters

Parameter	Type	Description	Required?
format	string	The file format. Possible values are: csv, json, xlsx.	yes
filename	string	The file name (without extension). If not provided a default file name will be autogenerated	no
countryCode	string	Country code of the numbers to look for (e.g. +32)	yes
search	string	The (partial) national subscriber number to look for. If not provided, all the numbers of the country code are returned	no

Example

{
    "format": "csv",
    "filename": "number_lookups_reseller_adb26c5a-38bf-469c-87e2-20445fa1e64d_20250610",
    "countryCode": "+32",
    "search": "2540"
}

Response

The API directly returns the file in the requested format as a downloadable attachment.

Status codes

Parameter	Description
200	The file with the lookup results has been returned (the list of results may be empty)
400	Error while processing the request
403	The API consumer doesn't have sufficient rights to perform this action
500	Uncatched error on server side

Download the number lookup results of the tenant

Use this endpoint to download, as a JSON, CSV or XLSX file, the results of a number lookup in the tenant: the (partial) phone number searched across all subscriptions of a tenant.

Request

Endpoint

POST /api/v01/draas/{draas_instance}/tenants/{uuid}/downloads/number_lookups

Path Parameters

Parameter	Type	Description
draas_instance	string	See common parameters
uuid	string	A system generated unique ID (UUID) identifying the tenant within which to search

URL/Query parameters

N/A

Body parameters

Parameter	Type	Description	Required?
format	string	The file format. Possible values are: csv, json, xlsx.	yes
filename	string	The file name (without extension). If not provided a default file name will be autogenerated	no
countryCode	string	Country code of the numbers to look for (e.g. +32)	yes
search	string	The (partial) national subscriber number to look for. If not provided, all the numbers of the country code are returned	no

Example

{
    "format": "csv",
    "filename": "number_lookups_tenant_adb26c5a-38bf-469c-87e2-20445fa1e64d_20250610",
    "countryCode": "+32",
    "search": "2540"
}

Response

The API directly returns the file in the requested format as a downloadable attachment.

Status codes

Parameter	Description
200	The file with the lookup results has been returned (the list of results may be empty)
400	Error while processing the request
403	The API consumer doesn't have sufficient rights to perform this action
500	Uncatched error on server side

Download the number lookup results of the subscription

Use this endpoint to download, as a JSON, CSV or XLSX file, the results of a number lookup in the subscription: the (partial) phone number searched across a subscription.

Request

Endpoint

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

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
subscription_id	integer	Index of the subscription within which to search

URL/Query parameters

N/A

Body parameters

Parameter	Type	Description	Required?
format	string	The file format. Possible values are: csv, json, xlsx.	yes
filename	string	The file name (without extension). If not provided a default file name will be autogenerated	no
countryCode	string	Country code of the numbers to look for (e.g. +32)	yes
search	string	The (partial) national subscriber number to look for. If not provided, all the numbers of the country code are returned	no

Example

{
    "format": "csv",
    "filename": "number_lookups_tenant_adb26c5a-38bf-469c-87e2-20445fa1e64d_subscription_12_20250610",
    "countryCode": "+32",
    "search": "2540"
}

Response

The API directly returns the file in the requested format as a downloadable attachment.

Status codes

Parameter	Description
200	The file with the lookup results has been returned (the list of results may be empty)
400	Error while processing the request
403	The API consumer doesn't have sufficient rights to perform this action
500	Uncatched error on server side