TLD Rules API

REST API for programmatic access to TLD registration requirements and rules.

Base URL: https://aws.ascio.info/api/v1/tldkit

Authentication

All endpoints require Ascio v2 API credentials passed as query parameters:

Parameter	Description	Required
username	Your Ascio account username	Yes
password	Your Ascio account password	Yes
env	testing (default) or production	No

Content Negotiation

All endpoints support JSON (default) and XML formats via the Accept header:

• Accept: application/json - JSON response (default)
• Accept: application/xml - XML response

Endpoints

GET /api/v1/tldkit/tlds

List all TLDs with their basic properties, paginated.

Parameters

Parameter	Description	Default
page	Page number	1
per_page	Items per page (max 500)	50
order	Sort by last_updated: asc or desc	asc
tld	Filter by TLD name(s), comma-separated	-

Example Request

GET /api/v1/tldkit/tlds?username=demo&password=demo123&env=testing&tld=com,de&page=1

Example Response

{
  "_links": {
    "self": "/api/v1/tldkit/tlds?order=asc&per_page=50&page=1",
    "first": "/api/v1/tldkit/tlds?order=asc&per_page=50&page=1",
    "last": "/api/v1/tldkit/tlds?order=asc&per_page=50&page=35"
  },
  "_meta": {
    "total": 1703,
    "page": 1,
    "per_page": 50,
    "total_pages": 35,
    "order": "asc"
  },
  "data": [
    {
      "tld": "com",
      "id": "123",
      "country": "US",
      "last_updated": "2026-01-15T10:30:00",
      "threshold": 0,
      "auth_code_required": true,
      "local_presence": {
        "required": false,
        "offered": false
      },
      "domain_length": {
        "min": 1,
        "max": 63
      },
      "nameservers": {
        "min": 2,
        "max": 13
      },
      "periods": {
        "register": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
        "renew": [1, 2, 3, 4, 5, 6, 7, 8, 9],
        "transfer": [1],
        "autorenew": [1]
      },
      "group_tlds": ["com"]
    }
  ]
}

GET /api/v1/tldkit/tlds/{name}

Get detailed information for a specific TLD, including processes and appendices.

Example Request

GET /api/v1/tldkit/tlds/it?username=demo&password=demo123

GET /api/v1/tldkit/fields

Get required special fields for domain registration by TLD.

Parameters

Parameter	Description
tld	Filter by TLD name(s), comma-separated

Example Response

{
  "generated": "2026-02-04T10:00:00",
  "total": 362,
  "data": [
    {
      "tld": "it",
      "registry": "NIC.it",
      "required_fields": [
        {
          "code": "3m",
          "api_name": "Registrant.OrganisationNumber",
          "label": "Organisation Number",
          "class": "Registrant"
        },
        {
          "code": "3q",
          "api_name": "Registrant.Type",
          "label": "Type",
          "class": "Registrant"
        }
      ]
    }
  ]
}

GET /api/v1/tldkit/conditions

Get conditional field requirements that depend on context (e.g., individual vs organization).

Parameters

Parameter	Description
tld	Filter by TLD name(s), comma-separated

Example Response

{
  "generated": "2026-02-01T12:00:00",
  "total_processed": 1703,
  "total_with_conditions": 135,
  "data": [
    {
      "tld": "it",
      "conditional_fields": [
        {
          "field": "Registrant.OrganisationNumber",
          "conditions": [
            {"context": "individual", "requirement": "Social Security Number"},
            {"context": "organization", "requirement": "VAT Number"}
          ]
        }
      ]
    }
  ]
}

GET /api/v1/tldkit/stats

Get statistics and last sync information.

Example Response

{
  "generated": "2026-02-04T10:00:00",
  "counts": {
    "documents": 717,
    "tlds": 1703,
    "tlds_with_special_fields": 362,
    "auth_code_required": 1650,
    "local_presence_required": 45
  },
  "last_sync": "2026-02-01T06:00:00"
}

Error Responses

All endpoints return consistent error responses:

{
  "error": true,
  "status": 401,
  "message": "Username and password are required"
}

Legacy Endpoint

The legacy endpoint /tldkit.xq remains available for backward compatibility without authentication. It returns basic TLD data in JSON format.