Skip to content

API System Technical Requirements

The Structure Of A Domain Name

A Domain Name in the Registry is a textual string of the form <3rd level>.<SLD>.il, where:

  • .il is the ccTLD (Contry Code Top Level Domain).
  • <SLD>: is one of the following Second Level Domain Names:
    • (1) co, (2) org, (3) net, (4) muni, (5) ac
  • <3rd level>: a string that is comprised only of the following characters:
    • Lowercase Latin letters ('a' to 'z').
    • IDN letters ('א' to 'ת') including final forms (corresponding to Unicode Code - Points U+05D0 to U+05EA).
    • Digits ('0' to '9').
    • Hyphen ('-').
    • At-least 3 characters long.
    • At-most 64 characters long.
    • Does not start or end with a hyphen.
    • Does not contain two consecutive hyphens, except for Hebrew Domain Names in the standard A-Label form (xn--).

For example: in the Domain Name isoc.org.il, isoc is the 3rd level, org is the SLD, and il is the ccTLD.

It should be noted that there are additional requirements that may be imposed on the 3rd level string. These requirements are not technical in nature and are primarily derived from the Domain Name Allocation Rules. Being such, they are not relevant for the development of the API Client, but in any case messages sent as a result of such requirements not being met, will be standard API System messages.

Request

Registration Requests are sent as POST method, over HTTPS.

Sending a request using the curl command

curl \
    --header 'Content-Type: text/xml; charset=utf-8' \
    --cert certificate.crt --key certificate.key \
    --data @info.xml \
    https://api.register.isoc.org.il/v1/domain/check

Content of info.xml

<?xml version="1.0" encoding="UTF-8"?>
<epp>
    <command>
        <info>
            <domain:info>
                <domain:name>test1.co.il</domain:name>
            </domain:info>
        </info>
        <clTRID>DT-42</clTRID>
    </command>
</epp>

Sending the request

The address for sending the requests are:

  • Production: https://api.register.isoc.org.il/v1/
  • Test Environment: https://api.reg-test.isoc.org.il/v1/

The relative routing structure is according to the type of request:

/object/action

Object can be - domain / contact

Action can be - info / renew / create / update ...

For example

  • If the request is <domain:info> the routing will be /domain/info
  • If the request is <contact:create> the routing will be /contact/create

As mentioned, full path will be: https://api.register.isoc.org.il/v1/domain/info

Currently, for this version (3.0) we support the functionality of the following requests.

Content type

Request content need to be in XML format. The HTTP request need to include this header:

Content-Type: text/xml; charset=utf-8

XML

XML Case Sensitivity

XML is case sensitive. Unless specifically specified otherwise, case distinction MUST be kept.

XML File – General Structure

Every XML instance MUST begin with the declaration <?XML?>, indicating one of the identified character sets (UTF-8, ASCII-7 or ISO-8859-1) and XML version 1.0. All Registration Actions are to be included between the tags <epp> and </epp>.

<?xml version="1.0" encoding="UTF-8"?>
<epp xmlns="urn:ietf:params:ns:epp-1.0"
 xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
 xsi:schemaLocation="urn:ietf:params:xml:ns:epp-1.0 epp-1.0.xsd">
. . .
</epp>

Validation of XML Files

The Registry provides XML Schema files (xsd), to allow ARs to validate compatibility of syntax and semantics of Requests with the API System.

Using the Schema is recommended.

When using the schema, ALL Requests MUST be validated against the file: "epp.xsd". This file automatically imports all schemas required for the validation.

Schema files are available at: https://register.isoc.org.il/reg-reg/schema/Schema.tgz

API Client Request – general structure

API Client Request is of the following format:

<?xml version="1.0" encoding="UTF-8"?>
<epp xmlns="urn:ietf:params:xml:ns:epp-1.0">
    <command>
        <someaction> ... </someaction>
            <extension>
            ...
            </extension>
        <clTRID>AB-209876</clTRID>
    </command>
</epp>

