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. Get DIDs cities

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

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.

perl example

php example

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.

* All parameters are case sensitive.
* All API requests should include your API key (you have to receive it from Diamondcrad.us when activating API).
* To use this service your account should be active and have enough funds in your account.

3. DIDs ordering

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. 

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. 

3.3. Load avalable 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. 

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. 

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. 

4. Manage accounts

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. 

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. '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. 

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
    CallerId - callerId number in format: 'ON_NUMBER' - turn ON and set the number. '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. 

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. 

5. Manage DIDs

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. 

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. 

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. 

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. 



Tags for this page:   api