Knowledge Base

REST API

Introduction Session handling Domain management Contact management Check Contact availability Create Contact Query Contact info Update Contact Delete Contact Response codes Host management Message queue Collections

Other sections

Registrars Domains EPP Gateway

Contact management

The management of contacts via the REST API Gateway allows for easy checking, creation, deleting, and updating of domain contact handles.

GET Check Contact availability

GET /contacts/:id/check

Contact check command is used to determine if a contact exists. It provides a hint that allows a client to anticipate the success or failure of provisioning, changing or deleting an object.

Command provide possibility to check one(1) contact per request.

NameDescription
idFully qualified domain name.

After successful request, response will contain following elements:

  • avail – identify if contact ID is available for usage as ID in new contact 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.
Request Example 
GET /contacts/ABC12345/check HTTP/1.1
Host: apihost
Content-Type: application/json
Api-Version: 1.0
Api-ClientTransactionId: 9a6c67e4-d666-54a8-9465-4847bee812e2
Api-ClientToken: 1a2B3C4d5e6F
Response Example 
HTTP/1.1 200 OK
Date: Tue, 01 Jan 2014 00:00:01 GMT
Server: Apache/2.2.15 (CentOS)
X-Powered-By: PHP/5.4.11
Connection: close
Transfer-Encoding: chunked
Content-Type: application/json

{
    "avail": 1,
    "code": 1000,
    "message": "OK",
    "cltrid": "9a6c67e4-d666-54a8-9465-4847bee812e2",
    "svtrid": "3574e2c0-a4cc-4655-aaec-02d891a2b7df",
    "time": 0.0075540542602539
}

PUT Create Contact

PUT /contacts/

Create contact command is supposed to be used to create Contact object.

Contact object is used to identify registrant, administrative, technical and/or billing contact for domain.

Request body contain elements:

  • id – unique identifier for the contact. If value is empty – ST Registry will generate new ID.
  • postalInfo – may contain one or two elements with address information. There is possibility to use element one of two types (or both) – “int” and/or “loc”. Usage of two elements of same type is disallowed. type=”int” – text only in Latin. type=”loc” – text on national language in UTF-8. postalInfo include following subelements: name – name (obligatory element). org – organisation (optional). addr – address, contain of subelements: street – up to 3 string (optional). city – city (optional). sp – province (optional). pc – postal code (optional). cc – country code according to the ISO 3166.
  • voice – telephone number (optional). Contact telephone number structure is derived from structures defined in [ITU.E164.2005]. Telephone numbers described in this mapping are character strings that MUST begin with a plus sign (“+”, ASCII value 0x002B), followed by a country code defined in [ITU.E164.2005], followed by a dot (“.”, ASCII value 0x002E), followed by a sequence of digits representing the telephone number. An optional “x” attribute is provided to note telephone extension information.
  • fax – fax number (optional). Fax number format requirements are identical to the <contact:voice>.
  • email – email address (obligatory element).
  • authInfo/pw – AuthInfo (also known as AuthCode or EPPCode). If element is empty then ST Registry will generate it automatically. Requirements for AuthInfo: minimum length – 6 symbols maximum length – 16 symbols both upper and lower case should be used should include digit(s)

After successful request, response will contain following elements:

  • creData – collection of short details for newly created contact.
  • creData/id – ID of newly created contact.
  • creData/crDate – date and time when contact was created.
  • 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.
Request Example 
PUT /contacts HTTP/1.1
Host: apihost
Content-Type: application/json
Api-Version: 1.0
Api-ClientTransactionId: 9a6c67e4-d666-54a8-9465-4847bee812e2
Api-ClientToken: 1a2B3C4d5e6F

{
    "id": "ABC-123",
    "voice": "+1.12312332",
    "fax": "+1.123123321",
    "email": "contact@my.domain.st",
    "postalInfo": {
        "int": {
            "name": "contact name",
            "org": "contact organization",
            "addr": {
                "street": [
                    "street1",
                    "street2",
                    "street3"
                ],
                "city": "contact City",
                "pc": "11011",
                "cc": "US",
                "sp": "province"
            }
        }
    },
    "authInfo": {
        "pw": "53e231D23948d"
    }
}
Response Example 
HTTP/1.1 200 OK
Date: Tue, 01 Jan 2014 00:00:01 GMT
Server: Apache/2.2.15 (CentOS)
X-Powered-By: PHP/5.4.11
Connection: close
Transfer-Encoding: chunked
Content-Type: application/json