Legend:

  • <command> ... </command>: Contains the Registration Action block. A Registration Action block is comprised of two blocks:
    • Standard EPP Block – between the tags <someaction>...</someaction>: Part of the Registration Action that contains Standard EPP XML code. The XML in the Standard EPP Block corresponds to the "command" part of EPP.
    • Extensions Block – between the tags <extension> ... </extension>: Implements ISOC-IL's Extensions to the Standard EPP XML code. Some IL Extensions are mandatory, as outlined in this document.
  • <clTRID> ... </clTRID> AR's transaction identifier. The identifier shall be of the following format: AR Code, followed by a hyphen, followed by a serial number larger than 0 and of up to 27 digits. For Example: "AB-209876". The identifier must be unique within the AR's range of identifiers. This identifier is not used by the API Server, and is returned in the API Server's response AS IS.

API Server response – general XML structure

API Server response is of the following format:

<?xml version="1.0" encoding="UTF-8"?>
<epp xmlns="urn:ietf:params:xml:ns:epp-1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-
instanc" xmlns:contact="urn:ietf:params:xml:ns:contact-1.0"
xmlns:domain="urn:ietf:params:xml:ns:domain-1.0" xmlns:isocil="http://www.isoc.org.il/xml/epp/isocil-
1.0" xsi:schemaLocation="urn:ietf:params:xml:ns:epp-1.0 epp-1.0.xsdurn:ietf:params:xml:ns:contact-1.0
contact-1.0.xsdurn:ietf:params:xml:ns:domain-1.0 domain-1.0.xsdhttp://www.isoc.org.il/xml/epp/isocil-
1.0">
    <response>
        <result code="1000">
            <msg> ... </msg>
            <value> ... </value>
        </result>
        <resData> ... </resData>
        <extension>
        ...
        </extension>
        <trID>
            <clTRID>BL-209876</clTRID>
            <svTRID>ISOCIL-AB716 20051117110800</svTRID>
        </trID>
    </response>
</epp>
Legend:

  • <response> Contains the API Server Response block.
  • <result> Contains details of the result of the processing of a Request, including:
    • A result code.
    • <msg> human readable message between the tags. Please refer to the following section for additional information.
    • <value> A set of values relevant to the Registration Action performed.
  • <resData> Contains specific information on the Object or Registration Action performed, e.g, the Object's identifier.
  • <trID> Comprised of two blocks, the combination of which creates a unique identifier of the transaction performed:
    • <clTRID> AR's identifier included in the Request.
    • <svTRID> A unique identifier generated by the API Server. The format of the identifier is: ISOC-IL-[AR Code][number] [Time Stamp].

Please refer to Appendix EPP Response Codes for a list of the response codes and their corresponding messages.

API Server response – the <msg> tag

The <msg> tag includes information in a human readable form. It also includes the Request ID (as defined in Registration Actions). The Request ID is also included in the Response Subject Line (see following section).

Where the result code corresponds to a denial of request which was handled manually in the Registry, additional information for the grounds for the denial will be included between the <msg> ... </msg> tags, denoting an "Error Message id(s)" followed by a code.

A short description of the message relating to the code is included in the <resData> block, between the tags <MailMsgs>.

For example:

...
<msg>Your request was denied (Error message(s) id(s): 400; domain requestid=D323860)</msg>
...
<resData>
 <mailMsgs>
    <isoc:mailmsg id="400">Incomplete/invalid holder data</isoc:mailmsg>
 </mailMsgs>
</resData>

Please refer to Appendix Error Message IDs for a complete description of the error message ids and their meaning.

API Server Response – Notification of failed request

In cases where the Request did not pass the registry validation, the response with the result of the processing of the Request will be sent back in the same connection by the API Server.

