# Set DHCP Scope
## Endpoint
`/api/dhcp/scopes/set`
Obsolete path: `/api/setDhcpScope`
## Method
GET
## Description
Sets (creates or updates) a DHCP scope configuration. When creating a new scope, `startingAddress`, `endingAddress`, and `subnetMask` are required. When updating an existing scope, only the parameters being changed need to be provided. This endpoint can also rename scopes via the `newName` parameter.
## Authentication
Required. Token must have **DhcpServer: Modify** permission.
## Parameters
| `token` | string | Yes | No | The session token generated by the `login` or the `createToken` call. |
| `name` | string | Yes | No | The name of the DHCP scope. When creating a new scope, this becomes the scope name. |
| `newName` | string | No | No | The new name of the DHCP scope. Used to rename an existing scope. |
| `startingAddress` | string | No | Yes | The starting IP address of the DHCP scope. Required when creating a new scope. |
| `endingAddress` | string | No | Yes | The ending IP address of the DHCP scope. Required when creating a new scope. |
| `subnetMask` | string | No | Yes | The subnet mask of the network. Required when creating a new scope. |
| `leaseTimeDays` | integer | No | No | The lease time in number of days. |
| `leaseTimeHours` | integer | No | No | The lease time in number of hours. |
| `leaseTimeMinutes` | integer | No | No | The lease time in number of minutes. |
| `offerDelayTime` | integer | No | No | The time duration in milliseconds that the DHCP server delays sending a DHCPOFFER message. |
| `pingCheckEnabled` | boolean | No | No | Set to `true` to allow the DHCP server to ping an IP address before offering it, preventing conflicts with manually configured devices. |
| `pingCheckTimeout` | integer | No | No | The timeout interval in milliseconds to wait for a ping reply. |
| `pingCheckRetries` | integer | No | No | The maximum number of ping requests to try. |
| `domainName` | string | No | No | The domain name for the network. The DHCP server automatically adds forward and reverse DNS entries for each IP allocation when configured. (Option 15) |
| `domainSearchList` | string | No | No | A comma-separated list of domain names that clients can use as a suffix when searching a domain name. (Option 119) |
| `dnsUpdates` | boolean | No | No | Set to `true` to allow the DHCP server to automatically update forward and reverse DNS entries for clients. |
| `dnsOverwriteForDynamicLease` | boolean | No | No | Set to `true` to allow the DHCP server to overwrite existing DNS A records matching the client domain name for dynamic leases. |
| `dnsTtl` | integer | No | No | The TTL value in seconds used for forward and reverse DNS records. |
| `serverAddress` | string | No | No | The IP address of next server (TFTP) for bootstrap. If not specified, the DHCP server's own IP address is used. (siaddr) |
| `serverHostName` | string | No | No | The optional bootstrap server host name for TFTP identification. (sname/Option 66) |
| `bootFileName` | string | No | No | The boot file name on the TFTP server for client bootstrap. (file/Option 67) |
| `routerAddress` | string | No | No | The default gateway IP address for clients. (Option 3) |
| `useThisDnsServer` | boolean | No | No | Set to `true` to use this DNS server's IP address for the DNS Servers DHCP option. |
| `dnsServers` | string | No | No | A comma-separated list of DNS server IP addresses for clients. Ignored when `useThisDnsServer` is `true`. (Option 6) |
| `winsServers` | string | No | No | A comma-separated list of NBNS/WINS server IP addresses for clients. (Option 44) |
| `ntpServers` | string | No | No | A comma-separated list of NTP server IP addresses for clients. (Option 42) |
| `ntpServerDomainNames` | string | No | No | NTP server domain names (e.g., `pool.ntp.org`) that the DHCP server should automatically resolve and pass the resolved IP addresses to clients as the NTP server option. (Option 42) |
| `staticRoutes` | string | No | No | A pipe-separated (`\|`) list of static routes in format `{destination}|{subnetMask}|{router}` for clients to access specified destination networks. (Option 121) |
| `vendorInfo` | string | No | No | A pipe-separated (`\|`) list of vendor information in format `{vendor class identifier}|{vendor specific information}` where vendor specific information is a colon-separated hex string or a normal hex string. |
| `capwapAcIpAddresses` | string | No | No | A comma-separated list of CAPWAP Access Controller IP addresses for Wireless Termination Points. (Option 138) |
| `tftpServerAddresses` | string | No | No | A comma-separated list of TFTP Server Addresses or VoIP Configuration Server Addresses. (Option 150) |
| `genericOptions` | string | No | No | A pipe-separated (`\|`) list of custom DHCP options in format `{option-code}|{hex-string-value}` where the value is a colon-separated hex string or normal hex string. |
| `exclusions` | string | No | No | A pipe-separated (`\|`) list of IP address ranges in format `{startingAddress}|{endingAddress}` to exclude from dynamic allocation. |
| `reservedLeases` | string | No | No | A pipe-separated (`\|`) list of reserved IP addresses in format `{hostName}|{MAC address}|{reserved IP address}|{comments}` assigned to specific clients by MAC address. |
| `allowOnlyReservedLeases` | boolean | No | No | Set to `true` to stop dynamic IP allocation and only assign reserved IP addresses. |
| `blockLocallyAdministeredMacAddresses` | boolean | No | No | Set to `true` to block dynamic IP allocation for clients with locally administered MAC addresses (0x02 bit set in the first octet). |
| `ignoreClientIdentifierOption` | boolean | No | No | Set to `true` to always use the client's MAC address as the identifier instead of the Client Identifier (Option 61). Changing this may cause existing clients to get a different IP on renewal. |
## Response Fields
Empty response object on success.
## Conditional Logic Notes
- **Creating a new scope**: `startingAddress`, `endingAddress`, and `subnetMask` are all required. Other parameters are optional and will use defaults.
- **Updating an existing scope**: Only the parameters being changed need to be provided. The `name` parameter identifies the existing scope.
- **Renaming a scope**: Provide the current name in `name` and the desired name in `newName`.
- **`dnsServers` is ignored when `useThisDnsServer` is `true`**: The server will use its own IP address instead of any explicitly provided DNS servers.
- **`ignoreClientIdentifierOption` warning**: Changing this option may cause existing clients to receive different IP lease allocations on renewal.
## Edge Cases
- **Pipe-separated compound parameters**: `staticRoutes`, `vendorInfo`, `genericOptions`, `exclusions`, and `reservedLeases` use pipe (`|`) as both an inter-entry separator and an intra-entry field separator. For example, `staticRoutes` with two routes would look like: `172.16.0.0|255.255.255.0|192.168.1.2|10.0.0.0|255.0.0.0|192.168.1.3`. The parser presumably splits on `|` and groups by the expected number of fields per entry.
- **Comma-separated list parameters**: `domainSearchList`, `dnsServers`, `winsServers`, `ntpServers`, `ntpServerDomainNames`, `capwapAcIpAddresses`, and `tftpServerAddresses` use commas as separators.
- **Empty string clears a value**: Parameters like `serverAddress`, `serverHostName`, and `bootFileName` can be set to empty string to clear them (as shown in the URL example).
- **`reservedLeases` format**: Each entry has 4 fields: `{hostName}|{MAC address}|{reserved IP address}|{comments}`. The hostname and comments fields may be empty strings within the pipe-delimited structure.
- **`vendorInfo` hex values**: The vendor-specific information can be either colon-separated hex (e.g., `06:01:03`) or a plain hex string.
- **`genericOptions` hex values**: Same dual hex format support as `vendorInfo`.
- **Setting any list parameter presumably replaces the entire list** rather than appending to it, since this is a "set" operation.
- **`ntpServerDomainNames`** is an additional parameter not visible in the Get response -- it provides domain names that the server resolves automatically, with the results appearing in the `ntpServers` response field.