Using Auth Token received from authentication request(s) client is able to complete set of domain management operations: checking domain(s) availability, creating a domain, updating a domain’s objects, to even deleting a domain. All operations issued to the REST API processed in REAL-TIME.

1. Check domain availability

REST API provide possibility to check availability for single domain using simple GET query.

URI: /domains/:name/check
Request method: GET

Name	Description
name	Fully qualified domain name.

Request example:

After successful request, response will contain following elements:

• avail – identify if domain is available for registration or not. 0 – not available. 1 – available
• code – response code. 1000 if operation successful.
• message – response message. Generally its a description for response code.
• cltrid – client transaction ID which was provided in request.
• svtrid – server transaction ID which was generated by ST Registry for corresponding request.
• time – request execution time in seconds.

Response example:

 

2. Create domain

The create command is performed through PUT request to the domains resource. During the domain creation process host object(s) (name servers) are also created if they do not exist in ST Registry hosts repository. If host object used in domain creation process already exist in hosts repository then it just linked with newly created domain. In case if there is a need to assign IP address(es) to the host (for DNS glue record) – this should be done with a separate <update> command request for corresponding host object.

URI: /domains
Request method: PUT

Name	Description
name	Domain name
period	Domain registration period group. Group include unit and value variables. unit – measure unit identifier for registration period. m – month(s), y – year(s). value – unit value.
ns (optional)	Name servers array which refer to the hosts object repository. If host is unknown – ST Registry will attempt to create it. If host(s) not provided – domain will be created with status inactive.
contacts	Contacts array which refer to existing contacts object repository. Before creating a domain registrar should create contacts which will be used during domain registration process.
authInfo (optional)	Contain attribute pw – which identify AuthCode/EPPCode for newly created domain. Optional value. If not provided – ST Registry will generate it

Request example:

After successful request, response will contain following elements:

• creData – Registration details collection.
• creData/name – Domain name which was created on current request.
• creData/crDate – Domain registration date.
• creData/exDate – Domain expire date.
• code – response code. 1000 if operation successful.
• message – response message. Generally its a description for response code.
• cltrid – client transaction ID which was provided in request.
• svtrid – server transaction ID which was generated by ST Registry for corresponding request.
• time – request execution time in seconds.

Response example:

 

3. Domain name server handling

Domain name server handling is performed through Domain update request and/or host management functionality.

When domain is created/updated and used host objects that doesn’t exist in Registry repository – then Registry will attempt to create them. If provided host object already available in Registry repository – it will be linked with corresponding domain object.

4. Query domain info

Query domain info in REST API is implemented in different way comparing to the EPP API. If in EPP API <domain:info> command handle requests from both – authorized and not authorized clients, in REST API for each type of request should be used independent resource.
There is totally 3 request types:

1. Query complete domain info from client repository by authorized Client.
2. Query complete domain info by unauthorized Client using AuthInfo.
3. Query public domain info by any ST Registry Client.

Each request type have own resource which is responsible for handling certain request . Every resource have own response format which is described in details below.

4.1. Query domain info by authorized Client

This resource provide possibility to fetch complete information about domain from client repository. You should keep in mind that resource operate only with domains where current client is a sponsoring registrar. To fetch public domain details should be used WHOIS resource. Unauthorized client may query complete domain details by providing authInfo for corresponding domain, this is described in paragraph “4.2. Query complete domain info by unauthorized client using AuthInfo“.

URI: /domains/:name
Request method: GET

Name	Description
name	Fully qualified domain name.

Request example:

After successful request, response will contain following elements:

