NewHost Docs

API reference

Domains

Registered domains, registration orders and DNS records.

Try these requests in Postman: Download Postman collection (how to use it).

List domains

GET/v1/domains

Requires a secret key with the read scope.

Parameters

NameInTypeDescription
limitqueryintegerItems per page, 1-100 (default 50).
offsetqueryintegerItems to skip (default 0).

Request

curl "https://api.newhost.co.za/v1/domains" \
  -H "Authorization: Bearer sk_live_..."

Response

{
  "data": [
    {
      "id": "clx8dom0001",
      "name": "acme.co.za",
      "tld": "co.za",
      "status": "ACTIVE",
      "autoRenew": true,
      "registeredAt": "2025-10-01T00:00:00.000Z",
      "expiresAt": "2026-10-01T00:00:00.000Z",
      "nameservers": [
        "ns1.newhost.co.za",
        "ns2.newhost.co.za"
      ],
      "dnsProvider": "NEWHOST"
    }
  ],
  "has_more": false
}

Retrieve a domain

GET/v1/domains/{id}

Requires a secret key with the read scope.

Parameters

NameInTypeDescription
idrequiredpathstringThe domain ID.

Request

curl "https://api.newhost.co.za/v1/domains/ID" \
  -H "Authorization: Bearer sk_live_..."

Response

{
  "data": {
    "id": "clx8dom0001",
    "name": "acme.co.za",
    "tld": "co.za",
    "status": "ACTIVE",
    "autoRenew": true,
    "registeredAt": "2025-10-01T00:00:00.000Z",
    "expiresAt": "2026-10-01T00:00:00.000Z",
    "nameservers": [
      "ns1.newhost.co.za",
      "ns2.newhost.co.za"
    ],
    "dnsProvider": "NEWHOST"
  }
}

Order a domain registration

POST/v1/domains

Creates an invoice. It is paid from your wallet when the balance allows, and the domain is registered once paid. Registrant details must be the domain owner's.

Requires a secret key with the domains scope. Returns 201 on success.

Body

FieldTypeDescription
domainrequiredstringDomain to register.
yearsinteger1-10 (default 1).
registrantrequiredobjectname, email, contactNumber (+27.821234567), address1, city, province, postalCode, country (ISO-2).
nameserversstring[]2-5 different nameserver host names, not inside the domain being registered (set those once it is registered). Case and a trailing dot are ignored. Defaults to NewHost's.
clientReferencestringDomain resellers: your own reference for the client the domain is for (up to 120 characters). Shown on the domain, for your records only.
autoRenewbooleanRenew automatically before the domain expires (default true).
lockbooleanLock the domain against transfer requests once it is registered (default true). Unlock it before moving it to another registrar.

Request

curl -X POST "https://api.newhost.co.za/v1/domains" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com","years":1,"registrant":{"name":"Jane Doe","email":"[email protected]","contactNumber":"+27.821234567","address1":"1 Main Road","city":"Cape Town","province":"Western Cape","postalCode":"8001","country":"ZA"}}'

Response

{
  "data": {
    "invoice": {
      "id": "clx8inv0001",
      "number": "NH-2026-000123",
      "kind": "DOMAIN",
      "status": "PAID",
      "amount": "249.00",
      "vat": "0.00",
      "issuedAt": "2026-09-01T08:00:00.000Z",
      "dueAt": "2026-09-08T08:00:00.000Z",
      "paidAt": "2026-09-01T08:02:11.000Z",
      "periodStart": "2026-09-01T08:02:11.000Z",
      "periodEnd": "2026-10-01T08:02:11.000Z"
    }
  }
}

List DNS records

GET/v1/domains/{id}/dns

Requires a secret key with the read scope.

Parameters

NameInTypeDescription
idrequiredpathstringThe domain ID.

Request

curl "https://api.newhost.co.za/v1/domains/ID/dns" \
  -H "Authorization: Bearer sk_live_..."

Response

{
  "data": [
    {
      "id": "8812",
      "type": "A",
      "name": "",
      "content": "203.0.113.10",
      "ttl": 3600,
      "prio": 0
    }
  ],
  "provider": "NEWHOST"
}

Add a DNS record

POST/v1/domains/{id}/dns

Requires a secret key with the domains scope. Returns 201 on success.

Parameters

NameInTypeDescription
idrequiredpathstringThe domain ID.

Body

FieldTypeDescription
typerequiredstringA, AAAA, CNAME, MX, TXT, SRV, CAA or NS.
namestringHost relative to the domain; empty for the apex.
contentrequiredstringRecord value.
ttlinteger60-86400 (default 3600).
priointegerPriority for MX / SRV.

Request

curl -X POST "https://api.newhost.co.za/v1/domains/ID/dns" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"type":"TXT","name":"_verify","content":"token-123","ttl":3600}'

Response

{
  "data": {
    "ok": true
  }
}

Delete a DNS record

DELETE/v1/domains/{id}/dns/{recordId}

Requires a secret key with the domains scope.

Parameters

NameInTypeDescription
idrequiredpathstringThe domain ID.
recordIdrequiredpathstringRecord ID from List DNS records.

Request

curl -X DELETE "https://api.newhost.co.za/v1/domains/ID/dns/RECORDID" \
  -H "Authorization: Bearer sk_live_..."

Response

{
  "data": {
    "ok": true
  }
}

Set the domain's nameservers

PUT/v1/domains/{id}/nameservers

Changes the nameservers at the registry (2 to 5 host names) for a domain registered with NewHost. The registry takes a few hours to publish the change; a domain that is not active here (registered elsewhere, transferring, expired) is refused. Resellers use it to point their clients' domains at their own nameservers.

Requires a secret key with the domains scope.

Parameters

NameInTypeDescription
idrequiredpathstringThe domain ID.

Body

FieldTypeDescription
nameserversrequiredarray2 to 5 different host names, e.g. ["ns1.example.co.za", "ns2.example.co.za"]. Case and a trailing dot are ignored.

Request

curl -X PUT "https://api.newhost.co.za/v1/domains/ID/nameservers" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"nameservers":["ns1.example.co.za","ns2.example.co.za"]}'

Response

{
  "data": {
    "ok": true,
    "pending": false,
    "message": null
  }
}

Next: Web & email hosting →