Search and register a domain

This guide covers a more realistic registration flow than the quickstart: searching by keyword instead of one exact domain, reviewing pricing, and setting up DNS automatically as part of the purchase.

Search for available domains

Instead of checking one domain at a time, search by keyword to get a list of available suggestions across TLDs.

curl -X POST https://api.dotlet.net/api/v1/registrar/search \
  -H "X-API-Key: dk_••••••••••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "acmewidgets",
    "tlds": ["com", "io", "dev"],
    "limit": 10
  }'

const response = await fetch('https://api.dotlet.net/api/v1/registrar/search', {
  method: 'POST',
  headers: {
    'X-API-Key': 'dk_••••••••••••••••',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: 'acmewidgets',
    tlds: ['com', 'io', 'dev'],
    limit: 10
  })
});
const data = await response.json();
console.log(data);

import requests

response = requests.post(
    'https://api.dotlet.net/api/v1/registrar/search',
    headers={'X-API-Key': 'dk_••••••••••••••••'},
    json={
        'query': 'acmewidgets',
        'tlds': ['com', 'io', 'dev'],
        'limit': 10
    }
)
print(response.json())

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	payload := map[string]interface{}{
		"query": "acmewidgets",
		"tlds":  []string{"com", "io", "dev"},
		"limit": 10,
	}
	body, _ := json.Marshal(payload)

	req, _ := http.NewRequest("POST", "https://api.dotlet.net/api/v1/registrar/search", bytes.NewBuffer(body))
	req.Header.Set("X-API-Key", "dk_••••••••••••••••")
	req.Header.Set("Content-Type", "application/json")

	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()

	respBody, _ := io.ReadAll(resp.Body)
	fmt.Println(string(respBody))
}

The response lists each candidate domain with its availability and price:

{
  "query": "acmewidgets",
  "suggestions": [
    { "domain": "acmewidgets.com", "available": true, "price": "12.99", "currency": "USD" },
    { "domain": "acmewidgets.io", "available": true, "price": "34.99", "currency": "USD" },
    { "domain": "acmewidgets.dev", "available": false, "price": null, "currency": "USD" }
  ]
}

tlds is optional, omit it to search the registrar’s default set of extensions.

Register the domain with DNS set up automatically

When you purchase a domain, you can set setup_dns to true so Dotlet creates a DNS zone for it immediately, instead of requiring a separate setup call.

curl -X POST https://api.dotlet.net/api/v1/registrar/purchase \
  -H "X-API-Key: dk_••••••••••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "acmewidgets.com",
    "years": 1,
    "contact": {
      "first_name": "Ada",
      "last_name": "Lovelace",
      "email": "ada@acmewidgets.com",
      "phone": "+14155550100",
      "address1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94105",
      "country": "US"
    },
    "privacy": true,
    "auto_renew": true,
    "setup_dns": true,
    "dns_provider": "cloudflare"
  }'

const response = await fetch('https://api.dotlet.net/api/v1/registrar/purchase', {
  method: 'POST',
  headers: {
    'X-API-Key': 'dk_••••••••••••••••',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    domain: 'acmewidgets.com',
    years: 1,
    contact: {
      first_name: 'Ada',
      last_name: 'Lovelace',
      email: 'ada@acmewidgets.com',
      phone: '+14155550100',
      address1: '123 Main St',
      city: 'San Francisco',
      state: 'CA',
      postal_code: '94105',
      country: 'US'
    },
    privacy: true,
    auto_renew: true,
    setup_dns: true,
    dns_provider: 'cloudflare'
  })
});
const data = await response.json();
console.log(data);

import requests