{
    "creData": {
        "id": "ABC-123",
        "crDate": "2014-01-01T13:09:06+00:00"
    },
    "code": 1000,
    "message": "OK",
    "cltrid": "9a6c67e4-d666-54a8-9465-4847bee812e2",
    "svtrid": "3574e2c0-a4cc-4655-aaec-02d891a2b7df",
    "time": 0.0075540542602539
}

GET Query Contact info

GET /contacts/:id

Query contact command is used to retrieve complete information about Contact object.

NameDescription
idFully qualified domain name.

After successful request, response will contain following elements:

  • id – unique identifier for the contact.
  • postalInfo – may contain one or two elements with address information – “int” and/or “loc”. type=”int” – text only in Latin. type=”loc” – text on national language in UTF-8. postalInfo include following subelements: name – name. org – organisation. addr – address, contain of subelements: street – up to 3 string. city – city. sp – province. pc – postal code. cc – country code according to the ISO 3166.
  • voice – telephone number. Contact telephone number structure is derived from structures defined in [ITU.E164.2005]. Telephone numbers described in this mapping are character strings that MUST begin with a plus sign (“+”, ASCII value 0x002B), followed by a country code defined in [ITU.E164.2005], followed by a dot (“.”, ASCII value 0x002E), followed by a sequence of digits representing the telephone number. An optional “x” attribute is provided to note telephone extension information.
  • fax – fax number. Fax number format requirements are identical to the <contact:voice>.
  • email – email address.
  • authInfo/pw – AuthInfo (also known as AuthCode or EPPCode).
Request Example 
GET /contacts/ABC-123 HTTP/1.1
Host: apihost
Content-Type: application/json
Api-Version: 1.0
Api-ClientTransactionId: 9a6c67e4-d666-54a8-9465-4847bee812e2
Api-ClientToken: 1a2B3C4d5e6F
Response Example 
HTTP/1.1 200 OK
Date: Tue, 01 Jan 2014 00:00:01 GMT
Server: Apache/2.2.15 (CentOS)
X-Powered-By: PHP/5.4.11
Connection: close
Transfer-Encoding: chunked
Content-Type: application/json

{
  "info": {
    "id": "ABC-123",
    "voice": "+1.12312332",
    "fax": "+1.123123321",
    "email": "contact@my.domain.st",
    "clID": "CliendID",
    "crID": "ClientID",
    "crDate": "2014-01-01T13:09:06+00:00",
    "postalInfo": {
      "int": {
        "name": "contact name",
        "org": "contact organization",
        "addr": {
          "street": [
            "street1"
          ],
          "city": "contact City",
          "pc": "11011",
          "cc": "US",
          "sp": "province"
        }
      }
    },
    "authInfo": {
      "pw": "AbC123456"
    }
  },
  "code": 1000,
  "message": "OK",
  "cltrid": "53e2417c5c2f9",
  "svtrid": "9b77cfab-8cf1-4df5-afca-c6f15c1179f7",
  "time": 0.0031960010528564
}

POST Update Contact

POST /contacts/:id

Contact update command is supposed to be used to update Contact object details. Only object sponsor/owner may update it.

Command request body may contain elements:

  • add – optional element. Contain of elements which should be added to the object.
  • rem – optional element. Contain of elements which should be removed from the object.
  • chg – optional element. Contain of elements which should be updated.

Contact update command should include at least one of element(s): add, rem, chg.

“add” and “rem” elements contain the following child elements:

  • One or more “status” elements that contain status values to be associated with or removed from the object. When specifying a value to be removed, only the attribute value is significant; element text is not required to match a value for removal.

“chg” element contains the following OPTIONAL child elements. At least one child element MUST be present:

  • postalInfo – may contain one or two elements with address information – “int” and/or “loc”. type=”int” – text only in Latin. type=”loc” – text on national language in UTF-8. postalInfo include following subelements: name – name. org – organisation. addr – address, contain of subelements: street – up to 3 string. city – city. sp – province. pc – postal code. cc – country code according to the ISO 3166.
  • voice – telephone number. Contact telephone number structure is derived from structures defined in [ITU.E164.2005]. Telephone numbers described in this mapping are character strings that MUST begin with a plus sign (“+”, ASCII value 0x002B), followed by a country code defined in [ITU.E164.2005], followed by a dot (“.”, ASCII value 0x002E), followed by a sequence of digits representing the telephone number. An optional “x” attribute is provided to note telephone extension information.
  • fax – fax number. Fax number format requirements are identical to the <contact:voice>.
  • email – email address.
  • authInfo/pw – AuthInfo (also known as AuthCode or EPPCode).
