Skip to main content

​
v4 To name.com API (Core) Migration Guide

​
Why Upgrade?

Better Documentation

CORE version uses OpenAPI 3.1-based documentation for better tooling and interactive exploration

Cleaner Errors

Cleaner, consistent error messages and HTTP status codes

Streamlined Endpoints

Streamlined, consolidated endpoints (e.g. UpdateDomain)

Enforced Standards

Enforced standards for content types and default response formatting

​
Upgrading from the legacy v4 API to the new name.com API (CORE)

Welcome to the name.com API! This new API offers a modern, RESTful interface for managing your domains, DNS records, and related services, succeeding our legacy v4 API. We’ve rebuilt the name.com API from the ground up to provide faster iteration, improved stability, more consistent behavior, and a better overall developer experience.
IMPORTANT: Breaking ChangesMigrating from the v4 API to the name.com API (CORE) is a breaking change. You will need to review and update your existing integrations to align with the new API structure, endpoints, and behaviors outlined below. The v4 API remains accessible for a transition period, but we strongly encourage all new integrations and existing integrations to migrate to the name.com API (CORE)

​
Key Changes Requiring Your Attention & Migration Steps

​
1. New API Documentation (OpenAPI 3.1)

The Core API documentation is now provided in OpenAPI 3.1 format
This offers significantly better tooling support, interactive documentation capabilities (e.g., “Try it out” features), and clearer schema definitions
Familiarize yourself with the new documentation structure. You can leverage a wide range of OpenAPI 3.1 compatible tools to generate client libraries, explore endpoints, and understand request/response models

​
2. Improved Error Handling & Messaging

We’ve overhauled error responses for clarity and accuracy:

Before

Generic 500 Internal Server Error responses for many client-side or predictable error conditions

After

More specific and appropriate HTTP status codes (e.g., 401, 402, 422)
Example: If an action fails due to insufficient account credit, the API will now return 402 Payment Required instead of the previous 500 Internal Server Error.
1

Review Error Handling

Update your error handling logic to expect and correctly process more specific HTTP status codes
2

Update Authentication Checks

Adjust authentication failure checks to look for 401 Unauthorized. Treat 403 Forbidden as a permissions issue for an authenticated user

​
3. Consistent Default Values in API Responses

API responses will now consistently include fields with their default values (e.g., false for booleans, 0 for numbers, "" for empty strings) instead of omitting them
The Search API previously omitted "purchasable": false; it is now explicitly returned as "purchasable": false
Update your response parsing logic to expect these default values. You should no longer assume that an omitted field implies a specific default (like false or null)

​
4. Correct Content-Type Headers in API Responses

Before

Content-Type: text/html was often incorrectly returned for JSON responses

After

Content-Type: application/json is now accurately set for JSON responses
Ensure your client correctly interprets the Content-Type: application/json header for JSON responses. If your client was previously ignoring or misinterpreting this header, updates may be needed.

​
5. Enforced Content-Type Header Requirements for Requests

The Content-Type: application/json header is now strictly enforced for all PUT, POST, and PATCH requests.
Important Note for Body-less POSTs: Due to server implementations, this enforcement means that even POST requests that do not require an actual request body (e.g., certain RPC-style actions like the now-deprecated LockDomain) will still require the Content-Type: application/json header.
1

Add Headers

For all PUT, POST, and PATCH requests made to the name.com Core API, you must include the header: Content-Type: application/json
2

Verify Requests

Verify this for requests that previously worked without it, including those that don’t send a JSON body

​
6. Consolidated Domain Update Functionality & Endpoint Deprecations

Several individual API endpoints for modifying domain settings have been deprecated. A new, consolidated endpoint, UpdateDomain, has been introduced to handle these actions.
PATCH /v1/domains/{domainName} (See DomainUpdate Documentation)
Migrate your domain modification logic from the deprecated endpoints to the new UpdateDomain endpoint. This endpoint allows for updating domain lock status, autorenew settings, and WHOIS Privacy settings in a single call

​
Removed Features

​
SearchStream Endpoint

This endpoint has been removed in the name.com Core API. We are evaluating a revised implementation for a future release.Action Required: If your application uses the SearchStream endpoint, you will need to remove this integration.

​
New Features

​
UpdateDomain Endpoint

New Consolidated Endpoint

  • Endpoint: PATCH /v1/domains/{domainName}
  • Purpose: Provides a consolidated and more efficient way to modify multiple domain settings such as autorenew status, WHOIS Privacy, and domain lock status
  • Recommendation: Utilize this new endpoint for all domain setting modifications

​
Overall Benefits & Next Steps

The name.com Core API is designed for improved usability, consistency, and future extensibility. The underlying codebase rewrite allows us to iterate faster, provide better error handling, and ensure more consistent behavior across all endpoints.
1

Review Documentation

Thoroughly review this guide and the new name.com Core API documentation
2

Plan Migration

Plan your migration from the legacy v4 API, prioritizing the changes outlined above
3

Test Integration

Test your updated integration extensively in a development or staging environment if available
While the legacy v4 API remains accessible during a transition period, all new development should use the name.com Core API (latest version recommended).
We appreciate your partnership and are excited to provide you with a more robust and modern API experience. Please refer to our official documentation for complete details and contact our support channels if you have any questions during your upgrade process.
⌘I