Skip to main content

CSR Lookup Tool

This walks through how to programmatically lookup Customer Service Records (CSRs for short) for Phone Numbers before porting into your Bandwidth account.

Polling vs. Webhooks#

CSR Orders in the Bandwidth Dashboard are asynchronous when creating an "order". The orders are then processed and the order status is updated asynchronously. Bandwidth recommends configuring your account with a subscription instead of polling the order resource for <OrderStatus>.

Order processing times can vary and are not guaranteed, so bandwidth does not recommend setting a timeout on waiting for an order to show either COMPLETE or FAILED status, but instead relying on a webhook from a CSR Orders subscription.

Create a CSR Order#

Before creating the order, be sure to collect any information from the end user to submit to the CSR API. Generally speaking, the more information provided, the better.

Request URL#

POST https://dashboard.bandwidth.com/api/accounts/{accountId}/csrs

Request Parameters#

ParameterRequiredDescription
CustomerOrderIdNoInternal customer order id for tracking the order. Only alphanumeric values, dashes and spaces are allowed. Max length is 40 characters.
WorkingOrBillingTelephoneNumber (WTN)YesWorking or Billing telephone number in 10-digits format NPANXXXXXX.
AccountNumberNoIdentifies the main account number on your bill, assigned by the current service provider. Alphanumeric characters are supported with a max length of 20 characters.
AccountTelephoneNumberNoIdentifies the account telephone number assigned by the current service provider. Alphanumeric characters are supported with a max length of 10 characters.
EndUserNameNoIdentifies the name of the end user associated with the telephone number being queried. Alphanumeric characters are supported with a max length of 100 characters.
AuthorizingUserNameNoIdentifies the name of the end user who signed the authorization. Alphanumeric characters are supported with a max length of 100 characters.
CustomerCodeNoIdentifies the customer code associated with the service provider. Must be numeric characters only with a max length of 3 characters.
EndUserPINNoIdentifies the end user’s personal identification number (PIN). Alphanumeric characters are supported with a max length of 50 characters.
EndUserPasswordNoIdentifies the end user’s password to access the CSR, if applicable. Alphanumeric characters are supported with a max length of 100 characters.
AddressLine1NoIdentifies the address line 1 portion of the service address. Alphanumeric characters are supported with a max length of 200 characters.
CityNoIdentifies the city of the end user where the telephone number is being serviced. Alphanumeric characters are supported with a max length of 100 characters.
StateNoIdentifies the abbreviation for the state or province of the end user where the telephone number is being serviced. Must be alpha characters only in the format XX with a max length of 2 characters, where XX is the state or province abbreviation.
ZIPCodeNoIdentifies the ZIP code, ZIP Code + extension, or postal code or the end user where the telephone number is being serviced. Alphanumeric characters are supported with a max length of 10 characters (including the dash if using ZIP Code with extension).
TypeOfServiceNoThe type of service identifying the end user account. Must be alphabetic characters only with a max length of 50 characters.

Examples#

Request

POST https://dashboard.bandwidth.com/api/accounts/{{accountId}}/csrs HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
<Csr>
<CustomerOrderId>CustomerOrderId</CustomerOrderId>
<WorkingOrBillingTelephoneNumber>9198675309</WorkingOrBillingTelephoneNumber>
<EndUserPIN>1234</EndUserPIN>
</Csr>

Response

HTTP/1.1 200 OK
Content-Type: application/xml
Location: https://dashboard.bandwidth.com/api/accounts/{{accountId}}/csrs/{{orderId}}
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<CsrResponse>
<OrderId>18cee9d0-a5c5-4322-9a47-d04176bc924c</OrderId>
<Status>RECEIVED</Status>
</CsrResponse>

Fetch Order Status#

Request URL#

GET https://dashboard.bandwidth.com/api/accounts/{accountId}/csrs/{orderId}

Examples#

CsrOrder Status Webhook

info

This is a webhook that bandwidth sends to your server upon order completion/failure - there is no need to poll the resource if using this recommended method.

POST your_url.com/webhookService HTTP/1.1
Content-Type: application/xml; charset=utf-8
<?xml version="1.0"?>
<Notification>
<SubscriptionId>...</SubscriptionId>
<OrderType>csrs</OrderType>
<OrderId>b05de7e6-0cab-4c83-81bb-9379cba8efd0</OrderId>
<CustomerOrderId>...</CustomerOrderId>
<Status>COMPLETE</Status>
</Notification>

Update an Order#

A PUT method provides the ability to replace the existing csr conditional data with specificed csr conditional data. To cancel CSR order, users must provide a Status element with REQUESTEDCANCEL value. Note that csr order must be a non-real time with PROCESSING or ACTIONREQUIRED status.

Request URL#

PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/csrs/{orderId}

Examples#

Request

PUT https://dashboard.bandwidth.com/api/accounts/{{accountId}}/csrs HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
<Csr>
<AccountNumber>987654321</AccountNumber>
<AccountTelephoneNumber>9196194444</AccountTelephoneNumber>
<EndUserName>bandwidthGuy</EndUserName>
<AuthorizingUserName>importantAuthGuy</AuthorizingUserName>
<CustomerCode>123</CustomerCode>
<EndUserPIN>12345</EndUserPIN>
<EndUserPassword>enduserpassword123</EndUserPassword>
<AddressLine1>900 Main Campus Dr</AddressLine1>
<City>Raleigh</City>
<State>NC</State>
<ZIPCode>27612</ZIPCode>
<TypeOfService>residential</TypeOfService>
<!-- cancel csr order -->
<Status>REQUESTED_CANCEL</Status>
</Csr>

Response

HTTP 200 OK
Content-Type: application/xml; charset=utf-8
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<CsrResponse>
<CustomerOrderId>TEST BWDB-6506</CustomerOrderId>
<LastModifiedBy>systemUser</LastModifiedBy>
<OrderCreateDate>2020-01-13T21:14:35Z</OrderCreateDate>
<AccountId>14</AccountId>
<OrderId>5c3b8240-52b5-45a5-8d7d-42a71ebcd1ba</OrderId>
<LastModifiedDate>2020-01-13T16:51:21.920Z</LastModifiedDate>
<Status>COMPLETE</Status>
<AccountNumber>987654321</AccountNumber>
<AccountTelephoneNumber>9196194444</AccountTelephoneNumber>
<EndUserName>bandwidthGuy</EndUserName>
<AuthorizingUserName>importantAuthGuy</AuthorizingUserName>
<CustomerCode>123</CustomerCode>
<EndUserPIN>12345</EndUserPIN>
<EndUserPassword>enduserpassword123</EndUserPassword>
<AddressLine1>900 Main Campus Dr</AddressLine1>
<City>Raleigh</City>
<State>NC</State>
<ZIPCode>27612</ZIPCode>
<TypeOfService>residential</TypeOfService>
<CsrData>
<AccountNumber>123456789</AccountNumber>
<CustomerName>JOHN SMITH</CustomerName>
<ServiceAddress>
<UnparsedAddress>900 MAIN CAMPUS DR</UnparsedAddress>
<City>RALEIGH</City>
<State>NC</State>
<Zip>27616</Zip>
</ServiceAddress>
<WorkingTelephoneNumber>9196191156</WorkingTelephoneNumber>
<WorkingTelephoneNumbersOnAccount>
<TelephoneNumber>9196191156</TelephoneNumber>
</WorkingTelephoneNumbersOnAccount>
</CsrData>
</CsrResponse>