TLD catalogue

GET /api/v1/products/tlds

The single most useful endpoint in the API. It answers how many years you can sell an extension for, whether it supports privacy, DNSSEC and transfers, which extra fields are required, and what it costs — all in one call.

This endpoint is free

It is exempt from rate limiting and never costs quota points. Even so, cache it on your side and refresh daily — it changes rarely and the response is large.

Request

GET /api/v1/products/tlds?maxResultCount=500&currency=USD

Parameter	Default	Notes
filterText	—	Filter by extension name.
currency	—	Express prices in this currency, e.g. USD, TRY.
skipCount	0
maxResultCount	10	Raise this — the default of 10 will surprise you. The full catalogue is several hundred entries.
sorting	—	field asc or field desc. Must end in asc or desc.

Response — 200, one entry abridged

{
  "totalCount": 487,
  "items": [
    {
      "name": "com",
      "minRegistrationPeriod": 1,
      "maxRegistrationPeriod": 10,
      "registrationPeriods": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
      "renewalPeriods": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
      "addGracePeriod": 5,
      "autoRenewGracePeriod": 45,
      "deletionRestorablePeriod": 30,
      "deletionHoldPeriod": 5,
      "transferPeriod": 5,
      "isSupportTransfer": true,
      "isTransferCheckSupported": true,
      "isRequiredAuthCode": true,
      "isTransferLockPossible": true,
      "isPrivacyAvailable": true,
      "isDnssecAvailable": true,
      "isSupportIdn": true,
      "isIpv6Available": true,
      "isGlueRecordAllowed": true,
      "isHostObjectAccepted": true,
      "registryDnsCheck": false,
      "isRequireDocument": false,
      "isSupportTrustee": false,
      "isTrusteeRequired": false,
      "isHandleUpdateAvailable": true,
      "isSaleAllowed": true,
      "availableInTestEnvironment": true,
      "prices": [
        {
          "priceGroup": "Standard",
          "register": [
            { "period": 1, "price": 11.40, "currency": "USD" },
            { "period": 2, "price": 22.80, "currency": "USD" }
          ],
          "renew": [
            { "period": 1, "price": 12.90, "currency": "USD" }
          ],
          "transfer": [
            { "period": 1, "price": 11.40, "currency": "USD" }
          ],
          "restore": { "period": 1, "price": 85.00, "currency": "USD" },
          "backorder": { "period": 1, "price": 25.00, "currency": "USD" }
        }
      ],
      "attributes": []
    }
  ]
}

Every field, and what to do with it

This response is the contract for what an extension will and will not accept. The fields fall into four groups.

1 · Terms you may sell — in years

Field	Meaning and use
name	The extension itself, without a leading dot: com, com.tr, co.uk.
registrationPeriods	The exact terms you may send as period when registering. A list, not a range — [1,2,3,5,10] means 4 is not sellable. Anything else gives Domain:10023.
renewalPeriods	The same list for renewal. It is not always identical to registrationPeriods.
minRegistrationPeriod maxRegistrationPeriod	The smallest and largest entry in registrationPeriods, provided for convenience. Use them for a “from N years” label; use the list itself to build the selector.
renewalPeriod	The shortest renewal term. Useful as the default in a renewal form.
transferPeriod	The shortest transfer term. May be 0 when the extension does not publish transfer terms in a form we can read — treat 0 as “not stated” and rely on /transfers/check and the transfer price list instead.
registerPeriod	Reserved. Currently always 0 — ignore it.

2 · Capability flags — check before you call

Each of these tells you whether an operation is possible at all. Checking first turns a failed API call into a disabled button.

Flag	What it gates, and the error if you ignore it
isSupportTransfer	Whether domains can be transferred in at all. false → Domain:10011 on /domains/transfer.
isTransferCheckSupported	Whether the registry offers a pre-transfer check. false → Domain:10025 on /transfers/check; that is not a failure, just skip the check and call /transfer directly.
isRequiredAuthCode	Whether an authorisation code is mandatory to transfer in. true means you must collect it from the customer before you start.
isTransferLockPossible	Whether the registrar transfer lock can be toggled. false means /domains/lock and /unlock have nothing to act on.
isPrivacyAvailable	Whether WHOIS privacy is sold. false → Tld:10001 on /domains/privacy. Hide the privacy option in your order form.
isDnssecAvailable	Whether DNSSEC is supported. false → every DNSSEC write gives Dnssec:10001.
isSupportIdn	Whether internationalised (non-ASCII) names are accepted. false → registering one gives TldAttribute:10004.
isIpv6Available	Whether IPv6 glue addresses are accepted. false → sending a v6 address gives Dns:10026; send only v4.
isGlueRecordAllowed	Whether glue records are accepted at all. false → host operations give Dns:10017.
isHostObjectAccepted	How name servers under the domain are modelled. true → independent host objects; false → glue records carried on the domain. Changes what you can share and delete — see Host (glue) records.
isHandleUpdateAvailable	Whether contacts can be re-pointed by handle. false → use /domains/contacts/update with full details instead of /update-with-handle.
isSupportTrustee	Whether a trustee / local-presence service is available to buy.
isSaleAllowed	Whether domains on this extension may be listed for sale.
availableInTestEnvironment	Whether the extension exists in the test environment. Check this before writing an integration test against a specific extension.