• info – Domain details collection.
• info/name – Request domain name. Value always available in response.
• info/clID – ClientID who is currently acting registrar for the domain. In other words this is a client/registrar ID who is making this request. Value always available in response.
• info/crID – ClientID who has originally registered/created this domain. Value always available in response.
• info/crDate – Domain registration date. Value always available in response.
• info/upDate – Date for the last successful update command execution. This value is optional and may not be available in response if domain didn’t got any successful update commands after domain registration/creation.
• info/exDate – Domain expire date. Value always available in response.
• ns – Name servers collection assigned to the current domain. This collection is optional and may not be available in response if domain have no assigned name servers.
• contacts – Contacts collection assigned to the current domain. There is totally 4 kind of contacts: registrant, admin, billing, tech. All of them are required and always available in response. Collection may also contain optional values which are represented if assigned to the domain: registrant_privacy, admin_privacy, billing_privacy, tech_privacy. Read more about privacy in paragraph “WHOIS Privacy“.
• status – Collection of status codes. More details on status codes page. Domain always have at least 1 status which mean that this collection is always available in response.
• statusDate – Collection of all status codes from “status” collection but with date when each status code was assigned to current domain.
• authInfo – Contain attribute pw – which identify AuthCode/EPPCode for domain. AuthCode/EPPCode is required to gain control over domain by other client/registrar or registrant. Usually is used to initiate domain transfer between clients/registrars.
• code – Response code. 1000 if operation successful.
• message – Response message. Generally its a description for response code.
• cltrid – Client transaction ID which was provided in request.
• svtrid – Server transaction ID which was generated by ST Registry for corresponding request.
• time – Request execution time in seconds.

Response example:

Response codes:

1000 “Command completed successfully” – generated when request successfully handled.

2303 “Object doesn’t exist” – generated when domain doesn’t belong to the client repository or if domain doesn’t exist.

 

4.2. Query domain info by unauthorized Client using AuthInfo

This resource provide possibility to fetch complete information about domain by unauthorized client using authInfo for corresponding domain.

URI: /domains/:name/auth
Request method: POST

Name	Description
name	Fully qualified domain name.

Request example:

Response format for successful request is identical to response described in paragraph “4.1. Query domain info by authorized client“

Response codes:

1000 “Command completed successfully” – generated when request successfully handled.

2001 “Command syntax error” – generated when there is syntax error in request body (JSON parse error)

2202 “Invalid authorization information” – generated if domain was found but authInfo provided for this domain is incorrect

2303 “Object doesn’t exist” – generated when domain if domain doesn’t exist.

4.3. Query public domain info

This type of requests is managed by WHOIS resource, please refer to the paragraph “9. Query domain WHOIS details” for detailed description.

5. Domain update

Domain update command allows modification of attributes of a domain object. Request body may contain following elements/instructions:

• add – optional element that contains attribute values to be added to the object.
• rem – optional element that contains attribute values to be removed from the object.
• chg – optional element that contains object attribute values to be changed.

chg instruction may update ONLY registrant contact and/or AuthInfo (AuthCode/EPPCode). For all other attributes should be used add/rem instructions, including for admin, tech and billing contacts.

URI: /domains/:name
Request method: POST

Name	Description
name	Fully qualified domain name.

Request example:

After successful request, response will contain following elements:

• code – response code. 1000 if operation successful.
• message – response message. Generally its a description for response code.
• cltrid – client transaction ID which was provided in request.
• svtrid – server transaction ID which was generated by ST Registry for corresponding request.
• time – request execution time in seconds.

Response example:

 

6. Delete domain

The delete command allows a client to delete a domain object.

Delete command doesn’t terminate domain immediately, instead, it put it to the deletion queue and assign status pendingDelete which mean that domain will be terminated within 5 days from a moment when this status was assigned, in other words this operation move domain to the termination state described on domain life cycle page

URI: /domains/:name
Request method: DELETE

Name	Description
name	Fully qualified domain name.

Request example:

After successful request, response will contain following elements:

• code – response code. 1000 if operation successful.
• message – response message. Generally its a description for response code.
• cltrid – client transaction ID which was provided in request.
• svtrid – server transaction ID which was generated by ST Registry for corresponding request.
• time – request execution time in seconds.

Response example:

7. Renew domain

domain renew command is used to extend the validity period of an existing domain. The elements needed to identify and extend the validity period of a domain include the current expiration date of the domain (curExpDate) and the period to extend, which is measured in whole numbers and is of unit “y” for years or “m” for months. Refer to your billing plan to identify how you can use “m”/months unit. curExpDate ensures that repeated <renew> commands do not result in multiple, unanticipated successful renewals.

URI: /domains/:name/renew
Request method: POST

