Sample Domain Names API Flow and some Notes

Buying Process for a single Domain Name

  1. Checking Domain Availability: First call the DomOrder.checkAvailabilityMultiple() method to discover if the domain name in question is available for registration.

  2. Customer Selection/Addition: If the domain name is available, you will have to retrieve the Customer Id of the Customer who wishes to buy the it. If the Customer already exists, you can use Customer.getCustomerId() to get it or use Customer.signUp() to create a new one. The Customer Id will be in the return value in both cases.

  3. Get Registration Info: You'll need the Name Servers and the Contact Ids to register a domain name at the Registry. Get the list of existing Contacts using DomContact.listByType().

  4. Validate the parameters: Now pass all the information required to DomOrder.validateDomainRegistrationsParams() to validate them and ensure correctness.

  5. Register the Domain: Call DomOrder.addWithoutValidation() with all the parameters you've just validated and you're basically done.

  • Using DomOrder.add(): The use of DomOrder.add() to register a domain is now deprecated. This method is single-threaded and inefficient and so is much slower than using steps 4 and 5 in the Buying process flow. Use the DomOrder.validateDomainRegistrationsParams(), DomOrder.addWithoutValidation() method pair instead.

  • Adding Contacts for .US and .COOP domains: The Contacts for .US and .COOP need to have addition information to be correctly added. .US requires a Nexus Category while .COOP requires a Sponsor (Co-operative Reference). When attempting to register these domains, DomOrder.validateDomainRegistrationsParams() will return "InsufficientContactDataException in DomValidation while adding order" in the status has under the error key. When you see this error, you should use DomContactExt.setContactDetails() to set the relevant additional information and try again. If you attempt to call DomOrder.addWithoutValidation() with these incomplete Contacts for .US or .COOP, you will get "Error during adding Contact" in the status hash under the error key.

Modifying Domain Name Details

There is no single DomOrder.mod() method. Rather, you must call the relevant method to modify the appropriate property of a domain name. For example, to modify the Domain Secret, call DomOrder.modifyDomainSecret() and so on.

Modifying Domain Contact Details

There is a bit of a niggle when modifying the Contacts to be used by a domain name. One can first get the Contact Ids for a particular domain name by calling DomOrder.getDetails() with the orderid and ContactIds in the options Vector. We can then use DomContact.listNames() to get a list of all Contacts belonging to a particular Customer and show this in a list on the screen. We can then use DomOrder.modifyContact() to modify the Contacts being used.

If the Customer chooses to modify the Registrant Contact, then we should check if it is fit to be used in such a manner by calling DomContactExt.isValidRegistrantContact(). Some Registries like .US and .COOP require additional information and this can be supplied to the Contact with a call to DomContactExt.setContactDetails() if DomContactExt.isValidRegistrantContact() returns false.

If an attempt is made to use an incorrect Contact Id (one which would fail the DomContactExt.isValidRegistrantContact() test), then a InsufficientContactDataException is thrown. You can catch it and then set the details using DomContactExt.setContactDetails().


The system allows you to create an infinite number of Resellers and Sub-Resellers, each with Customers under them. Orders can be placed only on behalf of the Customers and cannot be owned by Resellers or their Sub-Resellers directly. You can create as many Customers as you wish.