API reference · /api/v1

Registration & management

Register, renew and transfer domains and manage them, using your reseller prices and account credit. These endpoints require signed requests. Orders follow your account's approval settings: if new orders or renewals are reviewed by Domain.af, the response stage is pending_approval and the order completes after review.

Account and catalogue

• GET /api/v1/ping — check the key; returns account, currency, balance and scopes.
• GET /api/v1/tlds — extensions with your 1-year register/renew/transfer prices and limits.
• POST /api/v1/domains/availability — {"domains": ["a.af", "b.com.af"], "years": 1}, up to 20 names.

Register, transfer, renew (Idempotency-Key required)

POST /api/v1/domains/register
{
  "domain": "example.af",
  "years": 1,
  "contacts": {
    "registrant": {"name": "…", "organization": null, "email": "…", "phone": "+93700000000",
                   "address_line_1": "…", "address_line_2": null, "city": "Kabul", "state": "Kabul",
                   "postal_code": "1001", "country": "AF"},
    "admin": null, "tech": null, "billing": null
  },
  "nameservers": ["ns1.example.net", "ns2.example.net"],
  "addons": ["whois_privacy"],
  "client_reference": "your order or domain ID"
}

• Missing admin/tech/billing contacts use the registrant. Omitting nameservers uses Domain.af's defaults.
• POST /api/v1/domains/transfer — same body plus "auth_code".
• POST /api/v1/domains/{domain}/renew — {"years": 1, "current_expiry": "2027-05-01"}. current_expiry is the expiry you are renewing from; if the domain has already been renewed the call returns 409 expiry_mismatch instead of charging again.

201 Created
{"success": true, "data": {"domain": "example.af", "status": "active", "stage": "active",
  "expires_at": "2027-10-13T…", "expiry_date": "2027-10-13", "charged": "25.00", "currency": "USD",
  "invoice": "INV-…", "balance": "75.00", …}}

stage is one of active, pending, pending_approval, pending_kyc, pending_transfer, expired, redemption, suspended, transferred_away, cancelled, failed. Registrations are processed asynchronously; poll GET /api/v1/domains/{domain}.

Domain information

• GET /api/v1/domains/{domain} — status, stage, dates, lock, nameservers, registry statuses, WHOIS Privacy, Domain Protection and DNS hosting state.

Management

• PUT /api/v1/domains/{domain}/nameservers — {"nameservers": ["ns1…", "ns2…"]} (2–5).
• GET|PUT /api/v1/domains/{domain}/contacts — {"contacts": {"registrant": {…}}}; only the types you send change. A response status of pending means a WHOIS Privacy forwarding change waits for email confirmation.
• PUT /api/v1/domains/{domain}/lock — {"locked": true}.
• POST /api/v1/domains/{domain}/epp-code — sets and returns a new transfer code. The registrant is notified.
• GET|POST /api/v1/domains/{domain}/hosts, PUT|DELETE /api/v1/domains/{domain}/hosts/{hostname} — child nameservers: {"hostname": "ns1.example.af", "ipv4": ["192.0.2.1"], "ipv6": []}.

WHOIS Privacy and Domain Protection

• GET|POST|DELETE /api/v1/domains/{domain}/privacy — enabling buys the add-on for the rest of the term from account credit when the domain does not have it yet (Idempotency-Key required). The registrant email may need to confirm before privacy goes live (status: awaiting_verification).
• GET|POST /api/v1/domains/{domain}/protection — buys and switches on Domain Protection (Idempotency-Key required). While it is on, the registrar lock cannot be removed and the EPP code cannot be requested through the API.
• DELETE /api/v1/domains/{domain}/protection always returns 403 requires_portal_verification: removing protection is only possible in the reseller portal.