SRS Transactions ================ The SRS XML transactions below can be used by registrars to query and update the SRS. .. _DomainCreate: DomainCreate ------------ The DomainCreate transaction allows registrars to register a new .nz domain name. If the transaction is successful, the domain name is registered immediately. The domain is assigned an "Active" status and the Billing Process is invoked immediately. We recommend that you first read about the field definitions which will explain about the allowable values in the data described below. The DomainCreate element contains the following attributes and child elements: ===================== =================== ================ Attribute / Required Default val ===================== =================== ================ Term yes ActionId yes Delegate no "1" DomainName yes DomainNameUnicode no DomainNameLanguage no RegistrantRef no HandleId no yes no no no no no ===================== =================== ================ #. If no administrative contact details are provided the Registrant details are used as administrative contact details as well. #. If no technical contact details are provided the Registrar's technical contact details are used. The SRS supports internationalized domain names (IDNs). Domain names containing non-ASCII characters MUST use the Punycode encoding RFC3492 for the DomainName attribute, and provide the domain name in the original scripts in the DomainNameUnicode attribute. The DomainNameLanguage attribute may be used to provide a description of the original script and language for the domain name. The SRS supports Privacy. When registering a domain name, a registrar is able to specify the Privacy attribute for each of the Registrant :ref:`Contact`, Admin :ref:`Contact` and Technical :ref:`Contact` elements. If this field is not specified, it will default to '0' in DomainCreate transactions. A value other than '0' or '1' will result in an error being returned. The response to these transactions will include the Privacy="1" attribute and value if the privacy flag is set for the contact. Registering a new domain name: .. code-block:: xml create new domain .. code-block:: xml Registering a new internationalized domain name: .. code-block:: xml create new domain .. code-block:: xml Registering a new domain name with Privacy: .. code-block:: xml create new domain With privacy .. code-block:: xml Registering a new domain name with DNSSEC records: .. code-block:: xml 3FC2FB591B6089F454B90A529C760E3F92F28399 85DB78AF90EB23B5B346528482ABA500A445DDB40F5BE2F04911EE7CF7CF2335 .. code-block:: xml Registering a new domain name with Handles: .. code-block:: xml create new domain .. code-block:: xml Registering a new domain name with default Admin and Technical contact details .. code-block:: xml create new domain With default admin and technical contacts .. code-block:: xml .. _DomainUpdate: DomainUpdate ------------ The DomainUpdate transaction enables registrars to perform a number of update functions against domains they administer, including the option to cancel, uncancel, renew, delegate and generate new UDAIs. The DomainUpdate is also used to transfer a domain name from one registrar to another. These update functions can be performed one function at a time in separate DomainUpdate requests, or several functions can be combined into one request. Using DomainUpdate registrars can: * Cancel or Un-cancel a domain name by setting the Cancel attribute to either "1"or "0" respectively. * Auto-Cancel a domain name. A domain name can be cancelled immediately as mentioned above using the Cancel attribute. Alternatively a domain name can be set to be cancelled on it’s ’Billed Until date’ by setting the Term value to zero. Domain names do not automatically lapse at the end of their billing period; they are automatically renewed for the billing term specified by the registrar. Registration of a domain name has to be actively cancelled by the registrar and can only be cancelled upon request or where the registrant has not complied with their agreement with the registrar and cancellation is specified as a possible result. * Generate a new UDAI by setting the NewUDAI attribute to "1" . * Renew a domain name immediately , rather than waiting for the current billing period to end, by setting the Renew attribute to "1". The Term attribute value has to be provided if the Renew attribute is set. The Term attribute value will be added to the Billed Until date. * Auto-Renew a domain name by re-setting the Term attribute value. The domain name will be renewed on it’s ’Billed Until date’ using the value in the Term attribute. If sent in combination with the Renew="1" option then it is a normal renewal and the Billed Until date is updated immediately. * Transfer the management of a domain name to themselves by providing the correct UDAI. Other domain details may be changed in the same transaction. A domain name can be transferred while in PendingRelease. * Delegate the domain to appear in the .nz zone (DNS) by updating the Delegate attribute to "1". To remove the domain from the zone without canceling it set Delegate="0". * Update the registrant, administrative and technical contact information. * Set Privacy by specifying the Privacy attribute for each of the Registrant :ref:`Contact`, Admin :ref:`Contact` and Technical :ref:`Contact` elements. If this field is not specified, it will remain unchanged for DomainUpdate transactions. A value other than '0' or '1' will result in an error being returned. The response to these transactions will include the Privacy="1" attribute and value if the privacy flag is set for the contact (or the contacts that have changed if updating and FullResult is not specified). If the FullResult attribute is set to "0" only the updated fields are returned with the response. Otherwise all fields are returned. If the RegistrarId has changed, the old registrar is notified immediately of the transfer by a message sent by the SRS which is placed in the old registrar’s message queue, waiting to be received the next time it is polled. The message contains the domain name and the new registrar name. ======================== ==================== =================================================================== Attribute / Required Note / Default value ======================== ==================== =================================================================== Term no Renew no * To renew a domain name immediately * Boolean value "0" or "1" * Required Term value NewUDAI no * to request a new UDAI * boolean value "0" or "1" Cancel no * to change the status of domain name to Active or PendingRelease * boolean value UDAI no Required to transfer a domain name ActionID yes Delegate no RegistrantRef no FullResult no "1" HandleId no length: between 3 - 16 characters yes no no no no no no ======================== ==================== =================================================================== 1. If the administrative contact details are deleted (eg attribute with no elements) the Registrant details are used as administrative contact details as well. 2. If the technical contact details are deleted (eg attribute with no elements) the Registrar's technical contact details are used. .. note:: When a domain name transfers to a new registrar, the privacy flag of any contact details that are not explicitly specified in the DomainUpdate transaction will be honoured. .. warning:: The following attributes are only used by the registry: .. csv-table:: :header: "Attribute / ", "Required", "Note / Default value" :delim: | Lock | no | Used to lock or unlock a domain ConvertContactsToHandles | no | Generate new contact handles during a transfer in and use them instead of embedded contacts Cancel a domain: .. code-block:: xml sample-domain-test.org.nz .. code-block:: xml Uncancel a domain: .. code-block:: xml sample-domain-test.org.nz .. code-block:: xml Update the domain and set the delegation status on hold: .. code-block:: xml internetnz-change-delegate-domain.co.nz .. code-block:: xml Request a new UDAI for a domain: .. code-block:: xml internetnz-sample-newudai.co.nz .. code-block:: xml Renew a domain for 3 months immediately: .. code-block:: xml internetnz-sample-renew3.co.nz .. code-block:: xml Transfer a domain to registrar 90: .. code-block:: xml internetnz-sample-transfer.co.nz .. code-block:: xml Update most fields for a single domain: .. code-block:: xml internetnz-update-everything-domain.co.nz 3FC2FB591B6089F454B90A529C760E3F92F28399 85DB78AF90EB23B5B346528482ABA500A445DDB40F5BE2F04911EE7CF7CF2335 audit_this .. code-block:: xml Update a domain to use handles for RegistrantContact AdminContact and TechnicalContact. .. code-block:: xml internetnzhandles.nz update domain to use internetnz0001 handles .. code-block:: xml Update a domain name to use default Admin and Technical contact details. .. code-block:: xml test-admin.nz update domain to use default Admin and Technical Contacts .. code-block:: xml Adding Privacy to a Registrant contact .. code-block:: xml privacy-testdomain.co.nz .. code-block:: xml Update a domains nameservers and glue records .. code-block:: xml internetnz-sample-nameserver.co.nz Change Nameserver and IP .. code-block:: xml .. note:: Specifying the NameServers element will effectively replace all name servers for the domain. .. _DomainDetailsQry: DomainDetailsQry ---------------- The DomainDetailsQry provides registrars with the functionality to perform a variety of different queries about domains within the SRS database. It allows partial field matching, date dependencies using date range fields, and control over which data fields are returned. Registrars can only query the domain names and the history of the domain names for which they are the current registrar. When a registrar tries to retrieve historical information from period that the domain name was not registered with them or a domain name that has been released then no results are returned. To view history for a domain (that you are the current registrar of) you can include the ShowHistory=”1” attribute in the DomainDetailsQry request. The returned response will show all the historic data for the domain in question during the most recent period the domain was under your control as the registrar of the domain. .. note:: History on domains that have been released will not be returned. Wild-card ("*" for full words or more than two letters and "?" for single letters) searching is provided by the DomainDetailsQry. The DomainDetailsQry element contains the following attributes and child elements: ========================== ==================== =================================================================== Attribute / Required Note / Default value ========================== ==================== =================================================================== Status no Active and PendingRelease Term no Delegate no CountResults no MaxResults no 100 SkipResults no 0 RegistrantRef no ShowHistory no 0 no no no no no no no no no no ========================== ==================== =================================================================== FieldList ~~~~~~~~~ The FieldList element contains a list of parameters that define what information is to be returned for each domain name. Each field parameter can have the value of "0" or "1". If the parameter is set to "1" the corresponding field information is returned with the response. If the parameter is set to "0" then no information is returned. ========================= ================================================= Parameter Description ========================= ================================================= RegistrarId Registrar Identification number RegistrarName Name of registrar Status Status of domain name (active or pending release) LockedDate Date and time domain name was locked CancelledDate Date and time domain name was cancelled Delegate Boolean value to indicate delegation in DNS NameServers List of name servers of domain name RegistrantRef Registrant reference if provided RegistrantContact Registrant contact details AdminContact Administrative contact details TechnicalContact Technical contact details DNSSEC DNSSEC details for domain Term Billing Term EffectiveFrom Date a domain record was replaced by a new record (-> create or update transaction) BilledUntil Date and time domain name is/was billed to RegisteredDate Date and time domain name was registered LastActionId Unique ID of the last writing transaction (create or update of domain name) AuditText Optional reference provided by user in create or update transaction ChangedByRegistrarId Registrar Id of who updated the domain name ========================= ================================================= A query, that requests the history of the Domain name and all its details: .. code-block:: xml .. code-block:: xml A simple DomainDetailsQry that uses the CountResults to count the domains registered under RegistrarId 90 that begin with "a" using the "*" wildcard after the "a": .. code-block:: xml .. code-block:: xml .. _Whois: Whois ----- The Whois transaction is used to retrieve the public details associated with a domain name from the SRS. This information consists mainly of contact details, relevant dates, and nameserver details. If the domain name is not registered the available status is returned. The Whois element contains the following attributes: ========================== ==================== =================================================================== Attribute / Required Note / Default value ========================== ==================== =================================================================== DomainName yes SourceIP no Used to pass on the IP address of the originating query source for abuse detection/restrictions FullResult no ========================== ==================== =================================================================== Whois Privacy ~~~~~~~~~~~~~ Information returned from a Whois SRS query transaction will not return the following address fields if the contact privacy flag is set: * Address1 * Address2 * City * Province * PostalCode * Phone * Fax .. note:: the Privacy attribute will not be returned by the Whois SRS transaction. This is regardless of which registrar makes the request. Whois request to check availability: .. code-block:: xml .. code-block:: xml Whois request to query all publicly available domain name details: .. code-block:: xml .. code-block:: xml Whois request to query all publicly available domain name details with Registrant Privacy Flag set: .. code-block:: xml .. code-block:: xml Whois to query of all publicly available domain name details, result when Registrant Privacy Flag is not set : .. code-block:: xml Whois request to perform multiple availability checks: .. code-block:: xml .. code-block:: xml .. _UDAIValidQry: UDAIValidQry ------------ A UDAIValidQry validates that a given UDAI is correct and belongs to a registered domain name. Registrars are able to validate the UDAI for any domain name, regardless of whether they are the designated registrar for that domain name. A boolean value "1" in the response confirms the validity of a UDAI. A valid="0" means a UDAI is not valid. The UDAIValidQry element contains the following attributes: ========================== ==================== =================================================================== Attribute / Required Note / Default value ========================== ==================== =================================================================== DomainName yes UDAI yes ========================== ==================== =================================================================== Validate a UDAI for a domain name: .. code-block:: xml .. code-block:: xml .. _GetMessages: GetMessages ----------- A message is the answer given by the SRS in response to a single transaction, this may be an error message or a successful response. The GetMessages transaction allows registrars to poll for messages they may have been unaware of or to confirm the status of a specific transaction that had been sent previously. Messages can be actioned by the registry on the behalf of registrars, or actioned by other registrars transferring away domains. To query for these transactions, registrars need to set the OriginatingRegistrarId field to a special value OTHERS and with RecipientRegistrarId set to the registrar's own RegistrarId. All the messages originating from the registry and other registrars within the TransDateRange (if specified) are returned. Registrars only have access to messages that have been generated for them. If a GetMessages request is sent with RecipientRegistrarId and the OriginatingRegistrarId set to a registrar's own RegistrarId, all messages originating from that RegistrarId within the TransDateRange (if specified) are returned. The full transaction identifier is the combination of the registrar that initiated it (the originating registrar) and the ActionId that was given in the original transaction. QueueMode ~~~~~~~~~ The QueueMode is an optional attribute that is by default set to "0". When a GetMessages request is sent with QueueMode="1" the transaction returns all messages that match the GetMessages criteria AND that have not been acknowledged by the AckMessages transaction yet. Omitting the QueueMode attribute returns all messages matching the GetMessages criteria no matter if a specific message had been acknowledged via the AckMessage transaction or not. ~~~~~~~~~~~~ The TypeFilter element has an attribute 'Type' which can have the value 'third-party' or 'server-generated-data' . Using only the value 'third-party' returns similar results as using the 'OTHERS' value for the OriginatingRegistrarId attribute. However used in combination with 'server-generated-data' the transaction returns all messages that match either value (third-party OR server-generated-data). While using the 'OTHERS' value in combination with 'server-generated-data' will only return transactions that caused the server to generate data AND that have been processed for the registrar but not by themselves (e.g. domain transfer to the registrar processed by the registry). Currently the only relevant 'server-generated-data' is the UDAI, i.e. transactions where a UDAI is generated will be returned when querying with the filter 'server-generated-data' (domain create, domain transfer, registrant update) . The GetMessages element contains the following attributes and child elements: ========================== ==================== ==================================================================== Attribute / Required Note / Default value ========================== ==================== ==================================================================== ActionId no* RecipientRegistrarId no Is the registrar id that manages domains at the time that they are updated (you always set this to your registrar ID) OriginatingRegistrarId no Is the registrar id that sends the requests that update the domains eg your Registrar ID, or the Registry and the RenewDomains job or other Registrars that transfer domains away from you. You set this to your registrar ID to get just the messages that relate to updates to domains that you have done. For the GetMessages request you set OriginatingRegistrarId to "OTHERS" to see all the messages that relate to updates of domains that you manage performed by other registrars (transfers away) or by the Registry. MaxResults no "100" SkipResults no "0" QueueMode no "0" no* no ========================== ==================== ==================================================================== .. note:: Either an ActionId or a TransDateRange must be provided GetMessages request which returns messages between the specified dates: .. code-block:: xml .. code-block:: xml GetMessages request which returns a message with a specific ActionId: .. code-block:: xml .. code-block:: xml GetMessages request which returns messages originating from other registrars: .. code-block:: xml .. code-block:: xml GetMessages request with QueueMode, aTransDateRange and FilterType Gives back all transactions for registrar 90 generated in the specified time frame that have not been acknowledged and that have been generated by a transaction run by another registrar (e.g. transfer away, renewal domain job, release domain job) as well as all transactions run by registrar 90 that caused the system to generate data (e.g correct DomainCreate generating an UDAI): .. code-block:: xml .. code-block:: xml .. _AckMessage: AckMessage ---------- In the SRS, 'messages' (which are actually responses) are kept and can actually be queried unlimited times. The AckMessage transaction allows the EPP concept of acknowledging messages that have been received from the system to make sure messages are pulled only once. Once a message has been acknowledged with the AckMessage transaction it will no longer be returned by the GetMessages transaction if the QueueMode attribute is set in the GetMessage query. ========================== ==================== =================================================================== Attribute / Required Note / Default value ========================== ==================== =================================================================== ActionId yes TransId yes ActionId of the transaction to be acknowledged OriginatingRegistrarId yes ID of registrar who generated transaction ========================== ==================== =================================================================== Acknowledges the message with ActionId (TransId) 'SomeUniqueID'. The field 'ActionId' holds the value for the actual AckMessage transaction as AckMessage is also a writing action and all writing transactions in the SRS require an ActionId: .. code-block:: xml .. code-block:: xml .. _ActionDetailsQry: ActionDetailsQry ---------------- The ActionDetailsQry retrieves the original XML (RawRequest and RawResponse strings) of a request sent by a registrar. It is identified by the ActionId. Registrars are only returned transactions performed by them, or performed by the Registry on their behalf. ========================== ==================== =================================================================== Attribute / Required Note / Default value ========================== ==================== =================================================================== ActionId yes ========================== ==================== =================================================================== Fetch original transaction request and response for a given actionID: .. code-block:: xml .. code-block:: xml .. _HandleCreate: HandleCreate ------------ The HandleCreate transaction allows registrars to create a new SRS contact handle. The SRS handle is generated immediately and can be used in DomainCreate, DomainUpdate or RegistrarUpdate transactions. Transaction elements and attributes for a =============== ========== Name Required =============== ========== HandleId yes ActionId yes Name yes Email yes Privacy no yes yes no AuditText no =============== ========== HandleCreate with all available fields populated: .. code-block:: xml Create a Handle .. code-block:: xml HandleCreate with Privacy .. code-block:: xml Create a Handle .. code-block:: xml .. _HandleUpdate: HandleUpdate ------------ HandleUpdate allows registrars to update existing handles. If handles are used and the registrant name for several domain names is to be updated, we recommend to create a new handle and perform a DomainUpdate request for the relevant domain names to associate the new handle with the domains. This approach makes changes more visible and therefore registrars have more control over the actual changes. Also with an HandleUpdate orphaned handles that are no longer required can be deleted. Deletion is only possible if a handle is not associated with any domain name or registrar object. Otherwise an error will be returned. Updates: * All fields but the HandleId can be updated with a HandleUpdate transaction. An update of handle details results in the change of contact details of all domain names the handle is linked to. Note: If a handle is linked to the Registrant Contact of one or more domain names the update of the handle's name field results in a registrant change of the domain name(s). * If a SRS handle is updated linked to a domain name that has the status PendingRelease the contact details of that domain name will be updated. This behavior currently differs from a DomainUpdate for a domain name with status PendingRelease. Trying to update the contact details via a DomainUpdate returns an error advising only active domain names can be updated. * Domain names locked by the registry will not be effected by any HandleUpdates for the time they are locked. The system will keep a 'snapshot' of domain details as at the time of the lock. If a HandleUpdate occurs while a domain name is locked the domain name will only be updated with the new handle details once the domain name is unlocked (unless the domain name gets updated by the registry as result of any dispute resolution actions) Transaction elements and attributes for ================ ======== ========== Name Required Default ================ ======== ========== HandleId yes ActionId yes Delete no "0" (no) Name yes Email yes Privacy no "0" no no no AuditText no ================ ======== ========== HandleUpdate that updates Postal and Phone details: .. code-block:: xml Update a Handle .. code-block:: xml HandleUpdate for Privacy .. code-block:: xml Update a Handle .. code-block:: xml HandleUpdate that deletes a handle: .. code-block:: xml Delete a Handle .. code-block:: xml .. _HandleDetailsQry: HandleDetailsQry ---------------- Similar to the DomainDetailsQry transaction the HandleDetailsQry enables registrars to do a variety of different queries on current and historical data of handles. Registrars can only query handles and history of handles that are/were managed by them. The HandleDetailsQry provides the functionality and flexibility for a variety of different uses. It allows partial field matching and date dependencies using date range fields. Wildcards ("*" for full words and more than two letters and "?" for single letters) can be used for the attributes. Transaction elements and attributes for ================== ======== ======== Name Required Default ================== ======== ======== CountResults no "0" MaxResults no "100" SkipResults no "0" HandleIdFilter no SearchDateRange no ChangedInDateRange no ContactFilter no ================== ======== ======== Simple HandleDetailsQry that gives back the first 100 handles existing with registrar 90: .. code-block:: xml .. code-block:: xml Simple HandleDetailsQry that counts all handles existing with registrar 90: .. code-block:: xml .. code-block:: xml HandleDetailsQry searching for SRS handles that have a name contact starting with "Registrant" and Address line 1 ending with "Address": .. code-block:: xml .. code-block:: xml HandleDetailsQry of a single handle showing privacy .. code-block:: xml customer-1000 .. code-block:: xml .. _RegistrarAccountQry: RegistrarAccountQry ------------------- Registrars are able to query all their Billing Transactions in the SRS by using the RegistrarAccountQry. By providing search criteria, registrars are able to filter the query results to fit their needs. Registrars can query: * All transactions in a date range * All details relating to a specific domain * All details relating to a single customer of the Registrar (identified by the Registrant Customer Reference - if these details have been provided for the domain name) * Any combination of the above Wild-card (*) searching is possible for the DomainName field. Please note that this calculation is performed each time the query is executed, and if the database changes between executions, it is possible that transactions are missed or duplicated in the result. ========================== ==================== =================================================================== Attribute / Required Note / Default value ========================== ==================== =================================================================== DomainName no RegistrantRef no MaxResults no "100" SkipResults no "0" TransDateRange no ========================== ==================== =================================================================== A RegistrarAccountQry to find the account details of one domain name. (Use the wildcard (*) to find all acount details of the registrar): .. code-block:: xml .. code-block:: xml A RegistrarAccountQry using the TransDateRange to search for all account information between the specified dates (in this case one month): .. code-block:: xml .. code-block:: xml The following set of Billing details are returned: ================================== =================================================== Attribute / Details ================================== =================================================== RecipientRegistrarId The unique identifier for the user that the response is returned to OrigRegistrarId The unique identifier for the user that submitted the request to the SRS Amount A numeric currency value. The amount of money attached to the billing transaction BillingTerm An integer value that shows the number of months of payment for which the billing transaction was issued DomainName The domain name that the billing transaction relates to RegistrantRef The customer identifier, a reference that may be assigned to the registrant by the registrar (has to be provided during DomainCreate or DomainUpdate) RegistrarId The identifier of the registrar that manages the domain that the billing amount relates to TransStatus A text string that shows the status of the billing transaction (always "Pending-Confirmation" as a billing transaction is always pending at the time it was created due to grace periods) Type The type of transaction that the billing amount relates to (e.g. ”Create”, ”Renew”) TransDate The date on which the billing transaction occurred BilledPeriodStart Contains the start date of the billing period to which the transaction belongs BilledPeriodEnd Contains the end date of the billing period to which the transaction belongs ================================== =================================================== .. _RegistrarDetailsQry: RegistrarDetailsQry ------------------- The RegistrarDetailsQry retrieves information of a registrar contact details stored in the SRS. A registrar is only allowed to query for their own data. The ResultsDateRange causes the results to return multiple records for the registrar, describing all the changes that the registrar went through during the effective period. This is an optional parameter. Omitting it will cause only the latest data for the registrar that matches the filters to be returned. ========================== ==================== =================================================================== Attribute / Required Note / Default value ========================== ==================== =================================================================== ResultDateRange (From, To) no current date ========================== ==================== =================================================================== Return all current details for a domain: .. code-block:: xml .. code-block:: xml .. _RegistrarUpdate: RegistrarUpdate --------------- The RegistrarUpdate transaction enables registrar to update their contact details. All but the following fields can be updated by the registrar: * 2LDs * public key * access role list * Registrar Name * Registrar Accounting Reference If a you want us to update or add another public key please contact registry@internetnz.net.nz A registrar's DefaultTechnicalContact details are used for all domain names the registrar administers which have no other technical contact specified. ========================== ==================== =================================================================== Attribute / Required Note / Default value ========================== ==================== =================================================================== ActionId yes RegistrarPublicContact no RegistrarSRSContact no DefaultTechnicalContact no URL no ========================== ==================== =================================================================== Example: .. code-block:: xml .. code-block:: xml