response = requests.post(
    'https://api.dotlet.net/api/v1/registrar/purchase',
    headers={'X-API-Key': 'dk_••••••••••••••••'},
    json={
        'domain': 'acmewidgets.com',
        'years': 1,
        'contact': {
            'first_name': 'Ada',
            'last_name': 'Lovelace',
            'email': 'ada@acmewidgets.com',
            'phone': '+14155550100',
            'address1': '123 Main St',
            'city': 'San Francisco',
            'state': 'CA',
            'postal_code': '94105',
            'country': 'US'
        },
        'privacy': True,
        'auto_renew': True,
        'setup_dns': True,
        'dns_provider': 'cloudflare'
    }
)
print(response.json())

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	payload := map[string]interface{}{
		"domain": "acmewidgets.com",
		"years":  1,
		"contact": map[string]interface{}{
			"first_name":  "Ada",
			"last_name":   "Lovelace",
			"email":       "ada@acmewidgets.com",
			"phone":       "+14155550100",
			"address1":    "123 Main St",
			"city":        "San Francisco",
			"state":       "CA",
			"postal_code": "94105",
			"country":     "US",
		},
		"privacy":      true,
		"auto_renew":   true,
		"setup_dns":    true,
		"dns_provider": "cloudflare",
	}
	body, _ := json.Marshal(payload)

	req, _ := http.NewRequest("POST", "https://api.dotlet.net/api/v1/registrar/purchase", bytes.NewBuffer(body))
	req.Header.Set("X-API-Key", "dk_••••••••••••••••")
	req.Header.Set("Content-Type", "application/json")

	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()

	respBody, _ := io.ReadAll(resp.Body)
	fmt.Println(string(respBody))
}

The response includes a dns_setup object and a status_url you can poll while the zone is created and nameservers propagate:

{
  "success": true,
  "domain": "acmewidgets.com",
  "order_id": "8f14e45f-ceea-467e-bd6a-15e6e4f8c2f1",
  "nameservers": [],
  "dns_setup": { "status": "in_progress" },
  "status_url": "/api/v1/registrar/domains/acmewidgets.com/dns-status"
}

Check DNS setup progress

DNS setup happens asynchronously; creating a zone, updating nameservers at the registrar, and verifying delegation can take a few minutes. Poll the status endpoint until status reaches completed.

curl https://api.dotlet.net/api/v1/registrar/domains/acmewidgets.com/dns-status \
  -H "X-API-Key: dk_••••••••••••••••"

const response = await fetch('https://api.dotlet.net/api/v1/registrar/domains/acmewidgets.com/dns-status', {
  headers: { 'X-API-Key': 'dk_••••••••••••••••' }
});
const data = await response.json();
console.log(data);

import requests

response = requests.get(
    'https://api.dotlet.net/api/v1/registrar/domains/acmewidgets.com/dns-status',
    headers={'X-API-Key': 'dk_••••••••••••••••'}
)
print(response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.dotlet.net/api/v1/registrar/domains/acmewidgets.com/dns-status", nil)
	req.Header.Set("X-API-Key", "dk_••••••••••••••••")

	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}

{
  "domain": "acmewidgets.com",
  "status": "in_progress",
  "provider": "cloudflare",
  "zone_id": "023e105f4ecef8ad9ca31a8372d0c353",
  "nameservers": ["ns1.cloudflare.com", "ns2.cloudflare.com"],
  "progress": {
    "zone_created": true,
    "ns_updated_at_registrar": true,
    "ns_delegation_verified": false
  }
}

ns_delegation_verified flips to true once the new nameservers have propagated. Until then, the domain still resolves through its previous configuration.

If you didn’t set setup_dns during purchase, trigger it later with POST /registrar/domains/{domain}/setup-dns, it accepts the same dns_provider field.

What didn’t get covered here

Manual nameserver control: if you manage DNS with a provider other than the ones Dotlet integrates with, skip setup_dns and point nameservers yourself with PUT /registrar/domains/{domain}/nameservers.
Reviewing price before charging: to show a customer a price and get their confirmation before billing, create an order with POST /registrar/order instead of purchasing directly.

Get Started

Integration Paths

Guides

Search for available domains

Register the domain with DNS set up automatically

Check DNS setup progress

What didn’t get covered here

Next steps

Manage DNS records

Orders

​Search for available domains

​Register the domain with DNS set up automatically

​Check DNS setup progress

​What didn’t get covered here

​Next steps

Manage DNS records

Orders

Search for available domains

Register the domain with DNS set up automatically

Check DNS setup progress

What didn’t get covered here

Next steps