.TZ Registry EPP API v1.2.0

Official API documentation for the Tanzania Network Information Centre domain registry operations

Contents

API Overview

The .TZ Registry EPP API provides a modern interface to domain registration, transfer, and management operations for the .tz domain space via the FRED EPP protocol. This API acts as a bridge between HTTP/JSON applications and the EPP protocol used by the Tanzania domain registry.

With this API, you can:

  • Check domain availability across all .tz zones
  • Register new domains in .tz TLD space
  • Manage domain contacts and nameservers
  • Transfer domains between registrars
  • Renew domain registrations
  • Manage EPP authorization codes
  • Check account balance information
  • Access registry-wide statistics
Note: This API is designed for accredited .TZ registrars who have an EPP account with the Tanzania Network Information Centre. It is not intended for direct use by end customers.

Authentication

All API requests require authentication via an API key issued by the .TZ Registry. This key identifies your registrar account and determines what operations you can perform. Your API key can be provided in one of three ways:

HTTP Header

Include the X-API-KEY header in your request

X-API-KEY: your_api_key_here

Query Parameter

Append the api_key parameter to the URL

https://fred.yatosha.com/v1?api_key=your_api_key_here

Request Body

Include the API key in the JSON request body (POST requests only)

{
  "api_key": "your_api_key_here",
  "action": "checkDomain",
  "domainName": "example.co.tz"
}
Security Best Practice: We strongly recommend using the HTTP Header method as it prevents your API key from being logged in server access logs or browser history.

Endpoints

POST /v1

Main API endpoint for all operations. The action to perform is specified by the action parameter in the request body.

Content-Type: application/json

Available Actions

checkDomain

Check if a domain is available for registration.

{
  "action": "checkDomain",
  "domainName": "example.tz"
}

Response:

{
  "status": "success",
  "data": {
    "available": true,
    "domain": "example.tz"
  }
}

getDomainInfo

Get detailed information about a domain.

{
  "action": "getDomainInfo",
  "domainName": "example.tz",
  "authCode": "optional-epp-code"
}

Response:

{
  "status": "success",
  "data": {
    "domain": "example.tz",
    "status": ["ok"],
    "registrant": "REG12345",
    "admin": ["ADM12345"],
    "created": "2023-01-15T14:30:00.0Z",
    "expires": "2025-01-15T14:30:00.0Z",
    "nsset": "NSSET12345"
  }
}

getNameservers

Get nameservers for a domain.

{
  "action": "getNameservers",
  "domainName": "example.tz"
}

Response:

{
  "status": "success",
  "data": {
    "nameservers": [
      "ns1.tzregistry.co.tz",
      "ns2.tzregistry.co.tz"
    ]
  }
}

updateNameservers

Update nameservers for a domain.

{
  "action": "updateNameservers",
  "domainName": "example.tz",
  "nameservers": [
    "ns1.tzregistry.co.tz",
    "ns2.tzregistry.co.tz"
  ]
}

Response:

{
  "status": "success",
  "data": {
    "updated": true
  }
}

registerDomain

Register a new domain.

{
  "action": "registerDomain",
  "domainName": "example.tz",
  "period": 1,
  "registrantInfo": {
    "name": "John Doe",
    "organization": "Tanzania Tech Ltd",
    "address1": "123 Nyerere Road",
    "city": "Dar es Salaam",
    "state": "Dar es Salaam",
    "postcode": "11101",
    "country": "TZ",
    "phone": "+255.754123456",
    "email": "john.doe@tanzaniatech.co.tz"
  },
  "adminInfo": {
    "name": "Jane Doe",
    "organization": "Tanzania Tech Ltd",
    "address1": "123 Nyerere Road",
    "city": "Dar es Salaam",
    "state": "Dar es Salaam",
    "postcode": "11101",
    "country": "TZ",
    "phone": "+255.754123457",
    "email": "jane.doe@tanzaniatech.co.tz"
  },
  "nameservers": [
    "ns1.tzregistry.co.tz",
    "ns2.tzregistry.co.tz"
  ]
}