NameDescription
idFully qualified domain name.

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.
Request Example 
POST /contacts/ABC-123 HTTP/1.1
Host: apihost
Content-Type: application/json
Api-Version: 1.0
Api-ClientTransactionId: 9a6c67e4-d666-54a8-9465-4847bee812e2
Api-ClientToken: 1a2B3C4d5e6F

{
    "chg": {
        "postalInfo": {
            "int": {
                "name": "contact name",
                "org": "contact organisation",
                "addr": {
                    "street": [
                        "street1",
                        "street2",
                        "street3"
                    ],
                    "city": "contact City",
                    "pc": "11011",
                    "cc": "US",
                    "ps": "province"
                }
            }
        },
        "voice": "+1.12312332",
        "fax": "+1.123123321",
        "email: "contact@my.domain.st",
        "authInfo": {
            "pw": "DomainPassw0rd"
        }
    }
}
Response Example 
HTTP/1.1 200 OK
Date: Tue, 01 Jan 2014 00:00:01 GMT
Server: Apache/2.2.15 (CentOS)
X-Powered-By: PHP/5.4.11
Connection: close
Transfer-Encoding: chunked
Content-Type: application/json

{
    "code": 1000,
    "message": "OK",
    "cltrid": "9a6c67e4-d666-54a8-9465-4847bee812e2",
    "svtrid": "3574e2c0-a4cc-4655-aaec-02d891a2b7df",
    "time": 0.0075540542602539
}

DELETE Delete Contact

DELETE /contacts/:id

Contact delete command is supposed to be used to delete Contact object. Only object sponsor/owner may delete it.

If contact have a status “clientDeleteProhibited” or “serverDeleteProhibited” then <contact:delete> request will be rejected. Also, request will be rejected if contact is linked with another object in a Registry repository.

NameDescription
idFully qualified domain name.

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.
Request Example 
DELETE /contacts/ABC-123 HTTP/1.1
Host: apihost
Content-Type: application/json
Api-Version: 1.0
Api-ClientTransactionId: 9a6c67e4-d666-54a8-9465-4847bee812e2
Api-ClientToken: 1a2B3C4d5e6F
Response Example 
HTTP/1.1 200 OK
Date: Tue, 01 Jan 2014 00:00:01 GMT
Server: Apache/2.2.15 (CentOS)
X-Powered-By: PHP/5.4.11
Connection: close
Transfer-Encoding: chunked
Content-Type: application/json

{
    "code": 1000,
    "message": "OK",
    "cltrid": "9a6c67e4-d666-54a8-9465-4847bee812e2",
    "svtrid": "3574e2c0-a4cc-4655-aaec-02d891a2b7df",
    "time": 0.0075540542602539
}

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 contact related operations.

Response codeMessage
1000Command completed successfully
2003Missing contact id
2003Missing contact:postalInfo:name
2003Missing contact:postalInfo
2004Abstract client and object identifier type minLength value=3, maxLength value=16
2005Invalid contact:postalInfo:name; Name value length must be grater than 5 and do not start with special chars like dot, hyphen and comma
2005Invalid contact:postalInfo:org; Organization value length must be grater than 2 and do not start with special chars like dot, hyphen and comma
2005Invalid contact:postalInfo:addr:street; Street value length must be grater than 2 and do not start with special chars like dot, hyphen and comma
2005Invalid contact:postalInfo:city; City value length must be grater than 1 and do not start with special chars like dot, hyphen and comma
2005Invalid contact:postalInfo:sp; Province value length must be grater than 1 and do not start with special chars like dot, hyphen and comma
2005Invalid contact:postalInfo:pc; Postal code value have invalid format
2005Invalid contact:postalInfo:cc; Country code should be according to ISO 3166
2005Phone format is +1.123456789 (+[country_code].[regional_code][phone_number])
2005Email validation failed
2203Operation not permitted; Contact object not in client repository
2302Contact ID already exists
2303contact:id does not exists
2305Object association prohibits operation