ICOREHOST Reseller API Documentation

01

Quick start

Use this order when connecting a customer-facing service.

Get approvalAn active ICOREHOST reseller account is required for API access.
Create a keyOpen Reseller Centre, choose API Keys, and issue a key with only the scopes your integration needs.
Choose an environmentUse the sandbox while building and the live base URL only after your live registration access is approved.
Read before writingLoad the catalogue and check availability before presenting a registration price or submitting an order.

02

Authentication

Send the API key as a bearer token over HTTPS on every request. Keys are shown once when created.

Authorization: Bearer ICRSLR_your_key_here
Accept: application/json

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

03

Catalogue and quotes

Read the supported TLDs and the current reseller quote in the account currency.

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

retail_priceCurrent public catalogue price.

reseller_pricePrice after the reseller account discount.

billing_periodNumber of billing units included in the quote.

billing_unitUsually year for domain registration.

04

Availability checks

Use the check endpoint before offering a domain to a customer. The response includes availability and a quote.

curl -sS -X POST 'https://icorehost.co.ke/api/v1/reseller/domains/check' \
  -H 'Authorization: Bearer ICRSLR_your_key_here' \
  -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.

05

Sandbox testing

Build and test your integration without creating real orders or spending reseller funds.

Safe by design. Sandbox requests validate the same account permissions and domain catalogue, then return simulated results. They do not call Enom or KENIC, create database records, reserve balance, or register a domain.

# Available test domain
curl -sS -X POST 'https://icorehost.co.ke/api/v1/reseller/sandbox/domains/check' \
  -H 'Authorization: Bearer ICRSLR_your_key_here' \
  -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 ICRSLR_your_key_here' \
  -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 ICRSLR_your_key_here' \
  -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.

06

Live registration

Submit a live order only after your account, funding arrangement, registrar path, and integration have been reviewed.

Live registration is restricted until ICOREHOST enables both the live registration setting and the registrar bridge. Until then, this endpoint returns 503 and does not charge the account.

curl -sS -X POST 'https://icorehost.co.ke/api/v1/reseller/domains/register' \
  -H 'Authorization: Bearer ICRSLR_your_key_here' \
  -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. The API uses it to prevent duplicate reservation when the same request is retried.

07

Responses and errors

Successful responses return a data object. List endpoints also return pagination metadata.

200Read or check request completed.

201Sandbox or live registration completed.

202Registrar result needs manual review.

401Missing, invalid, expired, or disabled API key.

403Key is missing the required scope or IP restriction does not match.

409Requested domain is unavailable.

422Request data failed validation.

503API or live registration is disabled.