Domain Management API

The Domain Management API allows you to retrieve and manage domains purchased by your users.

Get User Domains

Retrieves all domains belonging to a specific user.

Endpoint: GET /api/v1/users/{user_identifier}/domains

Request

http

GET /api/v1/users/user_123/domains
Authorization: Bearer YOUR_API_KEY

Response

json

{
  "domains": [
    {
      "id": "dom_abc123",
      "name": "example.com",
      "status": "active",
      "purchased_at": "2025-01-01T00:00:00Z",
      "expires_at": "2026-01-01T00:00:00Z",
      "auto_renew": true,
      "dns_records_count": 8,
      "registrar": "pocketdns"
    }
  ],
  "total": 1
}

Domain Object Fields

Field	Type	Description
`id`	string	Unique domain identifier
`name`	string	Domain name (e.g., "example.com")
`status`	string	Domain status (`active`, `pending`, `expired`, `suspended`)
`purchased_at`	string	ISO 8601 timestamp of purchase
`expires_at`	string	ISO 8601 timestamp of expiration
`auto_renew`	boolean	Whether auto-renewal is enabled
`dns_records_count`	integer	Number of DNS records configured
`registrar`	string	Domain registrar

Examples

javascript

const getUserDomains = async (userIdentifier) => {
  const response = await fetch(
    `https://api.pocketdns.com/api/v1/users/${userIdentifier}/domains`,
    {
      headers: {
        'Authorization': 'Bearer sk_live_...'
      }
    }
  );

  const { domains } = await response.json();
  return domains;
};

const domains = await getUserDomains('user_123');
console.log(`User has ${domains.length} domains`);

Get Domain Details

Retrieves detailed information about a specific domain.

Endpoint: GET /api/v1/domains/{domain_id}

Request

http

GET /api/v1/domains/dom_abc123
Authorization: Bearer YOUR_API_KEY

Response

json

{
  "id": "dom_abc123",
  "name": "example.com",
  "user_identifier": "user_123",
  "status": "active",
  "purchased_at": "2025-01-01T00:00:00Z",
  "expires_at": "2026-01-01T00:00:00Z",
  "auto_renew": true,
  "registrar": "pocketdns",
  "nameservers": [
    "ns1.pocketdns.com",
    "ns2.pocketdns.com"
  ],
  "whois_privacy": true,
  "dns_records": [
    {
      "id": "rec_xyz789",
      "type": "A",
      "name": "@",
      "content": "192.0.2.1",
      "ttl": 300,
      "created_at": "2025-01-01T01:00:00Z"
    }
  ],
  "pricing": {
    "registration_price": "12.99",
    "renewal_price": "12.99",
    "currency": "USD"
  }
}

Extended Fields

Field	Type	Description
`nameservers`	array	List of nameserver hostnames
`whois_privacy`	boolean	Whether WHOIS privacy is enabled
`dns_records`	array	Array of DNS record objects
`pricing`	object	Pricing information

Examples

javascript

const getDomainDetails = async (domainId) => {
  const response = await fetch(
    `https://api.pocketdns.com/api/v1/domains/${domainId}`,
    {
      headers: {
        'Authorization': 'Bearer sk_live_...'
      }
    }
  );

  return await response.json();
};

const domain = await getDomainDetails('dom_abc123');
console.log(`Domain ${domain.name} expires on ${domain.expires_at}`);

Update Domain Settings

Updates domain configuration settings.

Endpoint: PUT /api/v1/domains/{domain_id}

Request

http

PUT /api/v1/domains/dom_abc123
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "auto_renew": false,
  "whois_privacy": true
}

Parameters

Parameter	Type	Required	Description
`auto_renew`	boolean	No	Enable/disable automatic renewal
`whois_privacy`	boolean	No	Enable/disable WHOIS privacy protection

Response

json

{
  "id": "dom_abc123",
  "name": "example.com",
  "auto_renew": false,
  "whois_privacy": true,
  "updated_at": "2025-01-06T12:30:00Z"
}

Examples

javascript