Name	Description
name	Fully qualified domain name.

Request example:

After successful request, response will contain following elements:

• renData – Collection with updated details which contain: name – renewed domain name, exDate – new expiration date which was defined after successful renewal operation.
• code – response code. 1000 if operation successful.
• message – response message. Generally its a description for response code.
• cltrid – client transaction ID which was provided in request.
• svtrid – server transaction ID which was generated by ST Registry for corresponding request.
• time – request execution time in seconds.

Response example:

 

8. Domain transfer

The transfer command is used to manage changes in domain sponsorship of an existing domain. Registrars can “request”, “cancel”, “approve”, “reject”, or “query” a transfer request using the “op” attribute.

A registrar who wishes to assume sponsorship of a known domain from another registrar uses the transfer command with the value of the “op” attribute set to “request” which initiate domain transfer process. Once a transfer has been requested, the same registrar can cancel the request using a transfer command with the value of the “op” attribute set to “cancel”. A request to cancel the transfer MUST be sent to the server before the loosing registrar either approves or rejects the transfer request and before the server automatically processes the request due to responding registrar inactivity. If loosing registrar will not respond to the transfer request within 7 days from a date when it was initiated ST Registry will automatically approve the transfer request.

Once a transfer request has been received by the Gateway, the server MUST notify the current domain sponsor of the requested transfer. Every event that occurs during transfer process create corresponding notification. More details about ST Registry notification system can be found on notifications page. The current status of a pending transfer command for any domain can be found using the transfer command with “op” attribute set to “query”.

The current domain sponsor(loosing registrar) MAY explicitly approve or reject the transfer request. The client can approve the request using a transfer command with the value of the “op” attribute set to “approve”. Clients can reject the request using a transfer command with the value of the “op” attribute set to “reject”.

Authorization password (AuthCode/EPP Code) is required to complete a transfer command.

Domain transfer initiate domain renewal when transfer request is completed. Renewal period is provided in transfer command with the value of the “op” attribute set to “request”. Minimum renewal period is defined in registrar billing plan. If ST Registry will be unable to complete successfully domain renewal (for example due to insufficient funds on registrar account) – transfer will be rejected and will gain status “serverRejected”.

8.1. Transfer command – Request

Transfer command with “op” attribute set to “request”(later just a transfer request command) initiate domain transfer to another registrar. To initiate transfer – gaining registrar should provide domain password (AuthInfo, also known as AuthCode/EPPCode). If domain have status clientTransferProhibited, serverTransferProhibited or pendingTransfer then transfer request will be rejected.

After successful transfer request command – domain will gain status “pendingTransfer” (more about statuses can be found on page “Domain statuses“), together with this ST Registry will send transfer request notification to the loosing registrar (read more about notifications on page “Registrar notifications“). Loosing registrar will have 7 days to process transfer request (accept or decline it). Gaining registrar is able to check transfer status by querying transfer command with “op” attribute set to “query”.

If loosing registrar doesn’t handle transfer request within 7 days after domain transfer request was initiated – such request will be automatically approved by ST Registry:

• Transfer is automatically approved and gain status “serverApproved”.
• Domain with all assiciated hosts transferred to the gaining registrar.
• Created clone for all domain contacts (registrant, admin, billing and technical) in gaining registrar repository.
• pendingTransfer status removed from domain.
• Domain gain serverTransferProhibited status for 60 days.
• Domain renewed for the period provided in transfer request.
• AuthInfo reset (AuthCode/EPPCode). ST Registry will generate new AuthCode which can be retrieved by new registrar with “Query domain info command“.

URI: /domains/:name/transfer

Request method: POST

Name	Description
name	Fully qualified domain name.

Command transfer request contain following elements in request body:

• op – set to “request”.
• period – unit: measure unit identifier for renewal period. m – month(s), y – year(s). Unit “m” (months) depends from billing attribute called “Billing period”. Defined renewal period will be applied after during after transfer request will be accepted.
• authInfo/pw – Domain password/AuthInfo (also known as AuthCode or EPPCode).

After successful transfer request command execution response will contain following elements:

• trnData – transfer request details collection.
• trnData/trStatus – Current status for transfer operation:
  • “clientApproved” – transfer was approved by the loosing registrar/registrant and completed.
  • “clientRejected” – transfer was rejected by the loosing registrar/registrant.
  • “clientCancelled” – transfer was cancelled by the gaining registrar/registrant.
  • “serverApproved” – transfer was approved by ST Registry and completed.
  • “serverCancelled” – transfer was rejected by ST Registry.
• trnData/reID – gaining registrar identifier who have created transfer request.
• trnData/reDate – date and time when transfer request was initially performed.
• trnData/acID – identifier for the registrar who should handle transfer request (when status pending) or who have handled request (for all other statuses). Normally this is loosing registrar.
• trnData/acDate – date and time when corresponding request was handled.
• trnData/exDate – domain expiration date on the date when transfer was initiated (trnData/reDate).
• code – response code. 1000 if operation successful.
• message – response message. Generally its a description for response code.
• cltrid – client transaction ID which was provided in request.
• svtrid – server transaction ID which was generated by ST Registry for corresponding request.
• time – request execution time in seconds.

8.2. Transfer command – Cancel

Transfer command with “op” attribute set to “cancel”(later just a transfer cancel command) is supposed to be used to cancel previously created transfer request.

Transfer cancel command is accepted only from a registrar who have previously initiated transfer request and only if transfer process was not finished (domain is still in status pendingTransfer).

After successful command execution:

• transfer request application is cancelled and application status is updated to “clientCancelled”.
• “pendingTransfer” status is removed from corresponding domain.

URI: /domains/:name/transfer

Request method: POST

Name	Description
name	Fully qualified domain name.

Command transfer request contain following elements in request body:

• op – set to “cancel”.

After successful transfer request command execution response will contain following elements:

• trnData – transfer request details collection.
• trnData/trStatus – Current status for transfer operation:
• • “clientApproved” – transfer was approved by the loosing registrar/registrant and completed.
  • “clientRejected” – transfer was rejected by the loosing registrar/registrant.
  • “clientCancelled” – transfer was cancelled by the gaining registrar/registrant.
  • “serverApproved” – transfer was approved by ST Registry and completed.
  • “serverCancelled” – transfer was rejected by ST Registry.
• trnData/reID – gaining registrar identifier who have created transfer request.
• trnData/reDate – date and time when transfer request was initially performed.
• trnData/acID – identifier for the registrar who should handle transfer request (when status pending) or who have handled request (for all other statuses). Normally this is loosing registrar.
• trnData/acDate – date and time when corresponding request was handled.
• trnData/exDate – domain expiration date on the date when transfer was initiated (trnData/reDate).
• code – response code. 1000 if operation successful.
• message – response message. Generally its a description for response code.
• cltrid – client transaction ID which was provided in request.
• svtrid – server transaction ID which was generated by ST Registry for corresponding request.
• time – request execution time in seconds.

8.3. Transfer command – Approve

Transfer command with “op” attribute set to “approve”(later just a transfer approve command) should be used to approve/accept currently active (status pending) transfer request(s). To be able to successfully submit transfer approve command registrar should ensure that domain is currently in pendingTransfer state (how to check read “QUERY” command).

After successful command execution:

• Transfer application is approved and gain status “clientApproved”
• Domain and related hosts are transferred to the new registrar
• pendingTransfer status from removed from domain and all related objects
• Domain renewed for the period provided in transfer request.
• AuthInfo reset (AuthCode/EPPCode). ST Registry will generate new AuthCode which can be retrieved by new registrar with “Query domain info command”.

URI: /domains/:name/transfer

Request method: POST

Name	Description
name	Fully qualified domain name.

Command transfer request contain following elements in request body:

• op – set to “approve”.

After successful transfer request command execution response will contain following elements:

• trnData – transfer request details collection.
• trnData/trStatus – Current status for transfer operation:
• • “clientApproved” – transfer was approved by the loosing registrar/registrant and completed.
  • “clientRejected” – transfer was rejected by the loosing registrar/registrant.
  • “clientCancelled” – transfer was cancelled by the gaining registrar/registrant.
  • “serverApproved” – transfer was approved by ST Registry and completed.
  • “serverCancelled” – transfer was rejected by ST Registry.
