Knowledge Base

REST API

Introduction Session handling Domain management Contact management Host management Message queue Collections Domains collection Contacts collection Hosts collection Billing transactions collection Invoices collection

Other sections

Registrars Domains EPP Gateway

Collections

ST Registry has implemented collections to improove communication performance between Registrar and ST Registry.

For collections was created unified list of parameters to manage filtration, sortings etc.

NameDescription
fieldFilter data represented as array.
opLogical operation to unite filters.
limitResult limit in response. In other words – number of objects to fetch starting from “offset” position.
offsetIdentify how many objects should be skipped before starting fetching objects.
sort_fieldIdentify object attribute which should be used for sorting results.
sort_directionSorting direction. May acquire values: asc or desc (ascending or descending).

Every response to collection request will include information:

  • searchInf/limit – requested result limits
  • searchInf/offset – requested result offset
  • searchInf/rows_count – total rows count according to applied filter values.

Example for IN construction:

URI: /collection_name/?do=search&field[‘field_name’][‘eq’][]=’ABC1’&field[‘field_name’][‘eq’][]=’ABC2′

This request will search for objects where field_name value exist in array [‘ABC1′,’ABC2’].

Example for OR logical operation:

URI: /collection_name/?do=search&field[‘field_name1’][‘eq’]=’ABC1’&field[‘field_name2’][‘eq’]=’ABC2’&op=or

This request will return all results where field_name1=ABC1 OR field_name2=ABC2.

GET Domains collection

GET /domains/?do=search&field[‘contact’][‘eq’]=’TEM525418792851B’

After successful authentication request, response will contact searchRes – collection of domains:

  • name – Request domain name. Value always available in response.
  • clID – ClientID who is currently acting registrar for the domain. In other words this is a client/registrar ID who is making this request. Value always available in response.
  • crID – ClientID who has originally registered/created this domain. Value always available in response.
  • crDate – Domain registration date. Value always available in response.
  • upDate – Date for the last successful update command execution. This value is optional and may not be available in response if domain didn’t got any successful update commands after domain registration/creation.
  • exDate – Domain expire date. Value always available in response.
  • ns – Name servers collection assigned to the current domain. This collection is optional and may not be available in response if domain have no assigned name servers.
  • contacts – Contacts collection assigned to the current domain. There is totally 4 kind of contacts: registrant, admin, billing, tech. All of them are required and always available in response. Collection may also contain optional values which are represented if assigned to the domain: registrant_privacy, admin_privacy, billing_privacy, tech_privacy. Read more about privacy in paragraph “WHOIS Privacy“.
  • status – Collection of status codes. More details on status codes page. Domain always have at least 1 status which mean that this collection is always available in response.
  • statusDate – Collection of all status codes from “status” collection but with date when each status code was assigned to current domain.
  • authInfo – Contain attribute pw – which identify AuthCode/EPPCode for domain. AuthCode/EPPCode is required to gain control over domain by other client/registrar or registrant. Usually is used to initiate domain transfer between clients/registrars.
  • 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.

It is possible to perform search by any field from result domain object field set.

Example for searching all domains with any contact value ‘ABC-12345’:

Request Example 
GET /domains/?do=search&limit=2 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 
GET /domains/?do=search&limit=2 HTTP/1.1
Host: apihost
Content-Type: application/json
Content-Length: 53
Api-Version: 1.0
Api-ClientTransactionId: 9a6c67e4-d666-54a8-9465-4847bee812e2
Api-ClientToken: 1a2B3C4d5e6F

{
    "searchRes": {
        "example1.st": {
            "name": "example1.st",
            "clID": "ClientID",
            "crID": "ClientID",
            "crDate": "2014-01-01T00:00:01+00:00",
            "upDate": "2014-01-01T00:05:14+00:00",
            "exDate": "2015-01-01T00:00:01+00:00",
            "ns": [
              "ns1.host.st",
              "ns2.host.st"
            ],
            "contacts": {
              "registrant": "ABC-12345",
              "admin": "ABC-54321",
              "billing": "ABC-67890",
              "tech": "ABC-09876"
            },
            "status": [
              "pendingUpdate"
            ],
            "statusDate": {
              "pendingUpdate": "2014-01-01T00:05:14+00:00"
            },
            "authInfo": {
              "pw": "AuthCode"
            }
        },
        "example2.st": {
            "name": "example2.st",
            "clID": "ClientID",
            "crID": "ClientID",
            "crDate": "2014-01-01T00:00:01+00:00",
            "upDate": "2014-01-01T00:05:14+00:00",
            "exDate": "2015-01-01T00:00:01+00:00",
            "ns": [
              "ns1.host.st",
              "ns2.host.st"
            ],
            "contacts": {
              "registrant": "ABC-12345",
              "admin": "ABC-54321",
              "billing": "ABC-67890",
              "tech": "ABC-09876"
            },
            "status": [
              "pendingUpdate"
            ],
            "statusDate": {
              "pendingUpdate": "2014-01-01T00:05:14+00:00"
            },
            "authInfo": {
              "pw": "AuthCode"
            }
        }
    },
    "searchInf": {
        "limit": 2,
        "offset": -1,
        "rows_count": "2"
    },
    "code": 1000,
    "message": "OK",
    "cltrid": "9a6c67e4-d666-54a8-9465-4847bee812e2",
    "svtrid": "65c44824-0480-45f3-862d-3003cf3a365f",
    "time": 0.009706974029541
}

