Edit this page

Reserve Free Domain Name Guide

The Partner API offers an endpoint that allows Partners to reserve free and available domains so they'll be minted at a later date. Reserved domains become unavailable to be claimed and minted by anyone except the Partner that reserved it for 168 hours (7 days).

Step 1: Retrieve Your Reseller ID and Secret API Token

To access your ResellerID and Secret API Token, you must navigate to your Sandbox or Production Partner dashboard. The ResellerID is used to identify the requests as coming from a Partner, while the Secret API Token is used for authentication to ensure that only authorized Partners can access the API.

Step 2: Prepare Request Body

When reserving a domain, the body must contain information about your reservation in JSON format with the following structure:

Copy
Copied
{
  "resellerIdentityKey": string // unique domain reservation identifier
}

To reserve a free and available domain, the partner must provide a unique user identifier (this could be an email or some other internal user identifier). The same identifier must be provided in the resellerIdentityKey parameter when minting the domain (using the Buy a Domain or Claim Free Domain endpoint).

Step 3: Prepare Authorization Headers

The Partner API uses bearer tokens to authorize requests with the Secret API Token from your Partner credentials.

Field Name Value
Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer Format a token provided by Unstoppable Domains

Step 4: Use the Reserve Free Domain Name Endpoint

Send a POST request with the authorization headers and request body you have prepared to check to the Reserve Free Domain Name endpoint. Here is the URL for our API environments:

Sandbox Environment:

Copy
Copied
https://api.ud-sandbox.com/api/v2/resellers/{PARTNER_RESELLERID}/domains/{DOMAIN_NAME}/reserve/

Production Environment:

Copy
Copied
https://unstoppabledomains.com/api/v2/resellers/{PARTNER_RESELLERID}/domains/{DOMAIN_NAME}/reserve/
info

The PARTNER_RESELLERID path parameter is the same one you retrieved from your partner account earlier.

Example

Here is an example request to reserve a domain name with the following parameters:

Parameter Value
Domain Name partner-test-67687986466871.crypto
Reservation ID test-reservation-id
Copy
Copied
curl --location --request POST 'https://api.ud-sandbox.com/api/v2/resellers/{PARTNER_RESELLERID}/domains/partner-test-67687986466871.crypto/reserve/' \
--header 'Authorization: Bearer {SECRET_API_TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "resellerIdentityKey": "test-reservation-id"
}'

Minting a Reserved Domain Name

To mint a domain you have reserved, you need to fill the resellerIdentityKey request body parameter in the Buy a Domain or Claim Free Domain endpoint with the domain reservation identifier.

Copy
Copied
curl --location --request POST 'https://api.ud-sandbox.com/api/v2/resellers/{PARTNER_RESELLERID}/orders/' \
--header 'Authorization: Bearer {SECRET_API_TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "payment": {
    "method": "free"
  },
  "security": "{ORDER_SECURITY}",
  "domains": [
    {
      "name": "{DOMAIN_TO_PURCHASE}",
      "ownerAddress": "{DOMAIN_OWNER_ADDRESS}",
      "resellerIdentityKey": "{DOMAIN_RESERVATION_ID}"
    }
  ]
}'
Congratulations!

You have successfully reserved a domain name with the Partner API.

Asking For Help

If you are experiencing difficulties using our services, please know that we are here to help. You can join our Discord Community for real-time support from UD and the community, where you can receive assistance with integrating your app