Summary
Every .us domain registration through the name.com API needs a valid nexus category and application purpose code in the tldRequirements payload. Map each registrant scenario to the right codes and stop 400 errors before they reach production.
Every .us domain registration through the name.com API requires a nexus data payload that most tutorials skip entirely. You can get your authentication right, construct a perfect domain registration request and still receive a 400 Bad Request because the tldRequirements object is missing or mismatched. The registry requires every .us registrant to meet a nexus requirement establishing a connection to the United States, and the API requires the corresponding nexus data at submission time .
This tutorial covers all five nexus categories exposed by our API (C11 through C32), shows how to map each registrant scenario to the correct API fields, and demonstrates building complete domain registration requests against our sandbox. You'll finish with annotated payload examples for each scenario type and a clear picture of what the API returns when the data is wrong.
One distinction worth stating upfront, the API fields described here are how you submit nexus data to the registry. Whether a given registrant actually qualifies under .us eligibility rules is a legal question for the registrant to answer, not something the API determines.
What .us nexus requirements are and why they matter
The .us TLD registry requires every registrant to meet a nexus requirement establishing a connection to the United States before a domain can be registered. This declaration travels as a tldRequirements object inside your Create Domain API request. Without it, or with invalid values, the API rejects the request with a 400 Bad Request regardless of how well-formed the rest of the payload is.
The tldRequirements object contains two fields, nexus_category and app_purpose. Both are required for every .us registration, and their values must match the codes listed in our .us requirements schema. , which mirror the registry's enumerations. An unrecognized value returns a validation error.
Sandbox setup and authentication
All examples in this tutorial target the name.com sandbox at https://api.dev.name.com. We keep sandbox and production separate, so domains registered in the sandbox don't sync to production, and TLD availability can differ between them.
Our API uses HTTP Basic Auth. For sandbox requests, append -test to your username (e.g., yourusername-test) and use the Development/Test Environment token you generate separately from your production token. Tokens are generated under Account Settings, Security, API Tokens. If your account has 2FA enabled, toggle "name.com API Access" to on in Account Settings, Security first. Newly issued sandbox credentials can take up to 15 minutes to activate.
For full setup instructions, see our Getting Started documentation. Before continuing, verify your credentials work:
# Verify sandbox credentials
curl -u yourusername-test:your-sandbox-token \
https://api.dev.name.com/core/v1/helloA successful response confirms you're authenticated and ready to proceed.
The five nexus categories and application purpose codes
The .us TLD requires two fields in every tldRequirements object, nexus_category and app_purpose. Both are required, and both must match the enumerated values defined by the registry schema, because an unrecognized value returns a validation error.
Nexus categories
The five categories map to five registrant scenarios:
Code | Registrant scenario |
|---|---|
| A natural person who is a United States citizen |
| A natural person who is a permanent resident |
| A U.S.-based organization or company formed within a U.S. state, the District of Columbia, or U.S. territories, including U.S. federal, state, or local government entities |
| A foreign organization that regularly engages in lawful activities in the United States |
| An organization that has an office or other facility in the United States |
C11 and C12 apply to individual natural persons. C21 covers domestic organizations. C31 and C32 cover foreign entities with a U.S. presence, and because both involve a non-U.S.-headquartered registrant, the organization's two-letter country code is relevant data that your collection flow needs to capture.
Application purpose codes
app_purpose declares the intended use of the domain. The five allowed values are:
Code | Purpose |
|---|---|
| Business used for profit |
| Non-profit business, club, association, or religious organization |
| Personal use |
| Educational purpose |
| Government purpose |
Both nexus_category and app_purpose are always required, regardless of which nexus code applies. The combination you submit must accurately reflect the registrant's situation.
Registrant data collection flow
Before you make the Create Domain call, your application needs to collect the right data from the registrant and map it to the correct nexus code. Getting this wrong at the collection stage produces a downstream API error that's harder to debug than a clean validation at the form level.
Nexus code | Who qualifies | Required fields in |
|---|---|---|
| U.S. citizen (natural person) |
|
| U.S. permanent resident (natural person) |
|
| U.S.-incorporated organization or government entity |
|
| Foreign organization with bona fide U.S. presence |
|
| Foreign entity with U.S. office or facility |
|
For C31 and C32 registrants, your collection form should also capture the organization's two-letter country code. The .us requirements schema specifies that this code corresponds to the organization, but the exact “Create Domain” call used to submit it should be verified against the current API schema before implementation.
Validate the complete field set before calling Create Domain. A registrant selecting C21 who has only provided individual-person data, or one choosing C31 without a country of incorporation on record, produces a rejection that client-side validation can prevent.
Our API exposes two endpoints for retrieving .us requirements programmatically.
GET /core/v1/domaininfo/requirements/usreturns a human-readable description of the TLD requirementsGET /core/v1/domaininfo/requirementsV2/usreturns the requirements as JSON Schema Draft-07
The V2 endpoint is useful for applications that drive form generation dynamically. Where the schema exposes conditional requirements, applications can use those rules to generate or validate the appropriate fields.
# Retrieve .us requirements as JSON Schema
curl -u yourusername-test:your-sandbox-token \
https://api.dev.name.com/core/v1/domaininfo/requirementsV2/usOur V2 schema separates tldInfo and tldRequirements into distinct schema sections, making it easier to identify TLD-specific requirements.
How to construct and send the tldRequirements payload
Our API expects tldRequirements inside the domain object in the Create Domain request body, not at the top level.
The Create Domain endpoint is POST /core/v1/domains.
C11 and C12 for individual U.S. citizens or permanent residents
For individual registrants, tldRequirements requires nexus_category and app_purpose.
{
"domain": {
"domainName": "example.us",
"years": 1,
"tldRequirements": {
"nexus_category": "C11", // U.S. citizen (natural person)
"app_purpose": "P3" // Personal use
}
},
"contacts": {
"registrant": {
"firstName": "Jane",
"lastName": "Smith",
"address1": "123 Main St",
"city": "Austin",
"state": "TX",
"zip": "78701",
"country": "US",
"phone": "+1.5125550100",
"email": "jane@example.com"
}
}
}Swap "C12" for a permanent resident. Select the app_purpose value that accurately reflects the domain's intended use.
curl --request POST \
--url https://api.dev.name.com/core/v1/domains \
--user yourusername-test:your-sandbox-token \
--header 'Content-Type: application/json' \
--data '{
"domain": {
"domainName": "example.us",
"years": 1,
"tldRequirements": {
"nexus_category": "C11",
"app_purpose": "P3"
}
},
"contacts": {
"registrant": {
"firstName": "Jane",
"lastName": "Smith",
"address1": "123 Main St",
"city": "Austin",
"state": "TX",
"zip": "78701",
"country": "US",
"phone": "+1.5125550100",
"email": "jane@example.com"
}
}
}'import requests
from requests.auth import HTTPBasicAuth
url = "https://api.dev.name.com/core/v1/domains"
payload = {
"domain": {
"domainName": "example.us",
"years": 1,
"tldRequirements": {
"nexus_category": "C11", # U.S. citizen
"app_purpose": "P3" // Personal use
}
},
"contacts": {
"registrant": {
"firstName": "Jane",
"lastName": "Smith",
"address1": "123 Main St",
"city": "Austin",
"state": "TX",
"zip": "78701",
"country": "US",
"phone": "+1.5125550100",
"email": "jane@example.com"
}
}
}
response = requests.post(
url,
json=payload,
auth=HTTPBasicAuth("yourusername-test", "your-sandbox-token")
)
print(response.status_code, response.json())C21 for U.S.-based organizations
For C21 registrants, tldRequirements requires nexus_category and app_purpose. Select the app_purpose value that accurately reflects the domain's intended use.
{
"domain": {
"domainName": "acmecorp.us",
"years": 1,
"tldRequirements": {
"nexus_category": "C21", // U.S.-incorporated organization
"app_purpose": "P1" // Business used for profit
}
},
"contacts": {
"registrant": {
"firstName": "Acme",
"lastName": "Corporation",
"org": "Acme Corporation",
"address1": "456 Commerce Blvd",
"city": "Chicago",
"state": "IL",
"zip": "60601",
"country": "US",
"phone": "+1.3125550200",
"email": "domains@acmecorp.example"
}
}
}C31 and C32 for foreign entities with U.S. presence
For C31 (bona fide U.S. presence, lawful activities) and C32 (physical U.S. office or facility), the registrant is a foreign organization. The .us requirements schema specifies that the organization's two-letter country code is associated with C31 and C32. Verify how that value is represented in the Create Domain request before documenting it as a contact field.
{
"domain": {
"domainName": "globalfirm.us",
"years": 1,
"tldRequirements": {
"nexus_category": "C31", // Foreign org with bona fide U.S. presence
"app_purpose": "P1" // Business used for profit
}
},
"contacts": {
"registrant": {
"firstName": "Global",
"lastName": "Firm Ltd",
"org": "Global Firm Ltd",
"address1": "10 King St",
"city": "Toronto",
"state": "ON",
"zip": "M5H 1A1",
"phone": "+1.4165550300",
"email": "domains@globalfirm.example"
}
}
}For C32, use "nexus_category": "C32" with the same structure. The requirements schema distinguishes C31 from C32 based on the type of U.S. connection described in each category. Collect enough information to allow the registrant to select the category that accurately describes their situation.
How to read error responses for invalid nexus data
When tldRequirements is missing or contains invalid values, the Create Domain request returns 400 Bad Request with a JSON body containing a message field. The message identifies the specific fields that failed validation using dot-notation paths.
If both fields are missing, our API returns:
{
"message": "tldRequirements error: tldRequirements.app_purpose: This field is required and cannot be empty; tldRequirements.nexus_category: This field is required and cannot be empty"
}If you pass a value outside the allowed enumeration, such as "C99", the API returns a validation error identifying the invalid field. . The exact wording depends on the registry validation layer, but the field path (tldRequirements.nexus_category) is consistent and sufficient to identify which field to fix.
There are two things to be on the lookout for in production:
- A form that lets users proceed without selecting a nexus category will submit a payload with
nexus_categoryabsent, producing the "is required" error. - A form that passes the display label rather than the code (e.g.,
"US Citizen"instead of"C11") produces an enum mismatch error.
Both can be caught by validating the complete tldRequirements object client-side against the schema returned by /core/v1/domaininfo/requirementsV2/us before submitting the Create Domain request. That validation step turns a round-trip API failure into an immediate form error.
Frequently asked questions about .us nexus requirements
What happens if I omit the tldRequirements object entirely from a .us registration request?
The Create Domain request returns a 400 Bad Request with a message identifying the required fields. The fix is to add tldRequirements nested inside the domain object before resubmitting.
Can I use the same nexus category for both individual and organizational registrants?
No. Categories C11 and C12 apply to natural persons, while C21, C31, and C32 apply to organizations. Select the category that accurately reflects the registrant’s situation.
What’s the difference between C31 and C32 for foreign entities?
C31 covers foreign organizations that have a bona fide presence in the U.S. through regular, lawful business or commercial activities, even without a physical office. C32 applies when the foreign entity has an actual physical office or facility located in the United States. Collect this distinction from the registrant during your onboarding flow so they select the accurate code.
Putting it all together
Retrieve the current .us requirements from the name.com Domain Info API rather than hard-coding field names. The schema is the source of truth, and requirements can change. Collect the registrant's nexus category and application purpose before reaching the Create Domain call, validate the full tldRequirements object against the schema, and submit the request with tldRequirements nested inside the domain object. Handle any 400 response by reading the field paths in the error message.
The same tldRequirements mechanism is used to pass TLD-specific registration data for other TLDs, although the required fields and validation rules vary by TLD.
Test every nexus scenario in the sandbox before going to production. Our sandbox and production environments are separate, and TLD availability and registry behavior can differ between them.
Ready to build? Explore the name.com API documentation or connect with our team for more information.
