Creating an IP Address Record in Netbox via the REST API

Desired outcome

Successfully add a new IP address to Netbox, associate it with a specific device interface, set its status, and store a custom field value for tracking purposes using the Netbox REST API.

Prerequisites

• A reachable Netbox instance running version 2.11 or later with the REST API enabled.
• An API token that has write permission on the ipam.ip_addresses endpoint (read‑only tokens will cause a 403 error).
• cURL or any HTTP client capable of sending JSON payloads and custom headers.
• The numeric ID of the device interface to which the address will be assigned (obtainable via the API or the web UI).
• The exact IPv4 or IPv6 address with prefix length you intend to create (e.g., 10.0.5.23/24).

Procedure

1. Gather required identifiers

   Determine the interface ID (assigned_object_id) and confirm the content type for device interfaces (dcim.interface). You can retrieve the interface ID with a GET request such as:

   curl -s -H "Authorization: Token $NETBOX_TOKEN" \
     https://netbox.example.com/api/dcim/interfaces/?name=eth0&device_id=42 | jq '.results[0].id'
   

   Replace $NETBOX_TOKEN with your token, adjust the hostname, and set the appropriate device_id and interface name.

2. Build the JSON payload

   Create a file (e.g., ip-payload.json) containing the fields required by the /api/ipam/ip-addresses/ endpoint:

   
   {
     "address": "10.0.5.23/24",
     "status": "active",
     "assigned_object_type": "dcim.interface",
     "assigned_object_id": 128,
     "custom_fields": {
       "ticket_id": "INC123456"
     }
   }
   

   Adjust address, status (choose from Netbox status choices), assigned_object_id, and any custom field names/values to match your environment.

3. Send the POST request

   Execute the following command, ensuring you are in a shell where the token variable is defined:

   curl -s -w "\nHTTP %{http_code}" -X POST \
     -H "Authorization: Token $NETBOX_TOKEN" \
     -H "Content-Type: application/json" \
     -d @ip-payload.json \
     https://netbox.example.com/api/ipam/ip-addresses/
   

   The command outputs the HTTP status code and the response body. A successful creation returns 201 Created and a JSON object that includes the newly assigned id.

4. Capture the created ID

   Extract the id from the response for later verification or rollback, for example:

   CREATED_ID=$(curl -s -H "Authorization: Token $NETBOX_TOKEN" \
     -H "Content-Type: application/json" \
     -d @ip-payload.json \
     https://netbox.example.com/api/ipam/ip-addresses/ | jq '.id')
   

Expected checks

1. Immediate API verification

   Issue a GET request using the captured ID and compare the returned fields with the original payload:

   curl -s -H "Authorization: Token $NETBOX_TOKEN" \
     https://netbox.example.com/api/ipam/ip-addresses/$CREATED_ID/ | jq .
   

   Confirm that address, status, assigned_object_type, assigned_object_id, and custom_fields match the values you submitted.

2. Web UI verification (optional)

   Log into Netbox, navigate to IPAM → IP Addresses, paste the address into the filter box, and verify that the interface, status, and custom field values appear as expected.

Recovery and rollback options

If the POST returns a non‑201 status (e.g., 400 for a duplicate address or missing interface), inspect the response body for validation messages, correct the payload, and retry.

To remove the address after it has been created, issue a DELETE request using the same token:

curl -s -w "\nHTTP %{http_code}" -X DELETE \
  -H "Authorization: Token $NETBOX_TOKEN" \
  https://netbox.example.com/api/ipam/ip-addresses/$CREATED_ID/

A successful deletion returns 204 No Content. Verify removal by attempting a GET on the same ID; you should receive 404 Not Found.

Limitations and notes

• The assigned_object_type and assigned_object_id fields are only available in Netbox 2.10+. Using them on earlier versions will produce a 400 error.
• Ensure the API token’s scope is limited to the required endpoints; overly broad tokens increase the risk of unintended data modification.
• Custom field names must exactly match those defined in Netbox’s Extras → Custom Fields; mismatched names are ignored silently.
• Always test changes in a staging or development Netbox instance before applying them to production.