ICOREHOST Reseller API documentation

1. Activate your accountAn active ICOREHOST reseller account is required for API access; live mode is a separate choice you control.
2. Create a keyOpen Reseller Centre, choose API Keys, and issue a key with only the scopes your integration needs.
3. Choose an environmentUse sandbox while building. When the account is active, select Live API in Reseller Centre → Settings to allow real orders.
4. Read before writingLoad the catalogue and check availability before presenting a registration price or submitting an order.

GET https://icorehost.co.ke/api/v1/reseller/capabilities?domain=available.co.ke

The capability response includes live_mode_selected, live_admin_paused, live_platform_enabled, live_enabled_for_account, and webhook_configured. A live operation is available only when the active reseller has selected live mode, ICOREHOST has the platform service enabled, and no admin pause is in place.

Authorization: Bearer YOUR_RESELLER_API_KEY
Accept: application/json

Keep the key on your server. Do not expose it in browser JavaScript, public repositories, screenshots, or client-side application bundles.

curl -sS 'https://icorehost.co.ke/api/v1/reseller/catalog' \
  -H 'Authorization: Bearer YOUR_RESELLER_API_KEY' \
  -H 'Accept: application/json'

curl -sS -X POST 'https://icorehost.co.ke/api/v1/reseller/domains/check' \
  -H 'Authorization: Bearer YOUR_RESELLER_API_KEY' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data '{"domain":"yourbrand.co.ke"}'

The live check uses the configured ICOREHOST registrar path for the selected TLD. Treat availability as time-sensitive and check again before a live registration.

# Available test domain
curl -sS -X POST 'https://icorehost.co.ke/api/v1/reseller/sandbox/domains/check' \
  -H 'Authorization: Bearer YOUR_RESELLER_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"domain":"available.co.ke"}'

# Unavailable test domain
curl -sS -X POST 'https://icorehost.co.ke/api/v1/reseller/sandbox/domains/check' \
  -H 'Authorization: Bearer YOUR_RESELLER_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"domain":"taken.co.ke"}'

curl -sS -X POST 'https://icorehost.co.ke/api/v1/reseller/sandbox/domains/register' \
  -H 'Authorization: Bearer YOUR_RESELLER_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{
    "domain":"available.co.ke",
    "external_reference":"test-order-001",
    "contact": {
      "first_name":"Test",
      "last_name":"Customer",
      "email":"test@example.com",
      "phone":"+254700000000",
      "address1":"1 Test Street",
      "city":"Nairobi",
      "postal_code":"00100",
      "country":"KE"
    }
  }'

Sandbox registration returns a simulated completed response with a SANDBOX- provider reference. It never creates a live order, domain, invoice, or balance transaction.

curl -sS -X POST 'https://icorehost.co.ke/api/v1/reseller/domains/register' \
  -H 'Authorization: Bearer YOUR_RESELLER_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{
    "domain":"yourbrand.co.ke",
    "external_reference":"your-system-order-123",
    "contact": {
      "first_name":"Jane",
      "last_name":"Doe",
      "email":"jane@example.com",
      "phone":"+254700000000",
      "address1":"10 Example Road",
      "city":"Nairobi",
      "postal_code":"00100",
      "country":"KE"
    },
    "nameservers":["ns1.example.com","ns2.example.com"]
  }'

Use a unique external_reference for each order. Retry an uncertain response with the same reference and identical data. The API returns the existing order without repeating the registrar call.

Live writes require the appropriate API scope and Live API selected in Reseller Centre settings. For transfer-in, the key needs both domains.transfer and domains.write. If a registrar result is uncertain, funds remain held until ICOREHOST support verifies the outcome.

Set an HTTPS callback URL in Reseller Centre → Settings and copy the signing secret when it appears. Send a sandbox test from that page or call POST https://icorehost.co.ke/api/v1/reseller/sandbox/webhooks/test.

X-Icorehost-Event-ID: order.123.completed
X-Icorehost-Event: order.status_changed
X-Icorehost-Timestamp: 1790000000
X-Icorehost-Signature: sha256=<hex digest>

signed_text = timestamp + "." + raw_request_body
expected = HMAC_SHA256(signing_secret, signed_text)

Compare signatures in constant time, reject old timestamps, and deduplicate the event ID. Return a 2xx response quickly. Delivery retries up to five times; polling GET /orders/{id} remains the fallback.

1. Complete sandbox callsTest available, unavailable, pending, completed, failed, and manual-review responses.
2. Confirm domain operationsAgree on .co.ke pricing, registrant contact fields, nameservers, renewal, transfer handling, and the KENIC DNS limitation.
3. Choose status deliveryConfigure a signed callback or poll orders. Keep polling as a fallback.
4. Enable live when readyOnce your reseller account is active and ICOREHOST has enabled the platform service, select Live API in Reseller Centre → Settings. You can switch back to sandbox at any time.