const updateDomain = async (domainId, settings) => {
  const response = await fetch(
    `https://api.pocketdns.com/api/v1/domains/${domainId}`,
    {
      method: 'PUT',
      headers: {
        'Authorization': 'Bearer sk_live_...',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(settings)
    }
  );

  return await response.json();
};

// Disable auto-renewal
await updateDomain('dom_abc123', { auto_renew: false });

Renew Domain

Manually renews a domain for additional years.

Endpoint: POST /api/v1/domains/{domain_id}/renew

Request

http

POST /api/v1/domains/dom_abc123/renew
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "years": 1
}

Parameters

Parameter	Type	Required	Description
`years`	integer	Yes	Number of years to renew (1-10)

Response

json

{
  "id": "dom_abc123",
  "name": "example.com",
  "expires_at": "2027-01-01T00:00:00Z",
  "renewal_cost": "12.99",
  "currency": "USD",
  "renewed_at": "2025-01-06T12:30:00Z"
}

Examples

javascript

const renewDomain = async (domainId, years) => {
  const response = await fetch(
    `https://api.pocketdns.com/api/v1/domains/${domainId}/renew`,
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer sk_live_...',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ years })
    }
  );

  return await response.json();
};

// Renew domain for 2 years
const renewal = await renewDomain('dom_abc123', 2);
console.log(`Domain renewed until ${renewal.expires_at}`);

Transfer Domain

Initiates a domain transfer to PocketDNS.

Endpoint: POST /api/v1/domains/transfer

Request

http

POST /api/v1/domains/transfer
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "domain_name": "example.com",
  "user_identifier": "user_123",
  "auth_code": "transfer123",
  "extend_registration": true
}

Parameters

Parameter	Type	Required	Description
`domain_name`	string	Yes	Domain name to transfer
`user_identifier`	string	Yes	User who will own the domain
`auth_code`	string	Yes	Authorization code from current registrar
`extend_registration`	boolean	No	Whether to extend registration by 1 year

Response

json

{
  "transfer_id": "txr_def456",
  "domain_name": "example.com",
  "status": "pending",
  "estimated_completion": "2025-01-13T12:00:00Z",
  "cost": "12.99",
  "currency": "USD"
}

Examples

javascript

const transferDomain = async (domainName, userIdentifier, authCode) => {
  const response = await fetch(
    'https://api.pocketdns.com/api/v1/domains/transfer',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer sk_live_...',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        domain_name: domainName,
        user_identifier: userIdentifier,
        auth_code: authCode,
        extend_registration: true
      })
    }
  );

  return await response.json();
};

const transfer = await transferDomain('example.com', 'user_123', 'auth123');
console.log(`Transfer initiated: ${transfer.transfer_id}`);

Get Transfer Status

Checks the status of a domain transfer.

Endpoint: GET /api/v1/domains/transfers/{transfer_id}

Request

http

GET /api/v1/domains/transfers/txr_def456
Authorization: Bearer YOUR_API_KEY

Response

json

{
  "transfer_id": "txr_def456",
  "domain_name": "example.com",
  "status": "completed",
  "started_at": "2025-01-06T12:00:00Z",
  "completed_at": "2025-01-10T15:30:00Z",
  "domain_id": "dom_ghi789"
}

Transfer Status Values

Status	Description
`pending`	Transfer request submitted
`in_progress`	Transfer is being processed
`completed`	Transfer completed successfully
`failed`	Transfer failed
`cancelled`	Transfer was cancelled

Examples

javascript

const checkTransferStatus = async (transferId) => {
  const response = await fetch(
    `https://api.pocketdns.com/api/v1/domains/transfers/${transferId}`,
    {
      headers: {
        'Authorization': 'Bearer sk_live_...'
      }
    }
  );

  return await response.json();
};

const status = await checkTransferStatus('txr_def456');
if (status.status === 'completed') {
  console.log(`Transfer completed! Domain ID: ${status.domain_id}`);
}

List Available TLDs

Gets a list of available top-level domains and their pricing.

Endpoint: GET /api/v1/domains/tlds

Request

http

GET /api/v1/domains/tlds
Authorization: Bearer YOUR_API_KEY

Response

json

