API Documentation

Integrate namepick.co services into your applications with our comprehensive API

Getting Started

Learn how to authenticate and make your first API request

Base URL

https://namepick.co/api

Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Rate Limiting

API rate limits vary by plan:

Starter: 1,000 requests/hour
Professional: 10,000 requests/hour
Enterprise: Unlimited

Rate limit information is included in response headers:

X-RateLimit-Limit: Maximum requests per hour
X-RateLimit-Remaining: Remaining requests
X-RateLimit-Reset: Time when limit resets

Domain Management

POST/api/domains/check

Check domain availability and pricing

Parameters

domainstring* - Domain name to check (e.g., "example.com")

Example Request

{
  "domain": "example.com"
}

Example Response

{
  "domain": "example.com",
  "available": true,
  "price": 9.99,
  "currency": "GBP",
  "premium": false,
  "extension": ".com"
}

POST/api/domains/register

Parameters

domainstring* - Domain name to register

yearsnumber - Registration period (1-10 years, default: 1)

nameserversarray - Custom nameservers (optional)

Example Request

{
  "domain": "example.com",
  "years": 1,
  "nameservers": [
    "ns1.namepick.co",
    "ns2.namepick.co"
  ]
}

Example Response

{
  "success": true,
  "domain": "example.com",
  "status": "registered",
  "expiryDate": "2026-01-06",
  "orderId": "ORD-123456"
}

POST/api/domains/whois

Perform WHOIS lookup

Parameters

domainstring* - Domain to lookup

Example Request

{
  "domain": "example.com"
}

Example Response

{
  "domain": "example.com",
  "available": false,
  "registrar": "Example Registrar Ltd",
  "createdDate": "2020-01-15",
  "expiryDate": "2025-01-15",
  "nameServers": ["ns1.example.com", "ns2.example.com"],
  "status": ["clientTransferProhibited"]
}

DNS Management

POST/api/domains/dns

Get DNS records for a domain

Parameters

domainstring* - Domain to check DNS records

Example Request

{
  "domain": "example.com"
}

Example Response

{
  "domain": "example.com",
  "records": {
    "A": [{"name": "example.com", "value": "192.0.2.1", "ttl": 3600}],
    "MX": [{"name": "example.com", "value": "10 mail.example.com", "ttl": 3600}],
    "TXT": [{"name": "example.com", "value": "v=spf1 -all", "ttl": 3600}]
  }
}

SSL Certificates

POST/api/domains/ssl

Check SSL certificate status

Parameters

domainstring* - Domain to check SSL certificate

Example Request

{
  "domain": "example.com"
}

Example Response

{
  "domain": "example.com",
  "valid": true,
  "issuer": {
    "organization": "Let's Encrypt",
    "commonName": "R3"
  },
  "validFrom": "2024-11-06T00:00:00Z",
  "validTo": "2025-02-04T23:59:59Z",
  "daysRemaining": 29,
  "grade": "A+"
}

Reseller API

POST/api/reseller/apply

Apply for reseller account

Parameters

companyNamestring* - Company name

emailstring* - Contact email

phonestring* - Contact phone number

planstring* - Plan type: reseller_starter, reseller_professional, or reseller_enterprise

companyWebsitestring - Company website URL

businessTypestring - Type of business

Example Request

{
  "companyName": "Web Solutions Ltd",
  "email": "contact@websolutions.com",
  "phone": "+44 20 1234 5678",
  "plan": "reseller_professional",
  "companyWebsite": "https://websolutions.com",
  "businessType": "Web Design Agency"
}

Example Response

{
  "success": true,
  "resellerId": "RES-123456",
  "status": "pending",
  "message": "Application submitted successfully. We'll review it within 24 hours."
}

GET/api/reseller/account

Get reseller account details

Parameters

Example Request

GET /api/reseller/account
Authorization: Bearer YOUR_SESSION_TOKEN

Example Response

{
  "reseller": {
    "id": "RES-123456",
    "companyName": "Web Solutions Ltd",
    "status": "active",
    "resellerType": "professional",
    "accountBalance": 1234.56,
    "totalRevenue": 5678.90,
    "totalCommission": 890.12,
    "commissionRates": {
      "domain": 20,
      "ssl": 25,
      "email": 30
    }
  }
}

GET/api/reseller/products

Get product catalog with reseller pricing

Parameters

typestring - Filter by product type: domain, ssl, email

categorystring - Filter domains by category: generic, country, new

Example Request

GET /api/reseller/products?type=domain
Authorization: Bearer YOUR_SESSION_TOKEN

Example Response

{
  "domains": [
    {
      "id": "domain-.com",
      "name": ".com",
      "basePrice": 9.99,
      "resellerPrice": 7.99,
      "commissionRate": 20,
      "commissionAmount": 2.00
    }
  ],
  "resellerInfo": {
    "type": "professional",
    "commissionRates": {
      "domain": 20,
      "ssl": 25,
      "email": 30
    }
  }
}

GET/api/reseller/orders