• trnData/reID – gaining registrar identifier who have created transfer request.
• trnData/reDate – date and time when transfer request was initially performed.
• trnData/acID – identifier for the registrar who should handle transfer request (when status pending) or who have handled request (for all other statuses). Normally this is loosing registrar.
• trnData/acDate – date and time when corresponding request was handled.
• trnData/exDate – domain expiration date on the date when transfer was initiated (trnData/reDate).
• code – response code. 1000 if operation successful.
• message – response message. Generally its a description for response code.
• cltrid – client transaction ID which was provided in request.
• svtrid – server transaction ID which was generated by ST Registry for corresponding request.
• time – request execution time in seconds.

 

8.4. Transfer command – Reject

Transfer command with “op” attribute set to “reject”(later just a transfer reject command) should be used to reject currently active (status pending) transfer request(s). To be able to successfully submit transfer reject command registrar should ensure that domain is currently in pendingTransfer state (how to check read “QUERY” command).

After successful command execution:

• Transfer request application is rejected and gain status “clientRejected” (which mean transfer rejected by current/loosing registrar).
• pendingTransfer status is removed from domain.

URI: /domains/:name/transfer

Request method: POST

Name	Description
name	Fully qualified domain name.

Command transfer request contain following elements in request body:

• op – set to “reject”.

After successful transfer request command execution response will contain following elements:

• trnData – transfer request details collection.
• trnData/trStatus – Current status for transfer operation:
• • “clientApproved” – transfer was approved by the loosing registrar/registrant and completed.
  • “clientRejected” – transfer was rejected by the loosing registrar/registrant.
  • “clientCancelled” – transfer was cancelled by the gaining registrar/registrant.
  • “serverApproved” – transfer was approved by ST Registry and completed.
  • “serverCancelled” – transfer was rejected by ST Registry.
• trnData/reID – gaining registrar identifier who have created transfer request.
• trnData/reDate – date and time when transfer request was initially performed.
• trnData/acID – identifier for the registrar who should handle transfer request (when status pending) or who have handled request (for all other statuses). Normally this is loosing registrar.
• trnData/acDate – date and time when corresponding request was handled.
• trnData/exDate – domain expiration date on the date when transfer was initiated (trnData/reDate).
• code – response code. 1000 if operation successful.
• message – response message. Generally its a description for response code.
• cltrid – client transaction ID which was provided in request.
• svtrid – server transaction ID which was generated by ST Registry for corresponding request.
• time – request execution time in seconds.

 

8.5. Transfer command – Query

Transfer command with “op” attribute set to “query”(later just a transfer query command) is supposed to be used to identify transfer operation state for domain to another registrar. This command doesn’t perform any updates to the object.

With transfer query command it is possible to track execution of latest transfer request operation (see transfer request command). This command is available for both – requesting and loosing registrar. This information might be accessed by providing AuthInfo in transfer query command request.

To request transfer query command, registrar who is not currently identified as a domain registrar should provide AuthInfo in transfer query command request. Current domain registrar is able to request transfer query command without providing AuthInfo.

transfer query command request contain following elements:

• op – set to value “query”.
• authInfo/pw – optional(read above) element which define AuthInfo for domain (also known as AuthCode or EPPCode).

URI: /domains/:name/transfer

Request method: POST

Name	Description
name	Fully qualified domain name.

Command transfer request contain following elements in request body:

• op – set to “reject”.

After successful transfer request command execution response will contain following elements:

• trnData – transfer request details collection.
• trnData/trStatus – Current status for transfer operation – “pending”.
• • “clientApproved” – transfer was approved by the loosing registrar/registrant and completed.
  • “clientRejected” – transfer was rejected by the loosing registrar/registrant.
  • “clientCancelled” – transfer was cancelled by the gaining registrar/registrant.
  • “serverApproved” – transfer was approved by ST Registry and completed.
  • “serverCancelled” – transfer was rejected by ST Registry.
