Manage DIDs

These methods manage the DID pool: the incoming numbers and ranges you assign to accounts, IVR applications or sub-customers. They do the same as the DID Pool screen. A DID assigned to a sub-customer in the panel is a DID plus a delegation, so to hand a number to a reseller you call addDID and then addDIDDelegation.

DID structure

getDIDInfo and getDIDsList return these fields. addDID and updateDID take the writable ones as parameters.

Name	Type	Description
i_did	int	ID of the DID. Read-only
did	string	The DID number (DID), or the first number of a range (Range Start)
did_range_end	string	Last number of a range (Range End). Empty for a single number
incoming_did	string	Called number exactly as the provider sends it (Incoming DID/CLD of the DID’s authentication rule)
incoming_cli	string	Caller number the rule accepts (Incoming CLI). Empty accepts any caller
translation_rule	string	Rewrites the number before routing (DID Translation Rule). See number translation
cli_translation_rule	string	Rewrites the caller number delivered by the provider (CLI Translation Rule)
description	string	Free text
i_account	int	Account the DID is assigned to
i_ivr_application	int	IVR application the DID is assigned to
i_dids_charging_group	int	Selling charging group (Selling Charging Group). See getDIDChargingGroupInfo
i_vendor	int	Vendor whose calls are accepted for this DID (Vendor)
i_connection	int	Connection whose calls are accepted for this DID (Connection)
buying_i_dids_charging_group	int	Buying charging group that records the vendor’s cost (Buying Charging Group). Used only with i_vendor and i_connection
i_did_delegation	int	ID of the delegation of this DID. Read-only
delegated_to	int	ID of the sub-customer the DID is delegated to. Read-only, set with addDIDDelegation
parent_i_did_delegation	int	ID of the parent delegation when the DID was re-delegated; empty for the first delegation. Read-only

Assign a DID to one account or one IVR application, not both. To clear an assignment or a charging group, send the field as nil (None in Python).

Caution

A DID without i_vendor and i_connection accepts calls to its number from any source. Always set the provider’s vendor and connection.

addDID

Adds a DID or a range to the pool.

Parameters

Name	Type	Required	Description
did	string	yes	The DID number, or the first number of a range
incoming_did	string	yes	Called number as the provider sends it
did_range_end	string	no	Last number of the range. Makes the new entry a range
i_did_allocated_from	int	no	ID of the range the new number or sub-range is allocated from. Omit for a top-level entry
other fields		no	Any writable field of the DID structure

Returns

Name	Type	Description
result	string	OK
i_did	int	ID of the new DID

Example

request

call("addDID", {
    "did": "15555550123",
    "incoming_did": "15555550123",
    "i_account": 3092,
    "i_dids_charging_group": 7,
    "i_vendor": 12,
    "i_connection": 41,
    "description": "Main office line",
})

response

{"result": "OK", "i_did": 5521}

updateDID

Changes a DID. Identify it by i_did or did and send at least one field to change.

Parameters

Name	Type	Required	Description
i_did	int	one of	ID of the DID
did	string	one of	The DID number, used when i_did is not given
other fields		no	Any writable field of the DID structure. Send did_range_end as nil to turn a range into a single number

A sub-customer cannot change did or did_range_end of a DID delegated to it.

Returns

Name	Type	Description
result	string	OK
i_did	int	ID of the updated DID

Example

request

call("updateDID", {"i_did": 5521, "i_account": None, "i_ivr_application": 3})

response

{"result": "OK", "i_did": 5521}

deleteDID

Deletes a DID from the pool.

Parameters

Name	Type	Required	Description
i_did	int	one of	ID of the DID
did	string	one of	The DID number, used when i_did is not given

Returns

Name	Type	Description
result	string	OK

Example

request

call("deleteDID", {"i_did": 5521})

response

{"result": "OK"}

getDIDInfo

Returns one DID.

Parameters

Name	Type	Required	Description
i_did	int	one of	ID of the DID
did	string	one of	The DID number, used when i_did is not given

Returns

Name	Type	Description
result	string	OK
DID fields		The fields of the DID structure, at the top level of the response

Example

request

call("getDIDInfo", {"did": "15555550123"})

response

{
    "result": "OK",
    "i_did": 5521,
    "did": "15555550123",
    "incoming_did": "15555550123",
    "translation_rule": "",
    "cli_translation_rule": "",
    "description": "Main office line",
    "i_account": 3092,
    "i_ivr_application": None,
    "i_dids_charging_group": 7,
    "i_vendor": 12,
    "i_connection": 41,
    "buying_i_dids_charging_group": None,
    "i_did_delegation": None,
    "delegated_to": None,
    "parent_i_did_delegation": None,
}

