Browse DIDs
Action Name: DidBrowseUpstreamProvidersAction
Description: Given a set of parameters, return the result of a search for available DIDs that match the parameters.
Required Parameters
| Parameter Name | Description | Type | Required |
Quantity |
The amount of DIDs being requested from the Upstream Providers |
|
✓ |
AccountId |
Trunking.io account id | number |
✓ |
Optional Parameters
| Parameter Name | Description | Type | Required |
Npa |
NPA (Numbering Plan Area). An Area Code. | number |
✕ |
Nxx |
NXX (Exchange Code) – The Central Office Code | number |
✕ |
RateCenter |
A geographical area used to determine call billing and number assignment | string |
✕ |
TnMask |
Ten-digit telephone number; Accepts 0-9, x, X, or space. x, X, or space are interpreted as any single digit. (Ex: 312xxx1x2x) | See upstream |
✕ |
TnWildCard |
Telephone number. Accepts 0-9, Aa-Zz, , or ? (e.g. "Hello" or "312?Hi7") | See upstream |
✕ |
Sequential |
Boolean value that indicates if the search should attempt to obtain sequential numbers or not | true || false |
✕ |
Quantity |
The amount of DIDs being requested from the Upstream Providers |
|
✓ |
AccountId |
Trunking.io account id | number |
✓ |
Note: TnMask, TnWildCard and Sequential are used only in the case of Toll Free searches.
Responses
Valid response
{
"Response": {
"Context": {
"Action": {
"IsCompleted": "true"
},
"Request": {
"IsValid": "true",
"DateTime": "2025-03-31T19:39:17+00:00",
"Duration": "433",
"Parameters": {
"Parameter": [
{
"Name": "Action",
"Value": "DidBrowseUpstreamProviders"
},
{
"Name": "Output",
"Value": "json"
},
{
"Name": "SessionId",
"Value": "J2yrzxH4iMNeiRbXsACAbkyXrwlefWaP"
},
{
"Name": "Npa",
"Value": "601"
},
{
"Name": "Nxx",
"Value": "490"
},
{
"Name": "Quantity",
"Value": "2"
},
{
"Name": "AccountId",
"Value": "4962"
}
]
}
},
"Session": {
"IsEstablished": "true",
"SessionId": "J2yrzxH4iMNeiRbXsACAbkyXrwlefWaP",
"UserId": "798176",
"Roles": {
"Role": {
"Name": "Super User"
}
}
}
},
"Result": {
"DidBrowseUpstreamProviders": {
"Dids": {
"Did": [
{
"TelephoneNumber": "16014907989",
"RateCenter": "MERIDIAN",
"State": "MS"
},
{
"TelephoneNumber": "16014907990",
"RateCenter": "MERIDIAN",
"State": "MS"
}
]
}
}
}
}
}
Invalid Parameters
{
"Response": {
"Context": {
"Action": {
"IsCompleted": "false"
},
"Request": {
"IsValid": "false",
"DateTime": "2025-03-31T19:51:44+00:00",
"Duration": "16",
"Parameters": {
"Parameter": [
{
"Name": "Action",
"Value": "DidBrowseUpstreamProviders"
},
{
"Name": "Output",
"Value": "json"
},
{
"Name": "SessionId",
"Value": "J2yrzxH4iMNeiRbXsACAbkyXrwlefWaP"
},
{
"Name": "Npa",
"Value": "601"
},
{
"Name": "Nxx",
"Value": "490"
},
{
"Name": "Quantity",
"Value": "2"
},
{
"Name": "AccountId",
"Value": "4962"
},
{
"Name": "TnMask",
"Value": "A2"
}
]
},
"Errors": {
"Error": {
"Parameter": "Npa",
"Code": "DIDSearch.InvalidParamters",
"Message": "Invalid Search Parameters. "
}
}
},
"Session": {
"IsEstablished": "true",
"SessionId": "J2yrzxH4iMNeiRbXsACAbkyXrwlefWaP",
"UserId": "798176",
"Roles": {
"Role": {
"Name": "Super User"
}
}
}
}
}
}
Rejected by Upstream Provider
{
"Response": {
"Context": {
"Action": {
"IsCompleted": "false",
"Errors": {
"Error": {
"Code": "UserRequestDid.ServiceError",
"Message": "tnMask must be in character 'x' or number from 0 to 9."
}
}
},
"Request": {
"IsValid": "true",
"DateTime": "2025-03-31T19:54:25+00:00",
"Duration": "467",
"Parameters": {
"Parameter": [
{
"Name": "Action",
"Value": "DidBrowseUpstreamProviders"
},
{
"Name": "Output",
"Value": "json"
},
{
"Name": "SessionId",
"Value": "J2yrzxH4iMNeiRbXsACAbkyXrwlefWaP"
},
{
"Name": "Quantity",
"Value": "2"
},
{
"Name": "AccountId",
"Value": "4962"
},
{
"Name": "TnMask",
"Value": "A2"
},
{
"Name": "Sequential",
"Value": "false"
}
]
}
},
"Session": {
"IsEstablished": "true",
"SessionId": "J2yrzxH4iMNeiRbXsACAbkyXrwlefWaP",
"UserId": "798176",
"Roles": {
"Role": {
"Name": "Super User"
}
}
}
}
}
}
Purchase DIDs
Action Name: DidRequestPurchaseFromUpstreamProviderAction
Description: Using the phone numbers returned from DidBrowseUpstreamProvidersAction, attempt to purchase the specified numbers. If not all numbers can be purchased, the action will return a partial fulfillment response. Fulfilled DIDs are assigned to the Account Admin.
Parameters
| Parameter Name | Description | Validations | Required |
|---|---|---|---|
AccountId |
Trunking.io account id | number |
✓ |
RequestedDids |
An array of DIDs obtained from DidBrowseUpstreamProvidersAction
|
array |
✓ |
IsTollFree |
Indicates if the specified numbers are Toll Free | true || false |
✓ |
Responses
All Requested Numbers fulfilled
{
"Response": {
"Context": {
"Action": {
"IsCompleted": "true"
},
"Request": {
"IsValid": "true",
"DateTime": "2025-03-31T20:25:37+00:00",
"Duration": "1347",
"Parameters": {
"Parameter": [
{
"Name": "Action",
"Value": "DidRequestPurchaseFromUpstreamProvider"
},
{
"Name": "Output",
"Value": "json"
},
{
"Name": "SessionId",
"Value": "J2yrzxH4iMNeiRbXsACAbkyXrwlefWaP"
},
{
"Name": "IsTollFree",
"Value": "false"
},
{
"Name": "AccountId",
"Value": "4962"
},
{
"Name": "RequestedDids",
"Array": {
"Elements": {
"Element": [
{
"Key": "0",
"Value": "16014907989"
},
{
"Key": "1",
"Value": "16014907990"
}
]
}
}
}
]
}
},
"Session": {
"IsEstablished": "true",
"SessionId": "J2yrzxH4iMNeiRbXsACAbkyXrwlefWaP",
"UserId": "798176",
"Roles": {
"Role": {
"Name": "Super User"
}
}
}
},
"Result": {
"DidRequestPurchaseFromUpstreamProvider": {
"Requested": "2",
"Filled": "2",
"Dids": {
"Did": [
{
"DidId": "50",
"UserId": "9548",
"OrganizationId": {},
"AccountId": "4962",
"UserStatus": "unknown",
"Number": "16014907989",
"Protocol": "sip",
"Timeout": "120",
"FailoverEnabled": "false",
"FailoverProtocol": "pstn",
"FailoverLocation": {},
"VoicemailboxId": {},
"CallerIdNumberRequired": "false",
"SimultaneousCallLimit": "25",
"Modified": "2025-03-31T20:25:37+00:00",
"Created": "2025-03-31T20:25:37+00:00",
"Note": {},
"Name": {},
"RateCenter": "null",
"InboundCallRate": {},
"CnamDipEnable": "1",
"FailoverDidId": {},
"UserNumberAlias": {
"AliasUsername": "16014907989",
"AliasDomain": "sip.jnctn.net",
"AddressUsername": {},
"AddressDomain": "sip.jnctn.net",
"AddressId": "3207202",
"AddressType": "none",
"AddressName": {},
"AppAddressType": {},
"UserId": "9548",
"Number": "16014907989",
"DefaultAddressId": "0"
}
},
{
"DidId": "51",
"UserId": "9548",
"OrganizationId": {},
"AccountId": "4962",
"UserStatus": "unknown",
"Number": "16014907990",
"Protocol": "sip",
"Timeout": "120",
"FailoverEnabled": "false",
"FailoverProtocol": "pstn",
"FailoverLocation": {},
"VoicemailboxId": {},
"CallerIdNumberRequired": "false",
"SimultaneousCallLimit": "25",
"Modified": "2025-03-31T20:25:37+00:00",
"Created": "2025-03-31T20:25:37+00:00",
"Note": {},
"Name": {},
"RateCenter": "null",
"InboundCallRate": {},
"CnamDipEnable": "1",
"FailoverDidId": {},
"UserNumberAlias": {
"AliasUsername": "16014907990",
"AliasDomain": "sip.jnctn.net",
"AddressUsername": {},
"AddressDomain": "sip.jnctn.net",
"AddressId": "3207202",
"AddressType": "none",
"AddressName": {},
"AppAddressType": {},
"UserId": "9548",
"Number": "16014907990",
"DefaultAddressId": "0"
}
}
]
}
}
}
}
}
Request partially fulfilled
{
"Response": {
"Context": {
"Action": {
"IsCompleted": "true"
},
"Request": {
"IsValid": "true",
"DateTime": "2025-03-31T20:27:03+00:00",
"Duration": "1496",
"Parameters": {
"Parameter": [
{
"Name": "Action",
"Value": "DidRequestPurchaseFromUpstreamProvider"
},
{
"Name": "Output",
"Value": "json"
},
{
"Name": "SessionId",
"Value": "J2yrzxH4iMNeiRbXsACAbkyXrwlefWaP"
},
{
"Name": "IsTollFree",
"Value": "false"
},
{
"Name": "AccountId",
"Value": "4962"
},
{
"Name": "RequestedDids",
"Array": {
"Elements": {
"Element": [
{
"Key": "0",
"Value": "16014907989"
},
{
"Key": "1",
"Value": "16014907990"
},
{
"Key": "2",
"Value": "16014907991"
}
]
}
}
}
]
}
},
"Session": {
"IsEstablished": "true",
"SessionId": "J2yrzxH4iMNeiRbXsACAbkyXrwlefWaP",
"UserId": "798176",
"Roles": {
"Role": {
"Name": "Super User"
}
}
}
},
"Result": {
"DidRequestPurchaseFromUpstreamProvider": {
"Requested": "3",
"Filled": "1",
"Dids": {
"Did": {
"DidId": "52",
"UserId": "9548",
"OrganizationId": {},
"AccountId": "4962",
"UserStatus": "unknown",
"Number": "16014907991",
"Protocol": "sip",
"Timeout": "120",
"FailoverEnabled": "false",
"FailoverProtocol": "pstn",
"FailoverLocation": {},
"VoicemailboxId": {},
"CallerIdNumberRequired": "false",
"SimultaneousCallLimit": "25",
"Modified": "2025-03-31T20:27:03+00:00",
"Created": "2025-03-31T20:27:03+00:00",
"Note": {},
"Name": {},
"RateCenter": "null",
"InboundCallRate": {},
"CnamDipEnable": "1",
"FailoverDidId": {},
"UserNumberAlias": {
"AliasUsername": "16014907991",
"AliasDomain": "sip.jnctn.net",
"AddressUsername": {},
"AddressDomain": "sip.jnctn.net",
"AddressId": "3207202",
"AddressType": "none",
"AddressName": {},
"AppAddressType": {},
"UserId": "9548",
"Number": "16014907991",
"DefaultAddressId": "0"
}
}
}
}
}
}
}
Invalid Parameters
{
"Response": {
"Context": {
"Action": {
"IsCompleted": "false"
},
"Request": {
"IsValid": "false",
"DateTime": "2025-03-31T20:29:31+00:00",
"Duration": "12",
"Parameters": {
"Parameter": [
{
"Name": "Action",
"Value": "DidRequestPurchaseFromUpstreamProvider"
},
{
"Name": "Output",
"Value": "json"
},
{
"Name": "SessionId",
"Value": "J2yrzxH4iMNeiRbXsACAbkyXrwlefWaP"
},
{
"Name": "IsTollFree",
"Value": "false"
},
{
"Name": "AccountId",
"Value": "4962a"
},
{
"Name": "RequestedDids",
"Array": {
"Elements": {
"Element": {
"Key": "0",
"Value": "16014907990"
}
}
}
}
]
},
"Errors": {
"Error": {
"Parameter": "AccountId",
"Code": "AccountId.Invalid",
"Message": "The account id is invalid."
}
}
},
"Session": {
"IsEstablished": "true",
"SessionId": "J2yrzxH4iMNeiRbXsACAbkyXrwlefWaP",
"UserId": "798176",
"Roles": {
"Role": {
"Name": "Super User"
}
}
}
}
}
}
Comments
0 comments
Article is closed for comments.