Response:

{
  "status": "success",
  "data": {
    "registered": true
  }
}

transferDomain

Transfer a domain to your registrar.

{
  "action": "transferDomain",
  "domainName": "example.tz",
  "authCode": "domain-epp-code"
}

Response:

{
  "status": "success",
  "data": {
    "transferInitiated": true
  }
}

renewDomain

Renew a domain registration.

{
  "action": "renewDomain",
  "domainName": "example.tz",
  "period": 1
}

Response:

{
  "status": "success",
  "data": {
    "renewed": true
  }
}

getContactDetails

Get contact details for a domain.

{
  "action": "getContactDetails",
  "domainName": "example.tz"
}

Response:

{
  "status": "success",
  "data": {
    "contacts": {
      "registrant": {
        "id": "REG12345",
        "name": "John Doe",
        "organization": "Tanzania Tech Ltd",
        "address1": "123 Nyerere Road",
        "city": "Dar es Salaam",
        "state": "Dar es Salaam",
        "postcode": "11101",
        "country": "TZ",
        "phone": "+255.754123456",
        "email": "john.doe@tanzaniatech.co.tz"
      },
      "admin": [
        {
          "id": "ADM12345",
          "name": "Jane Doe",
          "organization": "Tanzania Tech Ltd",
          "address1": "123 Nyerere Road",
          "city": "Dar es Salaam",
          "state": "Dar es Salaam",
          "postcode": "11101",
          "country": "TZ",
          "phone": "+255.754123457",
          "email": "jane.doe@tanzaniatech.co.tz"
        }
      ]
    }
  }
}

updateContactDetails

Update contact details for a domain.

{
  "action": "updateContactDetails",
  "domainName": "example.tz",
  "registrantInfo": {
    "name": "New Registrant Name",
    "organization": "New Company Name",
    "address1": "123 New Street",
    "city": "New City",
    "state": "New State",
    "postcode": "54321",
    "country": "TZ",
    "phone": "+255.987654321",
    "email": "new-contact@example.com"
  },
  "adminInfo": {
    "name": "New Admin Name",
    "organization": "New Company Name",
    "address1": "123 New Street",
    "city": "New City",
    "state": "New State",
    "postcode": "54321",
    "country": "TZ",
    "phone": "+255.987654321",
    "email": "new-admin@example.com"
  }
}

Response:

{
  "status": "success",
  "data": {
    "updated": true
  }
}

getEPPCode

Get the EPP/Auth code for a domain.

{
  "action": "getEPPCode",
  "domainName": "example.tz"
}

Response:

{
  "status": "success",
  "data": {
    "eppCode": "ABCD1234"
  }
}

setEPPCode

Set a new EPP/Auth code for a domain.

{
  "action": "setEPPCode",
  "domainName": "example.tz",
  "newEppCode": "new-epp-code"
}

Response:

{
  "status": "success",
  "data": {
    "updated": true
  }
}

getBalance

Get account credit balance information for all zones.

{
  "action": "getBalance"
}

Response:

{
  "status": "success",
  "data": {
    "balance": {
      "tz": 1500000,
      "co.tz": 1200000,
      "or.tz": 800000
    }
  }
}

Response Format

All API responses are in JSON format with a consistent structure:

Success Response

When an operation is successful, the API returns a 200 OK HTTP status code and a JSON response with the following structure:

{
  "status": "success",
  "data": {
    // Action-specific response data
  }
}

Error Response

When an operation fails, the API returns an appropriate HTTP status code (4xx or 5xx) and a JSON response with the following structure:

{
  "status": "error",
  "message": "Error description",
  "errorCode": 2302 // Optional EPP error code
}

Common EPP Error Codes

The following error codes may be returned in API responses:

Support and Resources

If you need assistance with the API or have any questions, please contact our technical support team:

Additional Resources: