Page Source for Api
=begin options
write = root
=end options
=head2 Diamondcard.us API description
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
=head3 1. General description
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.
L<perl
example|https://www.diamondcard.us/download/api/example.perl>
L<php
example|https://www.diamondcard.us/download/api/example.php>
=head3 2. Basic requirements
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.
=item * All parameters are case sensitive.
=item * All API requests should include your API key (you have to
receive it from Diamondcrad.us when activating API).
=item * To use this service your account should be active and have
enough funds in your account.
=head3 3. DIDs ordering
=head4 3.1. Get DIDs countries
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.
=head4 3.2. Get DIDs states
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.
=head4 3.3. Load available cities/area codes
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.
=head4 3.4. Order DID
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.
=head4 3.5. Check DID Order
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.
=head3 4. Manage accounts
=head4 4.1. Create account
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.
=head4 4.2. Load account details
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.
=head4 4.3. Update account details
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.
=head4 4.4. Recharge account
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.
=head3 5. Manage DIDs
=head4 5.1. Load DID current settings.
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.
=head4 5.2. Assign DID
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.
=head4 5.3. Update DID settings
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.
=head4 5.4. Renew DID
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.
X<API>
Tags for this page: api