Get reseller orders

Parameters

pagenumber - Page number (default: 1)

limitnumber - Results per page (default: 10)

statusstring - Filter by status: pending, processing, completed, failed, cancelled

Example Request

GET /api/reseller/orders?status=completed&limit=10
Authorization: Bearer YOUR_SESSION_TOKEN

Example Response

{
  "orders": [
    {
      "id": "RO-ABC123DEF4",
      "domainName": "example.com",
      "tld": ".com",
      "customerEmail": "john@example.com",
      "customerName": "John Doe",
      "registrationPrice": 12.99,
      "costPrice": 10.39,
      "commission": 2.60,
      "status": "completed",
      "orderDate": "2025-01-06T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 42,
    "totalPages": 5
  }
}

POST/api/reseller/orders

Create a new order

Parameters

domainNamestring* - Domain name without TLD

tldstring* - Top-level domain (e.g., .com, .net)

yearsnumber - Registration period in years (1-10, default: 1)

customerEmailstring* - Customer email address

customerNamestring* - Customer full name

registrationPricenumber* - Price charged to customer

whoisPrivacyboolean - Enable WHOIS privacy (default: false)

Example Request

{
  "domainName": "example",
  "tld": ".com",
  "years": 1,
  "customerEmail": "john@example.com",
  "customerName": "John Doe",
  "customerCompany": "Example Corp",
  "registrationPrice": 12.99,
  "whoisPrivacy": true,
  "autoRenew": true
}

Example Response

{
  "success": true,
  "order": {
    "id": "RO-XYZ789ABC1",
    "status": "pending",
    "domainName": "example.com",
    "commission": 2.60,
    "orderDate": "2025-01-06T14:30:00Z"
  }
}

GET/api/reseller/transactions

Get transaction history

Parameters

pagenumber - Page number (default: 1)

limitnumber - Results per page (default: 20)

typestring - Filter by type: credit, debit, commission, bonus, refund, payout

startDatestring - Start date (ISO 8601)

endDatestring - End date (ISO 8601)

Example Request

GET /api/reseller/transactions?type=commission&limit=5
Authorization: Bearer YOUR_SESSION_TOKEN

Example Response

{
  "transactions": [
    {
      "id": "RT-ABC123DEF4",
      "type": "commission",
      "amount": 2.60,
      "balance": 1237.16,
      "description": "Commission for order RO-XYZ789ABC1: example.com",
      "referenceType": "order",
      "referenceId": "RO-XYZ789ABC1",
      "createdAt": "2025-01-06T14:35:00Z"
    }
  ],
  "summary": {
    "totalCount": 150,
    "totalCredits": 5678.90,
    "totalDebits": 4444.34,
    "totalCommission": 890.12,
    "currentBalance": 1234.56
  },
  "pagination": {
    "page": 1,
    "limit": 5,
    "totalPages": 30
  }
}

GET/api/reseller/payouts

Get payout information

Parameters

statusstring - Filter by status: pending, processing, completed, failed

Example Request

GET /api/reseller/payouts
Authorization: Bearer YOUR_SESSION_TOKEN

Example Response

{
  "summary": {
    "availableBalance": 1234.56,
    "pendingPayouts": 0,
    "minimumPayout": 50,
    "lastPayoutDate": "2024-12-15T10:00:00Z",
    "totalPayouts": 5,
    "totalPayoutAmount": 2500.00
  },
  "payouts": [
    {
      "id": "PO-ABC123DEF4",
      "amount": 500.00,
      "status": "completed",
      "method": "bank_transfer",
      "requestedAt": "2024-12-14T15:00:00Z",
      "processedAt": "2024-12-15T10:00:00Z",
      "transactionId": "TXN-12345"
    }
  ],
  "methods": [
    {
      "id": "bank_transfer",
      "name": "Bank Transfer",
      "processingTime": "2-3 business days",
      "minimumAmount": 50
    },
    {
      "id": "paypal",
      "name": "PayPal",
      "processingTime": "Instant",
      "minimumAmount": 25
    }
  ]
}

POST/api/reseller/payouts

Request a payout

Parameters

amountnumber* - Payout amount

methodstring* - Payout method: bank_transfer, paypal, stripe

accountDetailsobject* - Account details based on payout method

Example Request

{
  "amount": 500.00,
  "method": "bank_transfer",
  "accountDetails": {
    "accountName": "Web Solutions Ltd",
    "accountNumber": "12345678",
    "sortCode": "12-34-56"
  }
}

Example Response

{
  "success": true,
  "payout": {
    "id": "PO-XYZ789ABC1",
    "amount": 500.00,
    "status": "pending",
    "method": "bank_transfer",
    "requestedAt": "2025-01-06T15:00:00Z"
  },
  "message": "Payout request submitted successfully"
}

GET/api/reseller/api-keys

Manage API keys

Parameters

Example Request

GET /api/reseller/api-keys
Authorization: Bearer YOUR_SESSION_TOKEN

Example Response

{
  "apiKeys": [
    {
      "id": "key_ABC123",
      "name": "Production API Key",
      "scopes": ["orders:read", "orders:write", "products:read"],
      "lastUsedAt": "2025-01-06T12:00:00Z",
      "createdAt": "2024-12-01T10:00:00Z"
    }
  ],
  "scopes": [
    {
      "scope": "orders:read",
      "description": "View order details and history"
    },
    {
      "scope": "orders:write",
      "description": "Create and manage orders"
    }
  ],
  "usage": {
    "last30Days": {
      "totalRequests": 1523,
      "successfulRequests": 1520,
      "failedRequests": 3,
      "averageResponseTime": 125
    }
  }
}

POST/api/reseller/api-keys

Create new API key

Parameters

namestring* - API key name

scopesarray* - Array of permission scopes

expiresInnumber - Expiration in days (default: 30)

Example Request

{
  "name": "Production API Key",
  "scopes": ["orders:read", "orders:write", "products:read", "transactions:read"],
  "expiresIn": 365
}

Example Response

{
  "success": true,
  "apiKey": {
    "id": "key_XYZ789",
    "name": "Production API Key",
    "token": "rk_live_1234567890abcdefghijklmnopqrstuvwxyz",
    "scopes": ["orders:read", "orders:write", "products:read", "transactions:read"],
    "expiresAt": "2026-01-06T15:00:00Z"
  },
  "message": "API key created successfully. Please save the token securely as it will not be shown again."
}

GET/api/reseller/webhook

Get webhook configuration

Parameters

Example Request

GET /api/reseller/webhook
Authorization: Bearer YOUR_SESSION_TOKEN

Example Response

{
  "webhook": {
    "url": "https://api.example.com/webhooks/namepick",
    "secret": "••••••••abc123",
    "configured": true
  },
  "history": [
    {
      "id": "evt_ABC123",
      "event": {
        "type": "order.completed",
        "timestamp": "2025-01-06T14:35:00Z"
      },
      "status": 200,
      "responseTime": 125,
      "createdAt": "2025-01-06T14:35:00Z"
    }
  ],
  "stats": {
    "totalEvents": 150,
    "successfulDeliveries": 148,
    "failedDeliveries": 2,
    "averageResponseTime": 135
  }
}

PUT/api/reseller/webhook

Update webhook configuration

Parameters

webhookUrlstring* - Webhook endpoint URL

generateNewSecretboolean - Generate new webhook secret (default: false)

Example Request

{
  "webhookUrl": "https://api.example.com/webhooks/namepick",
  "generateNewSecret": true
}

Example Response

{
  "success": true,
  "webhook": {
    "url": "https://api.example.com/webhooks/namepick",
    "secret": "••••••••xyz789",
    "configured": true
  },
  "message": "Webhook configuration updated successfully"
}

Authentication

POST/api/auth/signin

Parameters

emailstring* - User email address

passwordstring* - User password

Example Request

{
  "email": "user@example.com",
  "password": "your-password"
}

Example Response

{
  "user": {
    "id": "123",
    "email": "user@example.com",
    "name": "John Doe",
    "role": "member"
  },
  "url": "https://namepick.co/dashboard"
}

SDKs & Libraries

Official SDKs for popular programming languages

JavaScript/Node.js

npm install @namepick.co/sdk

Python

pip install namepick.co

PHP

composer require namepick.co/sdk

Ruby

gem install namepick.co

Go

go get github.com/namepick.co/go-sdk

Java

Maven: com.namepick.co:sdk

Webhook Events

Available webhook events for reseller integration

Event Types

order.createdNew order created

order.completedOrder successfully completed

order.failedOrder processing failed

order.cancelledOrder cancelled

commission.earnedCommission earned on order

commission.paidCommission added to balance

payout.requestedPayout request created

payout.completedPayout successfully processed

domain.registeredDomain registration completed

domain.renewedDomain renewal completed

balance.lowAccount balance below threshold

account.activatedReseller account activated

Webhook Payload Structure

{
  "id": "evt_1234567890",
  "type": "order.completed",
  "timestamp": "2025-01-06T14:35:00Z",
  "data": {
    // Event-specific data
  }
}

Signature Verification

Verify webhook authenticity using HMAC-SHA256 signature:

// Node.js example
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hash = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(hash)
  );
}

Reseller API Authentication

Using API keys for programmatic access

API Key Format

Reseller API keys follow the format:

rk_live_[random_string]

Using API Keys

Include your API key in the Authorization header:

curl -X GET https://namepick.co/api/reseller/orders \
  -H "Authorization: Bearer rk_live_1234567890abcdef" \
  -H "Content-Type: application/json"

API Key Scopes

orders:readView order details and history

orders:writeCreate and manage orders

products:readView product catalog and pricing

transactions:readView transaction history

webhooks:manageConfigure webhook endpoints

account:readView account information

reports:readGenerate and download reports

Need Help?

Our developer support team is here to help you integrate our API

api@namepick.co|Contact Support