Phone Number (DID)

NPA NXX Browse

Returns a list of available phone numbers (DIDs). Use the DidId value along with Action DidRequest to purchase the DID, then assign the DID to a user using the DidEdit Action.

Authentication & Authorization

Not required.

Request Parameters

Required ParametersDescription
Action “NpaNxxBrowse”

Result Element Schema

NpaNxxBrowse.rnc:

NpaNxxBrowse.rng, NpaNxx.rng, PostalCode.rng

Sample Request

cURL
1
2
3
curl -X POST \
--data 'Action=NpaNxxBrowse' \
https://api.onsip.com/api
JavaScript
1
2
3
4
5
6
7
8
9
var data = new FormData();
data.append('Action', 'NpaNxxBrowse');

var xhr = new XMLHttpRequest();
xhr.open('POST', 'https://api.onsip.com/api', true);
xhr.onload = function () {
  console.log(this.responseText);
}
xhr.send(data);

Sample Response

(omitted for brevity)

DID Request

Use NpaNxxBrowse to find phone numbers, then purchase the number using this UserRequestDid Action. Once purchased, use DID Edit to associate this phone number / DID to a user’s SIP address.

Note: Before assigning the DID to an OnSIP SIP address, the DID will appear to be a PSTN Gateway DID. Assigning the DID to an OnSIP SIP address will automatically update this to OnSIP.

Authentication & Authorization

AuthenticationAuthorization
Authenticated Session Account Admin

Request Parameters

Required ParametersDescription
Action “DidRequest”
SessionId Authenticated Session identifier.
UserId A positive integer which references a unique User.
Protocol The protocol by which calls will be delivered to the user; ‘sip’ or ‘iax’
NpaNxx[] An array mapping an NPA/NXX to a quantity. For example, NpaNxx[212789]=2 would indicate a request for 2 numbers from Area Code 212 with an NXX of 789.

Result Element Schema

DidRequest.rnc:

DidRequest.rng, Did.rng, User.rng

Sample Request

cURL
1
2
3
curl -X POST --data \
'Action=DidRequest&SessionId=0hg2c34qls6raj9misu2fukr00&UserId=123456&Protocol=sip&NpaNxx[212789]=1' \
https://api.onsip.com/api
JavaScript
1
2
3
4
5
6
7
8
9
10
11
12
13
var data = new FormData();
data.append('Action', 'DidRequest');
data.append('SessionId', '0hg2c34qls6raj9misu2fukr00');
data.append('UserId', '123456');
data.append('Protocol', 'sip');
data.append('NpaNxx[212789]', '1');

var xhr = new XMLHttpRequest();
xhr.open('POST', 'https://api.onsip.com/api', true);
xhr.onload = function () {
  console.log(this.responseText);
}
xhr.send(data);

