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

1. Check Contact availability

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.

URI: /contacts/:id/check
Request method: GET

Name	Description
id	Fully qualified domain name.

Request example:

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.

Response example:

 

2. Create Contact

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.

URI: /contacts/
Request method: PUT

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)

Request example:

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.

Response example:

3. Query Contact info

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

URI: /contacts/:id
Request method: GET

Name	Description
id	Fully qualified domain name.

Request example:

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).

Response example:

 

4. Update Contact

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).

URI: /contacts/:id
Request method: POST

Name	Description
id	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:

 

5. Delete Contact

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.

URI: /contacts/:id
Request method: DELETE

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