1. General description
2. Basic requirements
3. DIDs ordering
3.1. Get DIDs countries
3.2. Get DIDs states
3.3. Load available cities/area codes
3.4. Order DID
3.5. Check DID Order
4. Manage accounts
4.1. Create account
4.2. Load account details
4.3. Update account details
4.4. Recharge account
5. Manage DIDs
5.1. Load DID current settings.
5.2. Assign DID
5.3. Update DID settings
5.4. Renew DID
Diamondcard.us API provides the possibility to operate with Diamondcard.us services from your own applications. Communication with the API uses the SOAP protocol. SOAP client libraries can be found for most development environments. SOAP communication supported over http and https protocols. In addition to this description we provide examples written in Perl and PHP.
Diamondcard.us API provided with the SOAP protocol.
WSDL description of API available at http://diamondcard.us/download/api/dc-api.wsdl
API requests should be send on www.diamondcard.us/exec/api-dispatcher over http or https protocol.
Method: did_listcountries
This method will return the list of countries from active coverage list.
Input Params:
AuthKey - your API authentication key
DidType - DID type: 'TFN' for toll free DIDs and 'PPN' or empty for regular DIDs
Return value:
On success
ErrMsg - empty.
Countries - array of available countries in format: ID,NAME.
For example:
AR,"Argentina"
AU,"Australia"
AT,"Austria"
BE,"Belgium"
On error
ErrMsg - error description text.
Method: did_liststates
This method will return the list of available states by country ID. The country ID value is passed from method did_listcountries. This method is available for USA (US) and Canada (CA) country IDs only.
Input Params:
AuthKey - your API authentication key
Country - 2 char country ID (from did_listcountries method)
Return value:
On success
ErrMsg - empty.
States - array of available states
For example:
AL
AZ
CA
CO
CT
On error
ErrMsg - error description text.
Method: did_list This method will return the list of available cities by country ID and state ID along with reseller's prices. The country ID value is passed from method did_listcountries. The state ID value is passed from method did_liststates (for USA and Canada only).
Input Params:
AuthKey - your API authentication key
Country - 2 char country ID (from did_listcountries method)
State - 2 char state ID (from did_liststates method for USA and Canada only)
DidType - DID type: 'TFN' for toll free DIDs and 'PPN' or empty for regular DIDs
Return value:
On success
ErrMsg - empty.
List - array of available DIDs in format:
DidCode,City,Prefix,SetupPrice,MonthlyPrice
Where: DidCode - unique code for ordering DID (required in 'order_did' method)
City - city name
Prefix - DID prefix
SetupPrice - setup price
MonthlyPrice - price per month
For example:
1348_76456,London,44-207-XXX-XXXX,5,6
6578_94415,Manchester,44-161-XXX-XXXX,3,10
On error
ErrMsg - error description text.
Method: order_did
This method will make a new order. The UniqKey value must be different for every new order. If you pass the same value again, 'duplicate request' error will be returned. The DidCode value is passed from did_list method.
Input Params:
AuthKey - your API authentication key
DidCode - DID code (from did_list method)
UniqKey - unique key to prevent duplicate requests
Quantity - number of required DIDs
Duration - service duration. You can order DId for 1,3,6 and 12 months
Return value:
On success
ErrMsg - empty.
Status - status of the order: Completed - all required DIDs assigned
Pending - one or more DIDs were not assigned. It may take 1-2 business days and in some cases it could take as long as 7-10 business days to be assigned.
Numbers - list of ordered DIds separated by coma
OrderId - created order Id. Could be used to check the status of the order
For example:
Status: Completed
Numbers: 12345679801,12345678902
OrderId: 53687
On error
ErrMsg - error description text.
Method: order_info
This method will check order created by order_did method. The OrderId value is passed from order_did method.
Input Params:
AuthKey - your API authentication key
OrderId - Order ID (from order_did method)
Return value:
On success
ErrMsg - empty.
Status - status of the order: Completed - all required DIDs assigned
Pending - one or more DIDs were not assigned. It may take 1-2 business days and in some cases it could take as long as 7-10 business days to be assigned.
Numbers - list of ordered DIds separated by coma
For example:
Status: Completed
Numbers: 12345679801,12345678902
On error
ErrMsg - error description text.
Method: acc_add
This method will create new account
Input Params:
AuthKey - your API authentication key
UserName - username
Password - password
BalanceType - balance type 'unlim' for unlimited
Amount - initial balance
Currency - currency code for balance, 'USD' will be used by default
FirstName - first name
LastName - last name
Email - email
DayPhone - phone number
NoMail - if 1 do not sent notification emails
Return value:
On success
ErrMsg - empty.
AccId - account Id of created account
PinCode - pin code of created account
On error
ErrMsg - error description text.
Method: acc_info
This method will load account's details
Input Params:
AuthKey - your API authentication key
AccId - account Id
Return value:
On success
ErrMsg - empty.
Status - account status "active" or "lock"
PinCode - Pin code
BalanceType - balance type 'unlim' for unlimited
Balance - current balance
Currency - currency code
FirstName - first name
LastName - last name
Email - email
DayPhone - phone number
SpeedDial - Speed dial numbers: code and number pairs separate by coma. CODE1_NUMBER1,CODE2_NUMBER2.
Pinless - pinless numbers separated by coma.
CallerId - callerId number in format: 'ON_NUMBER' - feature turned ON and set the number OR 'ON_NUMBER_NAME' - feature turned ON, set the number and caller name. 'OFF' - feature turned OFF.
MultiCalls - Simultaneous calls in format: ON_MIN where MIN - call max duration in minutes. 'OFF' - feature turned OFF.
On error
ErrMsg - error description text.
Method: acc_update
This method will update account's details
Input Params:
AuthKey - your API authentication key
AccId - account Id
Status - new status: ON - active, OFF - not active
SpeedDial - speed dial setting: code and number pairs separate by coma. CODE1_NUMBER1,CODE2_NUMBER2. 'OFF' value will remove all speed dial settings
Pinless - pinless numbers separated by coma. 'OFF' value will remove all pinless numbers
CALLERDID - callerId number in format: 'ON_NUMBER' - turn ON and set the number OR 'ON_NUMBER_NAME' - turn ON, set the number and caller name. 'OFF' - turning OFF this feature.
MultiCalls - Simultaneous calls in format: ON_MIN where MIN - call max duration in minutes. 'OFF' - turning OFF this feature.
Return value:
On success
ErrMsg - OK.
On error
ErrMsg - error description text.
Method: acc_recharge
This method will recharge account
Input Params:
AuthKey - your API authentication key
AccId - account Id
Amount - amount to recharge
Currency - currency code
Comments - transaction comments
Return value:
On success
ErrMsg - empty.
Balance - result balance
Currency - balance currency code
On error
ErrMsg - error description text.
Method: did_info
This method load DID current settings (assignment and redirect)
Input Params:
AuthKey - your API authentication key
Number - number (DID)
Return value:
On success
ErrMsg - empty.
ExpDate - expiration date in mm/dd/yy format or empty if noe expiration date
Redirect - redirect rule in case if DID is redirected by account himself. 'PROFILE' if profile is used for redirect
AutoRenew - autorenew setting (ON or OFF)
SubAccId - account Id of sub account to which DID is assigned to
SubExpDate - sub account's assignment expiration date
SubAutoRenew - autorenew setting for sub account's assignment (ON or OFF)
SubRedirect - redirect rule of sub account's assignment. 'PROFILE' if profile is used for redirect, 'ASSIGNED' if DID is reassigned to sub account
On error
ErrMsg - error description text.
Method: did_assign
This method assign DId to sub account
Input Params:
AuthKey - your API authentication key
Number - number (DID)
SubAccId - sub account Id we want ot assign DID to. 'OFF' in case if we need to remove DID from sub account
ExpDate - exp date to set for sub account's number in format mm/dd/yyyy
Return value:
On success
ErrMsg - OK
On error
ErrMsg - error description text.
Method: did_update
This method update DID redirect/autorenew settings
Input Params:
AuthKey - your API authentication key
Number - number (DID)
SubAccId - sub account Id if we want to change redirect settings for sub account. If empty - we'll changed settings for main account
Redirect - new redirect rule. 'OFF' to empty redirect rule
AutoRenew - autorenew flag (ON/OFF)
Return value:
On success
ErrMsg - OK
On error
ErrMsg - error description text.
Method: did_renew
This method renew DID
Input Params:
AuthKey - your API authentication key
Number - number (DID)
RenewPeriod - renew period in months. 1,3,6,12 are available
UniqKey - unique key to prevent duplicate requests
Return value:
On success
ErrMsg - OK
On error
ErrMsg - error description text.