All notable changes to the Name.com Core API will be documented here.
Name.com is launching a new Core API - a modern, RESTful API for managing domains, DNS records, and related services. It is the successor to the legacy v4 API.
- Documentation format upgraded
- Now uses OpenAPI 3.1, allowing better tooling support and interactive documentation.
- Internal implementation rebuilt
- The underlying codebase has been rewritten to support faster iteration, better error handling, and more consistent endpoint behavior.
- Improved error messaging
- Legacy 500 Internal Server Error responses have been replaced with more appropriate and descriptive HTTP status codes.
- Example: When account credit is insufficient, the response now returns 402 Payment Required instead of 500.
- 403 Forbidden responses were previously returned for both authentication errors, and actual issues where the attempted action was forbidden. Authentication errors will now correctly return 401 Unauthorized responses, and 403 Forbidden is reserved for actions that are actually forbidden.
- Legacy 500 Internal Server Error responses have been replaced with more appropriate and descriptive HTTP status codes.
- Consistent default values in responses
- API responses now always return default values (e.g. false, 0, "") instead of omitting them.
- Example: The Search API previously omitted
purchasable: false;it is now explicitly returned.
- Example: The Search API previously omitted
- API responses now always return default values (e.g. false, 0, "") instead of omitting them.
- Consistent and correct
Content-Typeheaders in responses- Previously, we had been returning
Content-Type: text/htmlfor all of our responses, even though the API returns JSON. - This has been fixed, and we will now return
Content-Type: application/jsonfor all responses that are actually returning JSON. - If endpoints are implemented that return other data types, the
Content-Typeheader will accurately reflect the data returned
- Previously, we had been returning
- Consistent requirements for
Content-Typeheaders in requests- Previously, while our documentation indicated that the
Content-Type: application/jsonheader was required for allPOSTandPUTrequests, this was not enforced. - This is now enforced across all
PUT, POST, PATCHrequests. If theContent-Type: application/jsonheader is missing, or contains a value other thanapplication/json, you will receive a response of415 Unsupported Media Typewith an appropriate message body. - Due to server implementations, this means that even
POSTrequests that do not require an actual requst body (i.e. LockDomain) will require the correctContent-Typeheader.- Documentation for the affected APIs accurately reflects this requirement.
- Previously, while our documentation indicated that the
- Deprecating several API endpoints for modifying a domain, in favor of a new UpdateDomain API
- The following endpoints are deprecated and will be removed in a future release of the API:
- LockDomain
- UnlockDomain
- EnableAutorenew
- DisableAutorenew
- EnableWhoisPrivacy
- DisableWhoisPrivacy
- The following endpoints are deprecated and will be removed in a future release of the API:
- Please note, there are more changes overall that can be listed here, and migrating from v4 to Core v1 should be considered a "breaking" change.
- SearchStream endpoint
- This endpoint has been removed for now and may return in a future version with a revised implementation.
- Domain Update Endpoint
- This new endpoint allows for updating the value for autorenew, Whois Privacy and locking. See DomainUpdate.
This release improves usability, DX/AX consistency, and future extensibility. v4 remains accessible, but we encourage new integrations to use the Core API v1.0.
- Corrected an issue where the Create Transfer API was sometimes incorrectly returning a
500 Internal Errorresponse with a message stating that there was currently a transfer processing.- This has been fixed to correctly return a
409 Conflictresponse code, with a message statingA transfer is already processing for this domain.
- This has been fixed to correctly return a
- Resolved an issue where requests failing authentication incorrectly returned a
500 Internal Server Error. The API now correctly returns a401 Unauthorizedresponse for all authentication failures. - Resolved an issue where invalid pagination parameter perPage=0 returned a
500 Internal Server Error. Paginated requests using perPage=0 now default to valid perPage=1000.
Resolved an issue where Domain Create requests would incorrectly result in a
500 Internal Server Errorif a required contact phone number was omitted. The API now correctly returns a400 Bad Requesterror with a descriptive message in this scenario.Validation Enforcement: The following documented validation rules are now strictly enforced. Requests containing non-compliant data, which may have been inadvertently accepted previously, will now be correctly rejected with a
400 Bad Requesterror response.- The
phoneandfaxfields for contacts now strictly validates the E.164 format. The API documentation has been updated with the specific regex pattern (^\+[1-9]\d{7,14}$) used for this validation. - The related examples in the documentation were also incorrect for the E.164 format and have been updated to be accurate.
- All fields designated for email addresses are now validated to ensure a valid format. Validation adheres to the
addr-specsyntax in RFC 822, with common exceptions such as not supporting comments or whitespace folding. - Enums have been added where appropriate to ensure only correct values are allowed in requests
- Additional validation was added, so that empty strings are rejected for fields like
first_name, etc.
- The
- Resolved an issue on the
List Domainsendpoint where using certain optional filters could result in a500 Internal Server Erroror return an incorrectly filtered result set. The endpoint now reliably applies all filters and returns the correct data.
- Added the new Domain Info API. This new API will return general information about a specific TLD.
- If there are additional requirements to register a domain for that TLD, the additional requirements will also be returned.
- The formatting of the additional requirements has been optimized to allow dynamic form generation.
- Several API descriptions were updated to use OpenApi v3.0 compatible structures. The API definitions in question used v3.1 constructs which several users reported issues with when using common code generation tools.
- These updated specifications contain the same actual data description, and should cause no functional changes to the API, just how the OpenApi specification describes the endpoints.
- The description for the
DomainTransferStatusChangewebhook has been updated to include a list of the transfer statuses that trigger the webhook.
- Added the new TLD Pricing API. This API gives users the ability to see a general price list for TLDs, with any account level pricing they may qualify for.
- Several API responses have been updated to more accurately describe which parameters are
required, and are therefore always returned in an API response.
- Domain Info API now correctly returns empty objects ({}) instead of empty arrays ([]) for relevant parameters as per specification.
- TLD Pricing API:
- Enforced
durationparameter validation to align with API specification limits. - Improved handling of
tldsparameter:- Invalid or unsupported TLDs are now filtered out from the request.
- If, after filtering, the
tldslist becomes empty, the API will now return a400 Bad Requestresponse.
- Enforced
- Added the new Zone Check API. Zone Check offers a rapid, preliminary check for domain availability by leveraging cached zone file data.
- Added the ability to use Idempotency keys to ensure requests are not reprocessed on the Create Domain and Purchase Privacy APIs.
- Generate a unique ID for your request, (a UUID for example), and add an
X-Idempotency-Keyheader to your requests to enable this feature for your requests. - If a repeated request is made, the APIs will respond with a
X-Idempotent-Replayheader, that has a value of 1.
- Generate a unique ID for your request, (a UUID for example), and add an
- Improved documentation and examples for Domain Create requests. The updated documentation and examples now show how to correctly create an IDN domain via the API.
- IDN domains are domains that use non-ASCII characters
- The new TLD Pricing API was occasionally omitting some of the parameters marked as required in the responses. This has been fixed.
- The Check Availability API now correctly returns a
422 Unprocessable Entityresponse when all provided domains contain unsupported TLDs, rather than malformed JSON with 2 objects.
- The underlying implementation of the Check Availability API has been reworked to optimize as best as possible for speed.
- No other changes were made to the API, and it should continue to function as it did before, just faster.
- Due to changes in ICANN policy regarding the "Company Name" (Organization) field, the related API documentation has been updated to reflect the new policy.
- The
429 Rate Limitedresponse has been updated in the OpenApi specification to indicate themessageproperty is optional.
- The createDomain API endpoint now returns a 400 Bad Request response instead of 403 Forbidden when a domain registration request fails due to missing or invalid registration requirements.