Sample Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
<?xml version="1.0" encoding="UTF-8"?>
<Response xmlns="http://www.jnctn.net/ns/rest/2006-01">
  <Context>
    <Action>
      <IsCompleted>true</IsCompleted>
    </Action>
    <Request>
      <IsValid>true</IsValid>
      <DateTime>2014-04-21T17:00:04+00:00</DateTime>
      <Duration>1407</Duration>
      <Parameters>
        <Parameter>
          <Name>Action</Name>
          <Value>DidRequest</Value>
        </Parameter>
        <Parameter>
          <Name>SessionId</Name>
          <Value>0hg2c34qls6raj9misu2fukr00</Value>
        </Parameter>
        <Parameter>
          <Name>UserId</Name>
          <Value>123456</Value>
        </Parameter>
        <Parameter>
          <Name>Protocol</Name>
          <Value>sip</Value>
        </Parameter>
        <Parameter>
          <Name>NpaNxx</Name>
          <Array>
            <Elements>
              <Element>
                <Key>212789</Key>
                <Value>1</Value>
              </Element>
            </Elements>
          </Array>
        </Parameter>
      </Parameters>
    </Request>
    <Session>
      <IsEstablished>true</IsEstablished>
      <SessionId>0hg2c34qls6raj9misu2fukr00</SessionId>
      <UserId>123456</UserId>
      <Roles>
        <Role>
          <Name>Account Admin</Name>
        </Role>
      </Roles>
    </Session>
  </Context>
  <Result>
    <DidRequest>
      <Requested>1</Requested>
      <Filled>0</Filled>
      <Dids/>
      <User>
        <UserId>123456</UserId>
        <OrganizationId>98765</OrganizationId>
        <AccountId>13579</AccountId>
        <Flags>0</Flags>
        <Status>enabled</Status>
        <Domain>example.onsip.com</Domain>
        <Username>test</Username>
        <Password>zf94QsBp9XcQ7qos</Password>
        <AuthUsername>test</AuthUsername>
        <Modified>2014-01-08T20:40:14+00:00</Modified>
        <Created>2013-09-24T15:39:04+00:00</Created>
        <Ack911>1970-01-01T00:00:00+00:00</Ack911>
        <SurveyCompleted>2013-09-24T15:41:53+00:00</SurveyCompleted>
        <AckTrunkingTerms>1970-01-01T00:00:00+00:00</AckTrunkingTerms>
        <AckTrunkingE911>1970-01-01T00:00:00+00:00</AckTrunkingE911>
        <AckHostedTerms>2014-01-08T20:40:14+00:00</AckHostedTerms>
        <AckHostedE911>2013-09-24T15:41:42+00:00</AckHostedE911>
        <ExtendedDialing>false</ExtendedDialing>
        <PSTNForwarding>false</PSTNForwarding>
        <E911Provisioning>false</E911Provisioning>
        <PSTNTrunking>false</PSTNTrunking>
        <FreePSTNTrunking>false</FreePSTNTrunking>
        <BusyLampField>false</BusyLampField>
        <Contact>
          <Name>Alice Applegate</Name>
          <Organization>OnSIP Test</Organization>
          <Address>55 Broad St</Address>
          <City>New York</City>
          <State>NY</State>
          <Zipcode>10004</Zipcode>
          <Country>United States of America</Country>
          <CountryId>207</CountryId>
          <Phone>1-202-456-7890</Phone>
          <Email>alice@example.com</Email>
          <Modified>2013-09-24T15:38:44+00:00</Modified>
        </Contact>
        <Roles>
          <Role>
            <Name>Account Admin</Name>
          </Role>
        </Roles>
      </User>
    </DidRequest>
  </Result>
</Response>

DID Browse

Show DIDs associated with a group.

Authentication & Authorization

AuthenticationAuthorization
Authenticated Session Account Admin

Request Parameters

Required ParametersDescription
Action “DidBrowse”
SessionId Authenticated Session identifier.
One and Only One of the Following Parameters Description
AccountId A positive integer which references a unique Account.
OrganizationId A positive integer which references a unique Organization.
UserId A positive integer which references a unique User.

 

Result Element Schema

DidBrowse.rnc:

DidBrowse.rng, Did.rng

Sample Request

cURL
1
2
3
curl -X POST \
--data 'Action=DidBrowse&SessionId=c70d58iib3rc6etn4usj2kvlk5&OrganizationId=123456' \
https://api.onsip.com/api
Javascript
1
2
3
4
5
6
7
8
9
10
11
var data = new FormData();
data.append('Action', 'DidBrowse');
data.append('SessionId', 'c70d58iib3rc6etn4usj2kvlk5');
data.append('OrganizationId', '123456');

var xhr = new XMLHttpRequest();
xhr.open('POST', 'https://api.onsip.com/api', true);
xhr.onload = function () {
  console.log(this.responseText);
}
xhr.send(data);