GET Contacts collection

GET /contacts/?do=search

After successful authentication request, response will contact searchRes – collection of domains:

  • 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/?do=search&limit=1 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 
PUT /billing/?do=search&limit=2 HTTP/1.1
Host: apihost
Content-Type: application/json
Content-Length: 53
Api-Version: 1.0
Api-ClientTransactionId: 9a6c67e4-d666-54a8-9465-4847bee812e2
Api-ClientToken: 1a2B3C4d5e6F

{
    "searchRes": {
      "ABC-123": {
        "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"
        }
      }
    },
    "searchInf": {
        "rows_count": "2",
        "limit": 1,
        "offset": -1
    },
    "code": 1000,
    "message": "OK",
    "cltrid": "9a6c67e4-d666-54a8-9465-4847bee812e2",
    "svtrid": "65c44824-0480-45f3-862d-3003cf3a365f",
    "time": 0.009706974029541
}

GET Hosts collection

GET /hosts/?do=search

After successful authentication request, response will contact searchRes – collection of domains:

  • name – host name queried in this request.
  • clID – ClientID – current host sponsor.
  • crID – ClientID – host creator.
  • crDate – date when host was created.
  • addr – elements that contain collection of IP addresses associated with current host which is represented in pairs key->value. Key may obtain value “v4” or “v6” which identify IP version. Value should represent IP in version that is identified by Key.
  • 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 /hosts/?do=search&limit=1 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 
PUT /billing/?do=search&limit=2 HTTP/1.1
Host: apihost
Content-Type: application/json
Content-Length: 53
Api-Version: 1.0
Api-ClientTransactionId: 9a6c67e4-d666-54a8-9465-4847bee812e2
Api-ClientToken: 1a2B3C4d5e6F

{
    "searchRes": {
      "ns10.hostname.st": {
          "name": "ns10.hostname.st"
          "clID": "ClientID"
          "crID": "ClientID"
          "crDate": "2014-01-01T00:00:01+00:00"
          "addr": [
              {
                  v4: "192.0.2.1"
              }
              {
                  v6: "2001:db8:8:4::2"
              }
          ]
      }
    },
    "searchInf": {
        "rows_count": "3",
        "limit": 1,
        "offset": -1
    },
    "code": 1000,
    "message": "OK",
    "cltrid": "9a6c67e4-d666-54a8-9465-4847bee812e2",
    "svtrid": "65c44824-0480-45f3-862d-3003cf3a365f",
    "time": 0.009706974029541
}

GET Billing transactions collection

GET /billing/?do=search

After successful authentication request, response will contact searchRes – collection of domains:

  • TransactionUUID – Unique identifier for transaction.
  • clID – ClientID where transaction is related. Normally this is ID of requesting client.
  • BillingRecordName – Predefined by registry operation name.
  • Period – Operation period. OPTIONAL, available only for registration and/or renewal operation. Value reflect period in months.
  • Amount – Total amount/price for billing operation in currency defined by field “Currency”.
  • Status – Transaction payment status. May obtain values: PAID or NOT_PAID. When credit limit is used to create transaction – such transaction will gain status NOT_PAID until registrar/client will pay invoice which include unpaid transactions.
  • Currency – Currency which was used in corresponding transaction.
  • Description – Transaction description which was generated by ST Registry.
  • DateCreated – Date and time when transaction was created.
  • DatePaid – Date and time when transaction was paid using client balance or invoice (in case of credit limit usage).
  • DomainName – Optional, reference to domain name for current transaction
  • InvoiceUUID – Optional, Invoice number which was used to mark as “PAID” current transaction. Value is defined only for transactions that was paid and previously created using client credit limit.
Request Example 
GET /billing/?do=search&limit=2 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 
PUT /billing/?do=search&limit=2 HTTP/1.1
Host: apihost
Content-Type: application/json
Content-Length: 53
Api-Version: 1.0
Api-ClientTransactionId: 9a6c67e4-d666-54a8-9465-4847bee812e2
Api-ClientToken: 1a2B3C4d5e6F