3 · Flags that change your workflow

These do not block anything — they mean the happy path has an extra step. Design for them before you sell the extension, not after the first support ticket.

Flag	What changes when it is true
isRequireDocument	Registration does not complete on its own. The domain comes back in a waiting state and stays there until you upload documents and the registry approves them. Your order flow needs a document step and a status screen.
isTrusteeRequired	You must send useTrusteeContact: true or registration fails with Trustee:10006. The trustee fee is added to the order, so quote the customer the higher price.
registryDnsCheck	The registry queries your name servers and checks they really answer for the domain before accepting the registration. Point the domain at name servers that are already live — using a provider you have not configured yet will have the registration refused.

4 · Lifecycle periods — in calendar days

These describe what the registry does to a domain as it ages. They are the numbers behind the renewal and restore rules, and they differ by extension.

Field	Meaning and use
addGracePeriod	Days after a new registration during which deleting the domain is refunded by the registry. Commonly around 3–5 days. This is your window to undo a typo’d registration at no cost.
autoRenewGracePeriod	Days after expiry during which the registry’s automatic renewal can still be reversed. The domain is auto-renewed on the first day after expiry and sits in this window — which is exactly why a second renewal inside it returns Domain:10020. Commonly two to three weeks, up to 45 days.
deletionRestorablePeriod	The redemption window. How many days POST /domains/restore keeps working after the domain is deleted — typically 30. Drive your “you can still recover this” messaging off it.
deletionHoldPeriod	Days between redemption lapsing and the domain actually being released to the public. Nothing can be done during it; the domain is beyond recovery.
finalizationPeriod	Days until a pending renewal becomes irreversible at the registry.
failurePeriod	The point after expiry at which the domain can no longer be renewed at all and moves into deletion. Often a negative number, counted relative to the expiry date.
paymentPeriod	Days during which the registry accepts payment for an upcoming renewal.

How the lifecycle fields fit together

registration ──► addGracePeriod            delete here = refunded
                      │
                      ▼
                   active ... ... ... ... ... expiry date
                                                 │
                                                 ▼
                              autoRenewGracePeriod   registry auto-renews;
                                                     second renewal refused (10020)
                                                 │
                                                 ▼
                                   failurePeriod     renewal no longer possible
                                                 │
                                                 ▼
                         deletionRestorablePeriod    restore still works
                                                 │
                                                 ▼
                              deletionHoldPeriod     released to the public

Two practical uses: send renewal reminders before failurePeriod is reached, and show “recoverable until” dates from deletionRestorablePeriod instead of assuming 30 days everywhere.

Prices

Read the prices entry whose priceGroup matches your account’s group — which you can find from GET /api/v1/deposit/accounts/me as resellerGroupName.

These are list prices, and premium domains are not here

• If you have a negotiated rate, the amount actually charged can be lower than what this endpoint shows. Treat catalogue prices as your sell-price baseline, not as your cost.
• Premium domain prices never appear here. They come from POST /domains/search, /renew/check or /transfers/check, and they can be many times the standard price. Always check isPremium before showing a price to a customer.

Extra fields (attributes)

The attributes array lists the registry-specific extra fields for the extension. Each entry has:

Field	Meaning
key	The key to send in tldAttributes.
description	Label to show the customer.
type	Text, DropdownList, RadioButton, Checkbox, CheckboxWithContract, FileUpload or Label. Label entries are informational only; nothing is sent for them.
isRequired	Whether the registration fails without it.
options	The permitted values, each as { "value": "..." }. Send one of the values verbatim. Empty for free-text fields.

"attributes": [
  {
    "key": "TRABISDOMAINCATEGORY",
    "description": "Domain category",
    "isRequired": true,
    "type": "DropdownList",
    "options": [{ "value": "Corporate" }, { "value": "Owner" }]
  }
]

Build your registration form from this

Rather than hard-coding “.com.tr needs an identity number”, render the form dynamically from attributes. New extension requirements then work without a code change, and you never send a key the registry does not recognise. Every extension’s fields are also listed on its page under TLDs.

Errors

Code	Meaning and fix
Dna.ProductService.Product:10002	Invalid sorting value. The format is field asc or field desc.