Sample Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
<Response xmlns="http://www.jnctn.net/ns/rest/2006-01">
  <Context>
    <Action>
      <IsCompleted>true</IsCompleted>
    </Action>
    <Request>
      <IsValid>true</IsValid>
      <DateTime>2014-08-20T17:25:17+00:00</DateTime>
      <Duration>57</Duration>
      <Parameters>
        <Parameter>
          <Name>Action</Name>
          <Value>DidBrowse</Value>
        </Parameter>
        <Parameter>
          <Name>SessionId</Name>
          <Value>dhp0npe39ufqep6at5v1u3elp2</Value>
        </Parameter>
        <Parameter>
          <Name>OrganizationId</Name>
          <Value>25325</Value>
        </Parameter>
        <Parameter>
          <Name>OrderBy</Name>
          <Value>Number</Value>
        </Parameter>
        <Parameter>
          <Name>Limit</Name>
          <Value>20</Value>
        </Parameter>
        <Parameter>
          <Name>Offset</Name>
          <Value>0</Value>
        </Parameter>
        <Parameter>
          <Name>CalcFound</Name>
          <Value>true</Value>
        </Parameter>
      </Parameters>
    </Request>
    <Session>
      <IsEstablished>true</IsEstablished>
      <SessionId>dhp0npe39ufqep6at5v1u3elp2</SessionId>
      <UserId>211025</UserId>
      <Roles>
        <Role>
          <Name>Account Admin</Name>
        </Role>
      </Roles>
    </Session>
  </Context>
  <Result>
    <DidBrowse>
      <Dids Limit="20" Offset="0" Found="1">
        <Did>
          <DidId>114599</DidId>
          <UserId>155977</UserId>
          <OrganizationId>25325</OrganizationId>
          <AccountId>22835</AccountId>
          <UserStatus>enabled</UserStatus>
          <Number>15168304616</Number>
          <Protocol>sip</Protocol>
          <Timeout>120</Timeout>
          <FailoverEnabled>false</FailoverEnabled>
          <FailoverProtocol>pstn</FailoverProtocol>
          <FailoverLocation/>
          <VoicemailboxId/>
          <CallerIdNumberRequired>false</CallerIdNumberRequired>
          <SimultaniousCallLimit>25</SimultaniousCallLimit>
          <Modified>2014-08-20T17:12:18+00:00</Modified>
          <Created>2014-08-20T17:12:18+00:00</Created>
          <Note/>
          <Name/>
          <UserNumberAlias>
            <AliasUsername>15168304616</AliasUsername>
            <AliasDomain>jnctn.net</AliasDomain>
            <AddressUsername>eric.green</AddressUsername>
            <AddressDomain>egreen.onsip.com</AddressDomain>
            <AddressType>user</AddressType>
            <AddressName>Eric Green</AddressName>
            <AddressId>496770</AddressId>
            <UserId>155977</UserId>
            <Number>15168304616</Number>
          </UserNumberAlias>
        </Did>
      </Dids>
      <SearchMap>
        <SearchFields>
          <SearchField>
            <Display>Number</Display>
            <Name>Number</Name>
            <Type>string</Type>
          </SearchField>
          <SearchField>
            <Display>User Id</Display>
            <Name>UserId</Name>
            <Type>int</Type>
          </SearchField>
          <SearchField>
            <Display>Organization Id</Display>
            <Name>OrganizationId</Name>
            <Type>int</Type>
          </SearchField>
          <SearchField>
            <Display>Account Id</Display>
            <Name>AccountId</Name>
            <Type>int</Type>
          </SearchField>
        </SearchFields>
        <SearchCompOps>
          <SearchCompOp>
            <Desc>Contains</Desc>
            <SupportedTypes>
              <Type>string</Type>
              <Type>float</Type>
              <Type>int</Type>
            </SupportedTypes>
          </SearchCompOp>
          <SearchCompOp>
            <Desc>Equals</Desc>
            <SupportedTypes>
              <Type>float</Type>
              <Type>int</Type>
              <Type>string</Type>
            </SupportedTypes>
          </SearchCompOp>
          <SearchCompOp>
            <Desc>Begins With</Desc>
            <SupportedTypes>
              <Type>string</Type>
            </SupportedTypes>
          </SearchCompOp>
          <SearchCompOp>
            <Desc>Ends With</Desc>
            <SupportedTypes>
              <Type>string</Type>
            </SupportedTypes>
          </SearchCompOp>
          <SearchCompOp>
            <Desc>Greater Than</Desc>
            <SupportedTypes>
              <Type>float</Type>
              <Type>int</Type>
            </SupportedTypes>
          </SearchCompOp>
          <SearchCompOp>
            <Desc>Less Than</Desc>
            <SupportedTypes>
              <Type>float</Type>
              <Type>int</Type>
            </SupportedTypes>
          </SearchCompOp>
        </SearchCompOps>
      </SearchMap>
    </DidBrowse>
  </Result>
