API Overview

The Name.com v4 REST API is accessed over HTTPS. The production server is https://api.name.com. The testing server is https://api.dev.name.com. To access the testing environment, use your test username (your username with "-test" appended to the end). The test environment is only available programmatically through the API. It cannot be accessed through a browser. Your test API token is listed in your API Token Management page.

Your testing account will have account credit applied so you can make purchases in the test environment. Because the testing environment is completely separate from the production environment, and it relies upon the various TLDs' testing environments, domains will not have the same availibility in testing as in production.

The JSON responses are made simpler by omitting fields that are set to their default values. For strings, the default value is the empty string. For bools, the default value is false. For numeric types, the default value is zero.

Any non-200 response will return an ErrorMessage JSON response. ErrorMessages have a "message" that gives a general error message st ring, and an optional "details" key which contains a string with additional information about the error.

Path parameters are parameters that are included in the path. For example: "/v4/domains/{domainName}/records" would be replaced with "/v4/domains/example.org/records" to view the DNS records for example.org.

Any API calls requiring the use of the HTTP POST or PUT methods (for example, Search or UpdateEmailForwarding) must set the Content-Type header to application/json. Otherwise, a status of HTTP/1.1 403 Forbidden is returned.

Pagination is provided on the List functions. These functions accept perPage and page parameters, and if there are additional pages, they will return nextPage and lastPage parameters as well as a Link header such as the one below:

Link: <https://api.name.com/v4/domains?page=3>; rel="next",
<https://api.name.com/v4/domains?page=20>; rel="last", 
<https://api.name.com/v4/domains>; rel="first", 
<https://api.name.com/v4/domains>; rel="prev"

ETag headers are provided for many Get and Create endpoints. These allow updates to be done under the condition that the underlying model hasn't changed by passing it in the If-Match header.

The Name.com v4 API has rate limits that enforce concurrent requests as well as the number of requests in a given time period. An API user should not send more than 20 requests per second or more than 3000 requests per hour. Upon hitting either of these rate limits you will receive an HTTP 429 response code. If you feel you have hit these limits in error, please contact accountservices@name.com .

NOTE:

The Development environment does not mirror the Production environment, you must register the domain within Development to test in Development. You might get a "API Response: {"message": "Not Found"}" in error. If you want to practice the requests, you will need to add DNS records to the domains "registered" within the Development environment.

Common API errors

Error: {"message":"Not Found"}
Resolution: Domain is not registered in Development environment.

Error: {"message":"Permission Denied","details":"Authentication Error - Account Has Two-Step Verification Enabled"}
Resolution: Two-Step Verification is enabled, which is not compatible with the Name.com API.

Error: {"message":"Invalid Argument","details":"Parameter Value Error - Invalid Ipv4"}
Resolution: The DNS record is invalid.

Error: {"message":"Permission Denied"}
Resolution: The production server is https://api.name.com, and the testing server is https://api.dev.name.com. User will likely need to remove "dev" from request.

Error: {"message":"Unauthenticated"}
Resolution: The URL Request has a trailing period (Period after name.com) EXAMPLE: https://api.dev.name.com./v4/domains . Or, the password has been entered but not the username, or vice versa.

Error: {"message":"Permission Denied"}
Resolution: Login credentials are incorrect.

FAQ

What are the API error codes?

We use generic RESTful API codes in addition to verbose error messaging. Refer to these codes for all responses.

Can I access the API via client-side Javascript?

Client-side Javascript is not currently supported with API v4.

Do the domains from my live account copy over to the test account?

No, the accounts are completely separate. The domains from your live account will not be in your production account.

What API Port should I use?

HTTPS(443)

Why is my GetDomain request not working?

GetDomain requests will only pull the details of domains that have been registered with the production/test account in question.

What is the keyword limit for the API?

There is a limit of 50 domains per checkAvailabilty call.

Is PowerShell supported?

PowerShell examples are not available in the documentation, but any operating system that can send HTTP requests is compatible with our API.

Can customers utilize payment profiles?

Yes, in addition to account credit.