{
    "searchRes": [
        {
            "TransactionUUID": "c36ffa00-1234-5678-8765-6825458b34e4",
            "ClientId": "ClientID",
            "BillingRecordName": "DomainCreatePrice",
            "Period": "24",
            "Amount": "69.84",
            "Status": "PAID",
            "Currency": "EUR",
            "Description": "Domain registration",
            "DateCreated": "1407844743",
            "DatePaid": "1407844743",
            "DomainName": "example1.st",
            "InvoiceUUID": ""
        },
        {
            "TransactionUUID": "d6ad4b17-1234-5678-a7cf-ba4511f7fa29",
            "ClientId": "ClientID",
            "BillingRecordName": "DomainCreatePrice",
            "Period": "24",
            "Amount": "69.84",
            "Status": "PAID",
            "Currency": "EUR",
            "Description": "Domain registration",
            "DateCreated": "1407844743",
            "DatePaid": "1407844743",
            "DomainName": "example2.st",
            "InvoiceUUID": ""
        }
    ],
    "searchInf": {
        "rows_count": "2",
        "limit": 2,
        "offset": -1
    },
    "code": 1000,
    "message": "OK",
    "cltrid": "9a6c67e4-d666-54a8-9465-4847bee812e2",
    "svtrid": "65c44824-0480-45f3-862d-3003cf3a365f",
    "time": 0.009706974029541
}

GET Invoices collection

GET /invoices/?do=search

After successful authentication request, response will contact searchRes – collection of domains:

  • number- Unique invoice number.
  • dateIssue – Date and time when invoice was issued.
  • dateDue – Due date for invoice.
  • datePaid – Date and time when invoice was paid.
  • Status – Invoice payment status. May obtain values: PAID or NOT_PAID.
  • currency- Invoice currency.
  • Currency – Currency which was used in corresponding transaction.
  • issuerName, issuerAddr, issuerCity, issuerCountry, issuerBillingEmail, issuerPostalCode, issuerFax, issuerVatId – Issuer details in the moment when invoice was issued (ST Registry details).
  • clientName, clientAddr, clientCity, clientCountry, clientBillingEmail, clientPostalCode, clientFax, clientVatId – client details in the moment when invoice was issued.
  • VAT- client VAT rate.
  • TotalNet – Invoice total NET worth price. Amount before VAT is added.
  • TotalGross – Invoice total GROSS worth price. Amount after VAT is added
  • clID – Client ID where invoice is related. Normally this is a same client who is requesting this result.r
  • records – Collection of invoice records.
  • notes – Collection of invoice notes. Usually this is remarks about payment or comments from registry or just communication about invoice between ST Registry and the Client.
Request Example 
GET /invoices/?do=search&limit=1 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 
PUT /invoices/?do=search&limit=2 HTTP/1.1
Host: apihost
Content-Type: application/json
Content-Length: 53
Api-Version: 1.0
Api-ClientTransactionId: 9a6c67e4-d666-54a8-9465-4847bee812e2
Api-ClientToken: 1a2B3C4d5e6F

{
    "searchRes": [
        {
            "number": "STR-20140812-151547",
            "dateIssue": "2014-01-01T13:09:06+00:00",
            "dateDue": "2014-01-14T13:09:06+00:00",
            "datePaid": "",
            "status": "NOT_PAID",
            "currency": "EUR",
            "issuerName": "ST Registry AB",
            "issuerAddr": "Parkgatan 6",
            "issuerCity": "Borlange",
            "issuerCountry": "SE",
            "issuerBillingEmail": "sales@nic.st",
            "issuerPostalCode": "78432",
            "issuerFax": "+1.6466664373",
            "issuerVatId": "SE-556663-2476-01",
            "clientName": "Client Organization",
            "clientAddr": "Client address",
            "clientCity": "Client city",
            "clientCountry": "US",
            "clientBillingEmail": "sales@client.tld",
            "clientVatId": "Client-VAT-ID",
            "VAT": "0",
            "totalNet": "250",
            "totalGross": "250",
            "clID": "ClientID",
            "records": [
                {
                    "priceNet": 250,
                    "name": "Balance",
                    "priceTotalNet": 250,
                    "quantity": "1",
                    "description": "Adding 250 EUR to registrar balance"
                }
            ],
            "notes": [
                {
                    "message": "Invoice #ABC-123-456 created by registrar. Tue, 1 Jan 2014 13:09:06 +0000",
                    "dateCreated": "2014-01-01T13:09:06+00:00",
                    "dateUpdated": "",
                    "clientId": "ClientID",
                    "clientName": "Client Organization"
                }
            ]
        }
    ],
    "searchInf": {
        "rows_count": "2",
        "limit": 1,
        "offset": -1
    },
    "code": 1000,
    "message": "OK",
    "cltrid": "9a6c67e4-d666-54a8-9465-4847bee812e2",
    "svtrid": "4e59f357-1fdd-48dd-b491-3cf7e80a6c3e",
    "time": 0.032310962677002
}