</Response>

DID Edit

Associate a phone number (DID) to a SIP address and have callers dial you through the PSTN. Standard Rates will apply. This would be the last step in a series of 3 API calls to setup a phone number and be reachable by way of mobile phones and landlines.

Authentication & Authorization

AuthenticationAuthorization
Authenticated Session Account Admin

Request Parameters

Required ParametersDescription
Action “DidEdit”
SessionId Authenticated Session identifier
DidId A positive integer which references a unique DID
UserId A positive integer which references a unique user
Destination A valid hosted SIP address
CallerIdNumberRequired Block calls that don’t have valid caller-id number info; boolean (true/false)

Result Element Schema

DidEdit.rnc:

DidEdit.rng, Did.rng

Sample Request

cURL
1
2
3
curl -X POST \
--data 'Action=DidEdit&SessionId=c70d58iib3rc6etn4usj2kvlk5&DidId=107401&UserId=152255&Destination=john@example.onsip.com&CallerIdNumberRequired=false' \
https://api.onsip.com/api
JavaScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
var data = new FormData();
data.append('Action', 'DidEdit');
data.append('SessionId', 'c70d58iib3rc6etn4usj2kvlk5');
data.append('DidId', '107401');
data.append('UserId', '152255');
data.append('Destination', 'john@example.onsip.com');
data.append('CallerIdNumberRequired', 'false');

var xhr = new XMLHttpRequest();
xhr.open('POST', 'https://api.onsip.com/api', true);
xhr.onload = function () {
  console.log(this.responseText);
}
xhr.send(data);