• trnData/reID – gaining registrar identifier who have created transfer request.
• trnData/reDate – date and time when transfer request was initially performed.
• trnData/acID – identifier for the registrar who should handle transfer request (when status pending) or who have handled request (for all other statuses). Normally this is loosing registrar.
• trnData/acDate – date and time when corresponding request was handled.
• trnData/exDate – domain expiration date on the date when transfer was initiated (trnData/reDate).
• code – response code. 1000 if operation successful.
• message – response message. Generally its a description for response code.
• cltrid – client transaction ID which was provided in request.
• svtrid – server transaction ID which was generated by ST Registry for corresponding request.
• time – request execution time in seconds.

 

9. Query domain WHOIS details

WHOIS query command is used to fetch public details about domain. If domain is protected with “WHOIS Privacy” – domain contacts will be represented/masked with privacy contacts.

URI: /whois/:name

Name	Description
name	Fully qualified domain name.

Response example:

 

10. WHOIS Privacy

WHOIS Privacy management is managed completely through domain update command by using add/rem instructions and registrant_privacy/admin_privacy/billing_privacy/tech_privacy contact attributes. Please refer to the “Domain update” command for detailed information.

Example of request to create WHOIS Privacy:

URI: /domains/:name
Request method: POST

Name	Description
name	Fully qualified domain name.

Create request example:

WHOIS Privacy Update example:

URI: /domains/:name
Request method: POST

Name	Description
name	Fully qualified domain name.

Update request example:

WHOIS Privacy delete example:

URI: /domains/:name
Request method: POST

Name	Description
name	Fully qualified domain name.

Delete request example:

 

11. Auth Info/EPP Code requirements

When registrar create or update domain and define Auth Info/EPP Code (later EPP Code) for domain on his side – there is a strict rule for it and defined value should pass through validation process to ensure that it meet requirements on ST Registry side:

• Minimum length 6 symbols
• Maximum length 16 symbols
• Code should include at least 1 uppercase character
• Code should include at least 1  lowercase character
• Code should include at least one digit

If provided EPP code will not meet requirements above – such API request will generate error/exception.

 

12. Response codes

To simplify initial integration process, instead of general error messages, ST Registry provide different response messages for same response code depending from exception which generated corresponding response code. Below you can find list of all possible response codes and their messages for domain related operations.

Response code	Message
1000	Command completed successfully
2002	Name server duplicate. NS host name should be unique within same domain.
2002	Specified expiration date and real expiration date mismatch
2003	Missing domain name
2003	registrant, admin, tech and billing contacts are required to complete operation
2003	Missing renewal params
2004	domain:period minLength value=1, maxLength value=99
2004	domain:period unit m|y
2004	pw minLength value=’6′, maxLength value=’16’
2005	Invalid domain:name
2005	Domain is not within allowed list of zones. Allowed zones: st
2005	pendingDelete status MUST NOT be combined with either clientDeleteProhibited or serverDeleteProhibited status and MUST NOT be combined with enother pending statuses.
2005	pendingRenew status MUST NOT be combined with either clientRenewProhibited or serverRenewProhibited status and MUST NOT be combined with enother pending statuses.
2005	pendingTransfer status MUST NOT be combined with either clientTransferProhibited or serverTransferProhibited status and MUST NOT be combined with enother pending statuses.
2005	pendingUpdate status MUST NOT be combined with either clientUpdateProhibited or serverUpdateProhibited status and MUST NOT be combined with enother pending statuses.
2005	Password should have both upper and lower case characters
2005	Password should contain one or more numbers
2005	Unknown transfer operation
2104	Client billing state is locked. Further billing operation(s) disallowed. Contact Registry support for clarifications
2104	Not enough funds on registrar balance to complete operation
2106	Object is not eligible for transfer
2201	Operation not permitted
2201	Auth code update disallowed during domain pending transfer
2201	Transfer was initiated by another registrar
2203	Operation not permitted; Domain object not in client repository
2300	Domain {domain} already in pending transfer state
2301	{domain} is not in pending transfer state
2302	Domain name already exists
2303	Contact {id} does not exists
2304	Object status prohibits operation
2304	domain is in pending transfer state
2304	domain is already in pending delete state
2304	Domain already in redemption period