Setup netlify DNS on a site via API only

Sorry for crossposting but I have seen a couple similar issues that just point to some docs that doesn’t seem to clear my doubt.

I am creating some netlify sites and the process is fully automated so it has to be entirely handled via APIs.
All works well up to the point to connect a custom domain to the site.

I am using the updateSite method of the node client and passing the custom domain (let’s say to the domain_aliases array.
At this point though, is not a netlify domain (it is registered in

What I am doing is that in, I configure that site to use netlify dns ( etc). Then, I would like to set that new domain as primary domain and to have it use the netlify DNS.
I don’t understand how to do this step via API. I see that there are some DNS ZONE APIs but that is not about a specific site or domain.

The issue is, I cannot even test out if just connecting it like this works, because I am not actually purchasing those domains, I am using a sandbox in namecheap (since it is just development).
So on netlify, the domain does not connect well (it is not detected as a netlify domain).

Before running in production outside of the sandbox, I would like to clearify if what I am doing is correct and complete.

Another approach would perhaps be to keep using the DNS of the registrar, but point the A record to the netlify IP? anyways I would greatly prefer to use the DNS of netlify if I can get it work programmatically.

Hi, @stilllife00. It sounds like you want to test this but don’t want to use a real domain.

You will need a real domain to test. Nothing at Netlify will change that.

However, if you have a domain you do control and which is not using Netlify DNS already (like, you can use that to test.

If you don’t make any changes at the registrar, then you can create and delete Netlify DNS zones for that domain as a test without impacting what the domain really does (because you won’t ever actually update the name servers to point to Netlify).

If you want to test the DNS record in the inactive zone, you can do so by querying whatever the Netlify DNS name server is configured for the zone. For example, using dig (my favorite DNS troubleshooting tool) you might do this:

dig A

(Replacing the # characters with the real values from Netlify DNS.)

Again though, you will need a real domain to test. If there are other questions about this, please let us know.

Beside testing, my question was how to set the domain as primary domain and connect the Netlify DNS via API

Anyways, I bought a cheap real domain for testing and with some trial and error I think I managed to succeed:

const wwwDomain = ""
const domain = ""
const id = "123456"

// this adds the domain to the site
await netlifyClient.updateSite({
    site_id: id, // this is the id of my Netlify site
    body: {
      custom_domain: wwwDomain, // setting the "custom_domain" is the way to make it "primary"
      domain_aliases: [
      managed_dns: true // not sure this is required and what it means

// this uses the netlify DNS for that site
// I am not sure this step is required if the domain in the registrar was already configured to the same
// dns servers, but it does not seem to hurt anyways
await netlifyClient.configureDNSForSite({
    site_id: id,
    body: {
      dns_servers: [

I would just like to have a confirmation if what I am doing is how’s supposed to be done

Hi, @stilllife00. Are you using the js-client for this? → GitHub - netlify/js-client: A Open-API derived JS + Node.js API client for Netlify

My best recommendation for confirming best practices with our API can found here:

For undocumented endpoints or if you are unsure about implementation details, make the change using our web UI and then inspect the API calls made using the devtools in the browser. This will show you a working example so you can duplicate that in your code.

I do see one very big problem in the code above:

      dns_servers: [

You appear to have hard-coded one specific set of name servers (the “p08” set). There are several and they are assigned dynamically when new DNS zones are created. If you are working with a single DNS zone and it might be safe to hardcode that list. However, if you are dynamically making new DNS zones, you will need to check the return value of the API call (or query the created zone with a new API call) to see what name servers you should be using.

If there are other questions about this, please let us know.

Thanks for the heads up on the DNS zone.
I still fail to understand though how to get the correct set for my site.

The site is created with netlifyClient.createSite, deployed with netlifyClient.deploy, set my custom domain with netlifyClient.updateSite and then I set the DNS with netlifyClient.configureDNSForSite. How can I receive the correct pXX information to pass to the last method ?

I am not willingly making new zones, I just see different sets (p01, p02…,p08) are automatically created by netlify on my sites, and I don’t know which one to pick for a fresh new site.

Hey @stilllife00,
I believe we assign them for you- you just need to include the site ID in your API call, not DNS servers. Let us know if that helps!