Diamondcard.us API description

1. General description

2. Basic requirements

3. DID's ordering

3.1. Get DID's countries

3.2. Get DID's states

3.3. Get DID's 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 DID's

5.1. Load DID current settings.

5.2. Assign DID

5.3. Update DID settings

5.4. Renew DID

1. General description

The Diamondcard API gives you the ability to operate and manage Diamondcard services from within your own applications. This is normally used for reselling Diamondcard services within your own applications. You need a PE account to be able to use the API. A PE is a Diamondcard reseller account. Private Enterprise Distributor (PE)

Contact Diamondcard to upgrade to a PE account.

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 API provided with the SOAP protocol.

WSDL description of API available at http://diamondcard.us/download/api/dc-api.wsdl

API requests should be sent on www.diamondcard.us/exec/api-dispatcher over http or https protocol.

* All parameters are case sensitive.
* All API requests must include your API secret key. When your account is turned on to use the API, the secret key will show up in your admin center under the OPTIONS link in the PE section.
* To use this service your account should be active and have enough funds in your account to pass calls.

3. DID ordering

3.1. Get DID 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 DID's and 'PPN' or empty for regular DID's 
  
  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 DID 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 DID's 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 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 DID's and 'PPN' or empty for regular DID's
  
  Return value:
    On success
      ErrMsg - empty.
      List - array of available DID's 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 create a new DID 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 DID's
    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 DID's assigned
				    Pending - one or more DID's were not assigned. It may take 1-2 business days and in some cases it could take as long as 7-10 business days for a DID to be assigned
      Numbers - list of ordered DID's separated by a comma
      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 order: Completed - all required DID's assigned
				    Pending - one or more DID's were not assigned. It may take 1-2 business days and in some cases it could take as long as 7-10 business days for the DID to be assigned.
      Numbers - list of ordered DID's separated by a comma
            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 a new PE sub-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 send 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 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 a comma. CODE1_NUMBER1,CODE2_NUMBER2.
      Pinless - pinless numbers separated by a comma.
      CallerId - callerId number in format: 'ON_NUMBER' - feature turned ON and set the number. 'OFF' - feature turned OFF.
    On error
      ErrMsg - error description text. 

4.3. Update account details

Method: acc_update

This method will update account 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 a comma. CODE1_NUMBER1,CODE2_NUMBER2. 'OFF' value will remove all speed dial settings
    Pinless - pinless numbers separated by a comma. 'OFF' value will remove all pinless numbers
    CallerId - callerId number in format: 'ON_NUMBER' - turn ON and set the number. 'OFF' - turn 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 DID's

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 no expiration date
      Redirect - redirect rule in case 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 assignment expiration date
      SubAutoRenew - auto-renew setting for sub account assignment (ON or OFF)
      SubRedirect - redirect rule of sub account 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 assigns DId to a PE sub-account

  Input Params:
    AuthKey - your API authentication key
    Number - number (DID)
    SubAccId - sub-account Id we want to assign DID to. 'OFF' in case we need to remove DID from sub-account
    ExpDate - exp date to set for sub account 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 updates 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 change 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