<?xml version="1.0" encoding="UTF-8"?>
<epp xmlns="urn:ietf:params:xml:ns:epp-1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instanc"
xmlns:contact="urn:ietf:params:xml:ns:contact-1.0" xmlns:domain="urn:ietf:params:xml:ns:domain-1.0"
xmlns:isocil="http://www.isoc.org.il/xml/epp/isocil-1.0" xsi:schemaLocation="urn:ietf:params:xml:ns:epp-1.0
epp-1.0.xsdurn:ietf:params:xml:ns:contact-1.0 contact-1.0.xsdurn:ietf:params:xml:ns:domain-1.0 domain-
1.0.xsdhttp://www.isoc.org.il/xml/epp/isocil-1.0">
    <response>
        <result code="3017">
            <msg>Domain Name is already registered</msg>
        </result>
        <trID>
            <clTRID>BL-5</clTRID>
            <svTRID>ISOCIL-BL1634 20051117110800</svTRID>
        </trID>
    </response>
</epp>

API Server Response – Notification of a successful request submission: Pending Status

In cases where the Request has been queued for processing, the initial response of the API Server following a successful submission of a Request will be a notification on the "Pending" status of the Request.

The "Pending" notification is for information purposes only and does not require an action by the Client.

The final response with the result of the processing of the request, can be obtained by <poll> requests.

<?xml version="1.0" encoding="UTF-8"?>
<epp xmlns="urn:ietf:params:xml:ns:epp-1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instanc"
xmlns:contact="urn:ietf:params:xml:ns:contact-1.0" xmlns:domain="urn:ietf:params:xml:ns:domain-1.0"
xmlns:isocil="http://www.isoc.org.il/xml/epp/isocil-1.0" xsi:schemaLocation="urn:ietf:params:xml:ns:epp-1.0
epp-1.0.xsdurn:ietf:params:xml:ns:contact-1.0 contact-1.0.xsdurn:ietf:params:xml:ns:domain-1.0 domain-
1.0.xsdhttp://www.isoc.org.il/xml/epp/isocil-1.0">
    <response>
        <result code="1001">
            <msg>Submission completed successfully (domain requestid=D204169)</msg>
        </result>
        <resData>
            <domain:creData>
                <domain:name>domain.co.il</domain:name>
            </domain:creData>
        </resData>
        <trID>
            <clTRID>BL-5</clTRID>
            <svTRID>ISOCIL-BL1634 20051117110800</svTRID>
        </trID>
    </response>
</epp>

API Server Response – Notification of a successful processing of a request: Command completed Status

In cases where the Request has been processed successfully, the response with the result of the processing of the Request will be sent back in the same connection by the API Server upon completion of the process.

<?xml version="1.0" encoding="UTF-8"?>
<epp xmlns="urn:ietf:params:xml:ns:epp-1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instanc"
xmlns:contact="urn:ietf:params:xml:ns:contact-1.0" xmlns:domain="urn:ietf:params:xml:ns:domain-1.0"
xmlns:isocil="http://www.isoc.org.il/xml/epp/isocil-1.0" xsi:schemaLocation="urn:ietf:params:xml:ns:epp-1.0
epp-1.0.xsdurn:ietf:params:xml:ns:contact-1.0 contact-1.0.xsdurn:ietf:params:xml:ns:domain-1.0 domain-
1.0.xsdhttp://www.isoc.org.il/xml/epp/isocil-1.0">
    <response>
        <result code="1000">
            <msg> Command completed successfully (domain requestid=D204169)</msg>
        </result>
        <resData>
            <domain:renData>
                <domain:name>domain.co.il</domain:name>
                <domain:expDate>2021-10-15T23:59:59Z</domain:expDate>
            </domain:renData>
        </resData>
        <trID>
            <clTRID>BL-5</clTRID>
            <svTRID>ISOCIL-BL1634 20051117110800</svTRID>
        </trID>
    </response>
</epp>

Non-XML (human readable) Mail sent by the API Server

Notifications in a human readable form, initiated by the Registry, e.g. warning of a request to respond to a Transfer request.

In those messages, the Subject Line begins with the string "[ILREG]".

Information on those Mail Messages can be found in Appendix Mail Messages.

The non-XML messages are sent to the AR Main Regular Mail Address, and to the email address of the AR main contact person registered with the Registry.