Sample Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
<Response xmlns="http://www.jnctn.net/ns/rest/2006-01">
  <Context>
    <Action>
      <IsCompleted>true</IsCompleted>
    </Action>
    <Request>
      <IsValid>true</IsValid>
      <DateTime>2014-04-21T18:32:33+00:00</DateTime>
      <Duration>97</Duration>
      <Parameters>
        <Parameter>
          <Name>Action</Name>
          <Value>DidEdit</Value>
        </Parameter>
        <Parameter>
          <Name>SessionId</Name>
          <Value>c70d58iib3rc6etn4usj2kvlk5</Value>
        </Parameter>
        <Parameter>
          <Name>DidId</Name>
          <Value>107401</Value>
        </Parameter>
        <Parameter>
          <Name>UserId</Name>
          <Value>152255</Value>
        </Parameter>
        <Parameter>
          <Name>Destination</Name>
          <Value>john@example.onsip.com</Value>
        </Parameter>
        <Parameter>
          <Name>CallerIdNumberRequired</Name>
          <Value>false</Value>
        </Parameter>
      </Parameters>
    </Request>
    <Session>
      <IsEstablished>true</IsEstablished>
      <SessionId>c70d58iib3rc6etn4usj2kvlk5</SessionId>
      <UserId>152255</UserId>
      <Roles>
        <Role>
          <Name>Account Admin</Name>
        </Role>
      </Roles>
    </Session>
  </Context>
  <Result>
    <DidEdit>
      <Did>
        <DidId>108155</DidId>
        <UserId>152255</UserId>
        <OrganizationId>25018</OrganizationId>
        <AccountId>22543</AccountId>
        <UserStatus>enabled</UserStatus>
        <Number>13077635527</Number>
        <Protocol>sip</Protocol>
        <Timeout>120</Timeout>
        <FailoverEnabled>false</FailoverEnabled>
        <FailoverProtocol>pstn</FailoverProtocol>
        <FailoverLocation/>
        <VoicemailboxId/>
        <CallerIdNumberRequired>false</CallerIdNumberRequired>
        <SimultaniousCallLimit>25</SimultaniousCallLimit>
        <Modified>2014-04-21T18:32:34+00:00</Modified>
        <Created>2014-04-21T18:32:34+00:00</Created>
        <Note/>
        <Name/>
        <UserNumberAlias>
          <AliasUsername>13077635527</AliasUsername>
          <AliasDomain>jnctn.net</AliasDomain>
          <AddressUsername>john</AddressUsername>
          <AddressDomain>example.onsip.com</AddressDomain>
          <AddressType>user</AddressType>
          <AddressName>John Example</AddressName>
          <AddressId>485802</AddressId>
          <UserId>152255</UserId>
          <Number>13077635527</Number>
        </UserNumberAlias>
      </Did>
    </DidEdit>
  </Result>
</Response>

DID Edit Name

Update the caller ID name associated with a phone number.

Authentication & Authorization

AuthenticationAuthorization
Authenticated Session Account Admin

Request Parameters

Required ParametersDescription
Action “DidEditName”
SessionId Authenticated Session identifier
DidId A positive integer which references a unique DID
Name The caller ID name to associate with the DID

Result Element Schema

DidEditName.rnc:

DidEditName.rng, Did.rng

Sample Request

cURL
1
2
3
curl -X POST \
--data 'Action=DidEditName&SessionId=c70d58iib3rc6etn4usj2kvlk5&DidId=108155&Name=newname' \
https://api.onsip.com/api
JavaScript
1
2
3
4
5
6
7
8
9
10
11
12
var data = new FormData();
data.append('Action', 'DidEditName');
data.append('SessionId', 'c70d58iib3rc6etn4usj2kvlk5');
data.append('DidId', '108155');
data.append('Name', 'newname');

var xhr = new XMLHttpRequest();
xhr.open('POST', 'https://api.onsip.com/api', true);
xhr.onload = function () {
  console.log(this.responseText);
}
xhr.send(data);

