Skip to content
Cloudflare Docs

Set up reference zones

During an internal DNS query resolution, if no internal record is found within a matching internal zone, Cloudflare will check if the matching internal zone is referencing another internal zone. Successive references can be followed with a maximum of five references in a chain.

Each internal zone can only reference one other zone, but the same zone can be referenced by multiple internal zones. Public zones cannot be used as reference zones.

Steps

To set up a reference zone, use the Update DNS settings endpoint. In --data, specify the internal_dns object with the parameter reference_zone_id.

In the following example, internal zone A (ID 8a904aeb565c42cfa207d98f6edea2f3) is referencing internal zone B (ID 8e64c6fb4b514f3faf64de81efc11e51).

Terminal window
curl --request PATCH \
https://api.cloudflare.com/client/v4/zones/8a904aeb565c42cfa207d98f6edea2f3/dns_settings \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--header "Content-Type: application/json" \
--data '{
    "internal_dns": {
        "reference_zone_id": "8e64c6fb4b514f3faf64de81efc11e51"
    }
  }'

A third zone (C) could also point to zone B as a reference, but zone A cannot add another zone as a reference while also having zone B configured as its reference zone.