getDIDsList

Returns the DIDs that match the filters. Without filters it returns the whole pool.

Parameters

Name	Type	Required	Description
did	string	no	Pattern for the DID number
incoming_did	string	no	Pattern for the incoming DID
delegated_to	int	no	Only DIDs delegated to this sub-customer
i_account	int	no	Only DIDs assigned to this account
i_ivr_application	int	no	Only DIDs assigned to this IVR application
not_assigned	boolean	no	True: only DIDs not assigned to any account, customer or IVR application
offset	int	no	Number of rows to skip
limit	int	no	Maximum number of rows to return

Returns

Name	Type	Description
result	string	OK
dids	array	One struct per DID with the fields of the DID structure

Example

request

call("getDIDsList", {"not_assigned": True, "limit": 50})

response

{
    "result": "OK",
    "dids": [
        {"i_did": 5522, "did": "15555550124", "incoming_did": "15555550124", "i_account": None},
        # … one struct per DID
    ],
}

getDIDChargingGroupInfo

Returns one DID charging group, the object behind Selling Charging Group and Buying Charging Group. See charging groups.

Parameters

Name	Type	Required	Description
i_dids_charging_group	int	yes	ID of the charging group

Returns

Name	Type	Description
result	string	OK
i_dids_charging_group	int	ID of the charging group
i_customer	int	Owner of the group
name	string	Name of the group
description	string	Free text
type	int	1 selling, 2 buying
iso_4217	string	Currency, for example USD
price	double	Monthly fee
setup_fee	double	One-off setup fee
connect_fee	double	Charge per connected call
free_seconds	int	Free seconds at the start of a call
grace_period	int	Calls up to this length in seconds are not charged
interval_1, interval_n	int	First and next billing intervals in seconds
price_1, price_n	double	Price per minute for the first and next intervals
post_call_surcharge	double	Surcharge after the call, as a fraction: 0.05 is 5%

Example

request

call("getDIDChargingGroupInfo", {"i_dids_charging_group": 7})

response

{
    "result": "OK",
    "i_dids_charging_group": 7,
    "i_customer": 1,
    "name": "US local DID",
    "description": "",
    "type": 1,
    "iso_4217": "USD",
    "price": 2.0,
    "setup_fee": 1.0,
    "connect_fee": 0.0,
    "free_seconds": 0,
    "grace_period": 0,
    "interval_1": 60,
    "interval_n": 60,
    "price_1": 0.0,
    "price_n": 0.0,
    "post_call_surcharge": 0.0,
}

addDIDDelegation

Delegates a DID to a sub-customer. The sub-customer sees the number in its own DID Pool and can assign it to its accounts or delegate it further to its own sub-customer; the chain has no length limit.

Parameters

Name	Type	Required	Description
i_did	int	yes	ID of the DID
delegated_to	int	yes	ID of the sub-customer
parent_i_did_delegation	int	yes	ID of the delegation you received the DID through; nil when you delegate your own DID
i_dids_charging_group	int	no	Selling charging group charged to the sub-customer
description	string	no	Free text

Returns

Name	Type	Description
result	string	OK
i_did_delegation	int	ID of the new delegation

Example

request

call("addDIDDelegation", {
    "i_did": 5521,
    "delegated_to": 27,
    "parent_i_did_delegation": None,
    "i_dids_charging_group": 7,
})

response

{"result": "OK", "i_did_delegation": 840}

updateDIDDelegation

Changes a delegation: the sub-customer, the charging group or the description.

Parameters

Name	Type	Required	Description
i_did_delegation	int	yes	ID of the delegation
delegated_to	int	no	ID of the new sub-customer
i_dids_charging_group	int	no	Selling charging group
description	string	no	Free text

Returns

Name	Type	Description
result	string	OK
i_did_delegation	int	ID of the delegation

Example

request

call("updateDIDDelegation", {"i_did_delegation": 840, "description": "Reseller trial"})

response

{"result": "OK", "i_did_delegation": 840}

deleteDIDDelegation

Takes a delegated DID back from the sub-customer.

Parameters

Name	Type	Required	Description
i_did_delegation	int	yes	ID of the delegation

Returns

Name	Type	Description
result	string	OK

Example

request

call("deleteDIDDelegation", {"i_did_delegation": 840})

response

{"result": "OK"}

Related

• DID pool: the same fields in the panel
• DID ranges management
• Charging groups
• Create a DID and assign it to an account or IVR application
• Account incoming routing