Sample Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
<Response xmlns="http://www.jnctn.net/ns/rest/2006-01">
  <Context>
    <Action>
      <IsCompleted>true</IsCompleted>
    </Action>
    <Request>
      <IsValid>true</IsValid>
      <DateTime>2014-04-21T18:34:26+00:00</DateTime>
      <Duration>35</Duration>
      <Parameters>
        <Parameter>
          <Name>Action</Name>
          <Value>DidEditName</Value>
        </Parameter>
        <Parameter>
          <Name>SessionId</Name>
          <Value>c70d58iib3rc6etn4usj2kvlk5</Value>
        </Parameter>
        <Parameter>
          <Name>DidId</Name>
          <Value>108155</Value>
        </Parameter>
        <Parameter>
          <Name>Name</Name>
          <Value>newname</Value>
        </Parameter>
      </Parameters>
    </Request>
    <Session>
      <IsEstablished>true</IsEstablished>
      <SessionId>c70d58iib3rc6etn4usj2kvlk5</SessionId>
      <UserId>152255</UserId>
      <Roles>
        <Role>
          <Name>Account Admin</Name>
        </Role>
      </Roles>
    </Session>
  </Context>
  <Result>
    <DidEditName>
      <Did>
        <DidId>108155</DidId>
        <UserId>152255</UserId>
        <OrganizationId>25018</OrganizationId>
        <AccountId>22543</AccountId>
        <UserStatus>enabled</UserStatus>
        <Number>13077635527</Number>
        <Protocol>sip</Protocol>
        <Timeout>120</Timeout>
        <FailoverEnabled>false</FailoverEnabled>
        <FailoverProtocol>pstn</FailoverProtocol>
        <FailoverLocation/>
        <VoicemailboxId/>
        <CallerIdNumberRequired>false</CallerIdNumberRequired>
        <SimultaniousCallLimit>25</SimultaniousCallLimit>
        <Modified>2014-04-21T18:32:34+00:00</Modified>
        <Created>2014-04-21T18:32:34+00:00</Created>
        <Note/>
        <Name>newname</Name>
        <UserNumberAlias>
          <AliasUsername>13077635527</AliasUsername>
          <AliasDomain>jnctn.net</AliasDomain>
          <AddressUsername>john</AddressUsername>
          <AddressDomain>example.onsip.com</AddressDomain>
          <AddressType>user</AddressType>
          <AddressName>JJohn Example</AddressName>
          <AddressId>485802</AddressId>
          <UserId>152255</UserId>
          <Number>13077635527</Number>
        </UserNumberAlias>
      </Did>
    </DidEditName>
  </Result>
</Response>

DID Delete

Remove a DID from an account.

Authentication & Authorization

AuthenticationAuthorization
Authenticated Session Account Admin

Request Parameters

Required ParametersDescription
Action “DidDelete”
SessionId Authenticated Session identifier
DidId A positive integer which references a unique DID

Result Element Schema

DidDelete.rnc:

DidDelete.rng, Did.rng

Sample Request

cURL
1
2
3
curl -X POST \
--data 'Action=DidDelete&SessionId=c70d58iib3rc6etn4usj2kvlk5&DidId=108155' \
https://api.onsip.com/api
JavaScript
1
2
3
4
5
6
7
8
9
10
11
var data = new FormData();
data.append('Action', 'DidDelete');
data.append('SessionId', 'c70d58iib3rc6etn4usj2kvlk5');
data.append('DidId', '108155');

var xhr = new XMLHttpRequest();
xhr.open('POST', 'https://api.onsip.com/api', true);
xhr.onload = function () {
  console.log(this.responseText);
}
xhr.send(data);

Sample Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
<Response xmlns="http://www.jnctn.net/ns/rest/2006-01">
  <Context>
    <Action>
      <IsCompleted>true</IsCompleted>
    </Action>
    <Request>
      <IsValid>true</IsValid>
      <DateTime>2014-04-21T18:34:51+00:00</DateTime>
      <Duration>40</Duration>
      <Parameters>
        <Parameter>
          <Name>Action</Name>
          <Value>DidDelete</Value>
        </Parameter>
        <Parameter>
          <Name>SessionId</Name>
          <Value>c70d58iib3rc6etn4usj2kvlk5</Value>
        </Parameter>
        <Parameter>
          <Name>DidId</Name>
          <Value>108155</Value>
        </Parameter>
      </Parameters>
    </Request>
    <Session>
      <IsEstablished>true</IsEstablished>
      <SessionId>c70d58iib3rc6etn4usj2kvlk5</SessionId>
      <UserId>152255</UserId>
      <Roles>
        <Role>
          <Name>Account Admin</Name>
        </Role>
      </Roles>
    </Session>
  </Context>
  <Result>
    <DidDelete>
      <PoolDid>
        <PoolDidId>132224</PoolDidId>
        <Number>13077635527</Number>
        <Origin>lvlt</Origin>
        <Status>held</Status>
        <Modified>2014-04-21T18:34:51+00:00</Modified>
      </PoolDid>
    </DidDelete>
  </Result>
</Response>

Topics: Developer Docs