{
  "tlds": [
    {
      "tld": "com",
      "registration_price": "12.99",
      "renewal_price": "12.99",
      "transfer_price": "12.99",
      "currency": "USD",
      "available": true
    },
    {
      "tld": "org",
      "registration_price": "14.99",
      "renewal_price": "14.99",
      "transfer_price": "14.99",
      "currency": "USD",
      "available": true
    }
  ]
}

Examples

javascript

const getAvailableTLDs = async () => {
  const response = await fetch(
    'https://api.pocketdns.com/api/v1/domains/tlds',
    {
      headers: {
        'Authorization': 'Bearer sk_live_...'
      }
    }
  );

  const { tlds } = await response.json();
  return tlds;
};

const tlds = await getAvailableTLDs();
console.log(`${tlds.length} TLDs available`);

Check Domain Availability

Checks if a domain name is available for registration.

Endpoint: GET /api/v1/domains/availability/{domain_name}

Request

http

GET /api/v1/domains/availability/example.com
Authorization: Bearer YOUR_API_KEY

Response

json

{
  "domain_name": "example.com",
  "available": false,
  "price": null,
  "currency": null,
  "premium": false,
  "suggestions": [
    "example.net",
    "example.org",
    "myexample.com"
  ]
}

Response Fields

Field	Type	Description
`available`	boolean	Whether domain is available for registration
`price`	string	Registration price (null if unavailable)
`premium`	boolean	Whether this is a premium domain
`suggestions`	array	Alternative domain suggestions

Examples

javascript

const checkAvailability = async (domainName) => {
  const response = await fetch(
    `https://api.pocketdns.com/api/v1/domains/availability/${domainName}`,
    {
      headers: {
        'Authorization': 'Bearer sk_live_...'
      }
    }
  );

  return await response.json();
};

const result = await checkAvailability('example.com');
if (result.available) {
  console.log(`${result.domain_name} is available for $${result.price}`);
} else {
  console.log(`Try these alternatives: ${result.suggestions.join(', ')}`);
}

Common Error Codes

Status Code	Error Code	Description
400	`validation_error`	Request data is invalid
401	`unauthorized`	Invalid or missing API key
403	`forbidden`	Access denied to domain
404	`not_found`	Domain not found
409	`conflict`	Domain already exists or transfer in progress
422	`unprocessable_entity`	Invalid domain name or settings
429	`rate_limit_exceeded`	Too many requests
500	`internal_error`	Server error

Rate Limits

Domain retrieval: 1000 requests per minute
Domain updates: 60 requests per minute
Domain transfers: 10 requests per minute
Availability checks: 500 requests per minute

Best Practices

Cache domain data to reduce API calls
Validate domain names before API requests
Handle transfer delays appropriately (can take 5-7 days)
Monitor domain expiration dates proactively
Use batch operations when available
Implement proper error handling for all operations

Domain Management API ​

Get User Domains ​

Request ​

Response ​

Domain Object Fields ​

Examples ​

Get Domain Details ​

Request ​

Response ​

Extended Fields ​

Examples ​

Update Domain Settings ​

Request ​

Parameters ​

Response ​

Examples ​

Renew Domain ​

Request ​

Parameters ​

Response ​

Examples ​

Transfer Domain ​

Request ​

Parameters ​

Response ​

Examples ​

Get Transfer Status ​

Request ​

Response ​

Transfer Status Values ​

Examples ​

List Available TLDs ​

Request ​

Response ​

Examples ​

Check Domain Availability ​

Request ​

Response ​

Response Fields ​

Examples ​

Common Error Codes ​

Rate Limits ​

Best Practices ​

Domain Management API

Get User Domains

Request

Response

Domain Object Fields

Examples

Get Domain Details

Request

Response

Extended Fields

Examples

Update Domain Settings

Request

Parameters

Response

Examples

Renew Domain

Request

Parameters

Response

Examples

Transfer Domain

Request

Parameters

Response

Examples

Get Transfer Status

Request

Response

Transfer Status Values

Examples

List Available TLDs

Request

Response

Examples

Check Domain Availability

Request

Response

Response Fields

Examples

Common Error Codes

Rate Limits

Best Practices