API System Technical Requirements

The Structure Of A Domain Name under .il Registry⚓

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 3^rd 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 3^rd 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.

The Structure Of A Hebrew Domain Name under ישראל. Registry⚓

Around September 2022, the ISOC-IL registry will start supporting the new ccTLD “ישראל” for Hebrew domain names.

ישראל. [ascii: .xn--4dbrk0ce] is the ccTLD (Contry Code Top Level Domain).

A Hebrew Domain Name in the Registry is a textual string of the form <2nd level Domain Name>.ישראל or a textual string of the form <3rd level Domain Name>.<SLD>.ישראל.

Form of <2nd level Domain Name>.ישראל⚓

For example, in the Domain Name איגודהאינטרנט.ישראל

איגודהאינטרנט is the 2^nd level Domain Name.

ישראל is the ccTLD level Domain Name.

Form of <3rd level Domain Name>.<SLD>.ישראל⚓

In addition, 3^rd level Domain Names will also be allocated, within a limited number of 2^nd level Domain Names, as follows:
- <SLD>: is one of the following Second Level Domain Names:
  - (1) ישוב.ישראל [ascii: xn--5dbhl8d.xn--4dbrk0ce]
  - (2) אקדמיה.ישראל [ascii: xn--4dbgdty6c.xn--4dbrk0ce]
For example, in the Domain Name משרד.אקדמיה.ישראל

משרד is the 3^rd level Domain Name

אקדמיה is the 2^nd level Domain Name.

ישראל is the ccTLD level Domain Name.

For more info check appendix with rules for Hebrew domain names.

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/
- See The Test Environment page for more details.

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.

Domain
- Create
- Update
- Renew
- Reassign
- Transfer
- Delete
- Info
- Check
- Cancel
Contact
- Create
- Update
- Info
- Delete
Domain + Contact:
- Poll - Since this action applies for both objects path is: https://api.register.isoc.org.il/v1/poll

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> ... </code>
            <msg> ... </msg>
        </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:
- <code> Response code of the API Server.
- <msg> human readable message between the tags. Please refer to the following section for additional information.
<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>
            <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</code>
            <msg>Submission completed successfully (domain requestid=D204169)</msg>
        </result>
        <resData>
            <domain:creData>
                <domain:name>domain.co.il</domain:name>
                <domain:requestID>204169</domain:requestID>
            </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</code>
            <msg>Command completed successfully (domain requestid=D204169)</msg>
        </result>
        <resData>
            <domain:renData>
                <domain:name>domain.co.il</domain:name>
                <domain:requestID>204169</domain:requestID>
                <domain:exDate>2021-10-15T23:59:59.000Z</domain:exDate>
            </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 about blocked certificate.

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.

API System Technical Requirements

The Structure Of A Domain Name under .il Registry⚓

The Structure Of A Hebrew Domain Name under ישראל. Registry⚓

Form of `<2nd level Domain Name>.ישראל`⚓

Form of `<3rd level Domain Name>.<SLD>.ישראל`⚓

Request⚓

Sending the request⚓

Content type⚓

XML⚓

XML Case Sensitivity⚓

XML File – General Structure⚓

Validation of XML Files⚓

API Client Request – general structure⚓

API Server response – general XML structure⚓

API Server response – the `<msg>` tag⚓

API Server Response – Notification of failed request⚓

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

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

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

API System Technical Requirements

The Structure Of A Domain Name under .il Registry⚓

The Structure Of A Hebrew Domain Name under ישראל. Registry⚓

Form of <2nd level Domain Name>.ישראל⚓

Form of <3rd level Domain Name>.<SLD>.ישראל⚓

Request⚓

Sending the request⚓

Content type⚓

XML⚓

XML Case Sensitivity⚓

XML File – General Structure⚓

Validation of XML Files⚓

API Client Request – general structure⚓

API Server response – general XML structure⚓

API Server response – the <msg> tag⚓

API Server Response – Notification of failed request⚓

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

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

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

Form of `<2nd level Domain Name>.ישראל`⚓

Form of `<3rd level Domain Name>.<SLD>.ישראל`⚓

API Server response – the `<msg>` tag⚓