Domains API
The domain product type sells domain registrations and transfers through registrars. These calls manage a domain order’s nameservers, contacts, lock, privacy and transfer code, the TLDs you sell with their prices, the registrars and their price lists, and the domain search of the store. See Set up domain sales and Manage a registered domain for the user guides.
Admin calls need Module access on the Servicedomain card of the staff group’s Permissions tab, plus each call’s own permission below (Super Administrators have all). See Authentication.
Admin calls
Section titled “Admin calls”update
Section titled “update”POST /api/admin/servicedomain/update
Changes a domain’s stored details without sending anything to the registrar: use it to correct the record after a change made at the registrar.
Permission: Manage domains (servicedomain.manage_domains)
| Parameter | Type | Description |
|---|---|---|
order_id |
integer, required | The domain order’s id. |
ns1 |
string | Nameserver 1. Each field you leave out keeps its value; the same for ns2, ns3 and ns4. |
ns2 |
string | Nameserver 2. |
ns3 |
string | Nameserver 3. |
ns4 |
string | Nameserver 4. |
period |
integer | Registration period in years. |
privacy |
boolean | Whether privacy protection is on. |
locked |
boolean | Whether the transfer lock is on. |
transfer_code |
string | The stored transfer (EPP) code. |
domain_fields |
object | The answers to the TLD’s extra registrar questions, for an order still to register or transfer: they are checked and saved in the order before a retry. |
Returns: true.
Errors:
- Order ID is missing (code 9999)
- Order not found (code 9999)
- Domain order is not activated (code 9999) when the order has no domain service yet.
update_nameservers
Section titled “update_nameservers”POST /api/admin/servicedomain/update_nameservers
Sends new nameservers to the registrar and saves them on the domain.
Permission: Manage domains (servicedomain.manage_domains)
| Parameter | Type | Description |
|---|---|---|
order_id |
integer, required | The domain order’s id. |
ns1 |
string, required | Nameserver 1. |
ns2 |
string, required | Nameserver 2. |
ns3 |
string | Nameserver 3; left out it is cleared. |
ns4 |
string | Nameserver 4; left out it is cleared. |
Returns: true.
Errors:
- Order ID is missing (code 9999)
- Order not found (code 9999)
- Domain order is not activated (code 9999)
- Nameserver 1 is required (code 9999)
- Nameserver 2 is required (code 9999)
- The registrar’s own error when it refuses the change.
With the Email registrar nothing goes to a registrar: the change is added to the domain’s support ticket for staff, and the domain keeps its old values until staff mark the requests done (admin/requests_done). With support tickets off, the call fails with “Please contact us to make this change to …”. The same applies to contacts, lock, privacy and the transfer code.
Example
Request parameters:
{ "order_id": 21, "ns1": "ns1.example.com", "ns2": "ns2.example.com"}result:
trueupdate_contacts
Section titled “update_contacts”POST /api/admin/servicedomain/update_contacts
Sends new registrant (WHOIS) contact details to the registrar and saves them on the domain.
Permission: Manage domains (servicedomain.manage_domains)
| Parameter | Type | Description |
|---|---|---|
order_id |
integer, required | The domain order’s id. |
contact |
object, required | The contact: first_name, last_name, email, address1, city, state, postcode, country (two-letter code), phone_cc (country calling code) and phone are required; company and address2 are optional. |
Returns: true.
Errors:
- Order ID is missing (code 9999)
- Order not found (code 9999)
- Domain order is not activated (code 9999)
- Required field contact is missing (code 9999)
- Required field first_name is missing (code 9999), and the same for each required contact field.
- The registrar’s own error when it refuses the change.
With the Email registrar the change waits in the domain’s support ticket, as for nameservers.
enable_privacy_protection
Section titled “enable_privacy_protection”POST /api/admin/servicedomain/enable_privacy_protection
Turns on WHOIS privacy protection at the registrar.
Permission: Manage domains (servicedomain.manage_domains)
| Parameter | Type | Description |
|---|---|---|
order_id |
integer, required | The domain order’s id. |
Returns: true.
Errors:
- Order ID is missing (code 9999)
- Order not found (code 9999)
- Domain order is not activated (code 9999)
- The registrar’s own error when it refuses.
disable_privacy_protection
Section titled “disable_privacy_protection”POST /api/admin/servicedomain/disable_privacy_protection
Turns off WHOIS privacy protection at the registrar.
Permission: Manage domains (servicedomain.manage_domains)
| Parameter | Type | Description |
|---|---|---|
order_id |
integer, required | The domain order’s id. |
Returns: true.
Errors:
- Order ID is missing (code 9999)
- Order not found (code 9999)
- Domain order is not activated (code 9999)
- The registrar’s own error when it refuses.
POST /api/admin/servicedomain/sync
Reads the domain from the registrar and saves what it reports: lock, privacy, nameservers, contacts and dates. For a transfer still in progress it asks the registrar how the transfer stands instead.
Permission: Manage domains (servicedomain.manage_domains)
| Parameter | Type | Description |
|---|---|---|
order_id |
integer, required | The domain order’s id. |
Returns: true.
Errors:
- Order ID is missing (code 9999)
- Order not found (code 9999)
- Domain order is not activated (code 9999)
- The registrar’s own error when it cannot answer.
get_transfer_code
Section titled “get_transfer_code”POST /api/admin/servicedomain/get_transfer_code
Gets the domain’s transfer (EPP) code from the registrar.
Permission: Manage domains (servicedomain.manage_domains)
| Parameter | Type | Description |
|---|---|---|
order_id |
integer, required | The domain order’s id. |
Returns: The transfer code, as the registrar returns it. An empty string with the Email registrar, which asks staff in the domain’s ticket instead.
Errors:
- Order ID is missing (code 9999)
- Order not found (code 9999)
- Domain order is not activated (code 9999)
- The registrar’s own error when it refuses.
POST /api/admin/servicedomain/lock
Turns on the domain’s transfer lock at the registrar.
Permission: Manage domains (servicedomain.manage_domains)
| Parameter | Type | Description |
|---|---|---|
order_id |
integer, required | The domain order’s id. |
Returns: true.
Errors:
- Order ID is missing (code 9999)
- Order not found (code 9999)
- Domain order is not activated (code 9999)
- The registrar’s own error when it refuses.
unlock
Section titled “unlock”POST /api/admin/servicedomain/unlock
Turns off the domain’s transfer lock at the registrar.
Permission: Manage domains (servicedomain.manage_domains)
| Parameter | Type | Description |
|---|---|---|
order_id |
integer, required | The domain order’s id. |
Returns: true.
Errors:
- Order ID is missing (code 9999)
- Order not found (code 9999)
- Domain order is not activated (code 9999)
- The registrar’s own error when it refuses.
requests_done
Section titled “requests_done”POST /api/admin/servicedomain/requests_done
For a domain on the Email registrar: marks the requests waiting in its support ticket as done, saves their values on the domain and replies to the client on the ticket (Mark Done on the domain page).
Permission: Manage domains (servicedomain.manage_domains)
| Parameter | Type | Description |
|---|---|---|
order_id |
integer, required | The domain order’s id. |
transfer_code |
string | The transfer code you got from the registrar: saved and sent to the client in the reply. |
expires_at |
string | The expiry date the registrar reports, to save on the domain. |
Returns: true.
Errors:
- Order ID is missing (code 9999)
- Order not found (code 9999)
- Domain order is not activated (code 9999)
- This domain has no requests waiting. (code 9999)
- Check the expiry date. (code 9999)
The client gets a ticket reply that lists the requests done. The ticket’s task is marked complete.
tld_get_list
Section titled “tld_get_list”POST /api/admin/servicedomain/tld_get_list
Lists the TLDs (domain extensions) you sell, by id.
Permission: Manage TLDs (servicedomain.manage_tlds)
| Parameter | Type | Description |
|---|---|---|
hide_inactive |
boolean | true lists only active TLDs. |
allow_register |
boolean | When given (any value), lists only TLDs open to registration. |
allow_transfer |
boolean | When given (any value), lists only TLDs open to transfers. |
search |
string | Text to find in the TLD, such as com. |
page |
integer | Page number, from 1. Default 1. |
per_page |
integer | Rows per page, 1 to 500. Default 100. |
Returns: A paged list. Each row has the fields of admin/tld_get.
Example
Request parameters:
{ "search": "com"}result:
{ "pages": 1, "page": 1, "per_page": 100, "total": 1, "list": [ { "id": 1, "tld": ".com", "price_registration": "12.00", "price_renew": "14.00", "price_transfer": "12.00", "active": 1, "allow_register": 1, "allow_transfer": 1, "require_transfer_code": true, "min_years": 1, "periods": null, "domain_fields": [], "transfer_fields": [], "registrar": { "id": 2, "title": "Example Registrar" }, "price_locked": false } ]}tld_get
Section titled “tld_get”POST /api/admin/servicedomain/tld_get
Returns one TLD by name.
Permission: Manage TLDs (servicedomain.manage_tlds)
| Parameter | Type | Description |
|---|---|---|
tld |
string, required | The TLD, such as .com (the dot is optional). |
Returns: The TLD: id, tld, price_registration, price_renew, price_transfer (per year, default currency), active, allow_register, allow_transfer, require_transfer_code, min_years, periods (the allowed years, or null for any from min_years), domain_fields and transfer_fields (extra questions the registrar asks at registration and transfer), registrar (id, title) and price_locked (Keep my price).
Errors:
- TLD is missing (code 9999)
- TLD not found (code 9999)
- TLD is invalid. (code 9999)
tld_get_id
Section titled “tld_get_id”POST /api/admin/servicedomain/tld_get_id
Returns one TLD by id.
Permission: Manage TLDs (servicedomain.manage_tlds)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The TLD’s id. |
Returns: The TLD, with the fields of admin/tld_get.
Errors:
- ID is missing (code 9999)
- TLD not found (code 9999)
tld_delete
Section titled “tld_delete”POST /api/admin/servicedomain/tld_delete
Deletes a TLD that no domain uses, with its fixed currency prices.
Permission: Manage TLDs (servicedomain.manage_tlds)
| Parameter | Type | Description |
|---|---|---|
tld |
string, required | The TLD, such as .com. |
Returns: true.
Errors:
- TLD is missing (code 9999)
- TLD not found (code 9999)
- TLD is used by N domains (code 707)
To stop selling a TLD that has domains, set it inactive with admin/tld_update.
tld_create
Section titled “tld_create”POST /api/admin/servicedomain/tld_create
Adds a TLD to sell.
Permission: Manage TLDs (servicedomain.manage_tlds)
| Parameter | Type | Description |
|---|---|---|
tld |
string, required | The TLD, such as .com. It is saved in lowercase with a leading dot; international names are saved in their ASCII form. |
tld_registrar_id |
integer, required | The registrar that sells it. It must be fully configured. |
price_registration |
number, required | Registration price per year, 0 or more, in the default currency. |
price_renew |
number, required | Renewal price per year. |
price_transfer |
number, required | Transfer price. |
min_years |
integer | Shortest registration, in years. Default 1. |
periods |
string | The allowed years, comma-separated, such as 1,2,5. Empty: any period from min_years. |
allow_register |
boolean | Open to registration. Default true. |
allow_transfer |
boolean | Open to transfers. Default true. |
require_transfer_code |
boolean | Clients must give the transfer code when ordering a transfer. Default false. |
active |
boolean | On sale. Default true. |
price_locked |
boolean | Keep my price: the registrar price list import and sync leave its prices alone. Default false. |
Returns: The new TLD’s id.
Errors:
- TLD is missing (code 9999), and the same for each required field.
- TLD already registered (code 9999)
- TLD is invalid. (code 9999)
- Domain price must be a non-negative number (code 9999)
- Minimum registration period must be a positive integer (code 9999)
- Registration periods must be a comma-separated list of positive integers (code 9999)
- Registrar not found (code 9999)
- Registrar … is missing required configuration: … (code 9999)
Example
Request parameters:
{ "tld": ".com", "tld_registrar_id": 2, "price_registration": 12, "price_renew": 14, "price_transfer": 12}result:
1tld_update
Section titled “tld_update”POST /api/admin/servicedomain/tld_update
Changes a TLD’s registrar, prices and settings. A field you leave out keeps its value.
Permission: Manage TLDs (servicedomain.manage_tlds)
| Parameter | Type | Description |
|---|---|---|
tld |
string, required | The TLD to change, such as .com. The name itself cannot change. |
tld_registrar_id |
integer | The registrar; it must be fully configured. |
price_registration |
number | Registration price per year. |
price_renew |
number | Renewal price per year. Existing domains pay the new price at their next renewal. |
price_transfer |
number | Transfer price. |
min_years |
integer | Shortest registration, in years. |
periods |
string | The allowed years, comma-separated; empty for any. |
allow_register |
boolean | Open to registration. |
allow_transfer |
boolean | Open to transfers. |
require_transfer_code |
boolean | Clients must give the transfer code. |
active |
boolean | On sale. |
price_locked |
boolean | Keep my price. |
currency_prices |
object | Fixed prices in other currencies: an object of currency code to { "register": {"price"}, "renew": {"price"}, "transfer": {"price"} }. Saved first, so a wrong price changes nothing. See product/admin/currency_prices_save. |
Returns: true.
Errors:
- TLD is missing (code 9999)
- TLD not found (code 9999)
- Domain price must be a non-negative number (code 9999)
- Registrar not found (code 9999)
- Fixed prices can only be set for a currency other than the default one. (code 9999)
tld_pinned_update
Section titled “tld_pinned_update”POST /api/admin/servicedomain/tld_pinned_update
Sets the TLDs pinned at the top of the domain search (up to 8), in the order given.
Permission: Manage TLDs (servicedomain.manage_tlds)
| Parameter | Type | Description |
|---|---|---|
tlds |
array | The TLDs, such as [".com", ".net"], or one string with names separated by spaces or commas. Each must be active and open to registration. Empty or left out: none pinned. |
Returns: true.
Errors:
- TLD not found (code 9999)
- Domain cannot be registered (code 9999) for a TLD not on sale.
- Pin up to 8 TLDs. (code 9999)
registrar_get_list
Section titled “registrar_get_list”POST /api/admin/servicedomain/registrar_get_list
Lists the installed registrars, by name, with their settings.
Permission: Manage registrars (servicedomain.manage_registrars)
No parameters.
Returns: A paged list whose list holds every registrar (it is not paged). Each row has the fields of admin/registrar_get.
registrar_get_pairs
Section titled “registrar_get_pairs”POST /api/admin/servicedomain/registrar_get_pairs
Returns the installed registrars as id and name pairs, newest first.
Permission: Manage registrars (servicedomain.manage_registrars)
No parameters.
Returns: An object of registrar id to name.
registrar_get_available
Section titled “registrar_get_available”POST /api/admin/servicedomain/registrar_get_available
Lists the registrar adapters you can install: the built-in ones and those of active modules.
Permission: Manage registrars (servicedomain.manage_registrars)
No parameters.
Returns: A list of adapter codes, such as ["Email", "Resellerclub"]. Adapters already installed are left out.
registrar_install
Section titled “registrar_install”POST /api/admin/servicedomain/registrar_install
Installs a registrar adapter, unconfigured and in live mode. Configure it with admin/registrar_update.
Permission: Manage registrars (servicedomain.manage_registrars)
| Parameter | Type | Description |
|---|---|---|
code |
string, required | An adapter code from admin/registrar_get_available. |
Returns: true.
Errors:
- Registrar code is missing (code 9999)
- Registrar is not available for installation. (code 9999)
registrar_delete
Section titled “registrar_delete”POST /api/admin/servicedomain/registrar_delete
Deletes a registrar that no domain or TLD uses, with its saved price list.
Permission: Manage registrars (servicedomain.manage_registrars)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The registrar’s id. |
Returns: true.
Errors:
- Registrar ID is missing (code 9999)
- Registrar not found (code 9999)
- Registrar is used by N domains (code 707)
- Registrar is used by N TLDs (code 707)
registrar_copy
Section titled “registrar_copy”POST /api/admin/servicedomain/registrar_copy
Adds a second registrar on the same adapter, named “
Permission: Manage registrars (servicedomain.manage_registrars)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The registrar to copy. |
Returns: The new registrar’s id.
Errors:
- Registrar ID is missing (code 9999)
- Registrar not found (code 9999)
registrar_get
Section titled “registrar_get”POST /api/admin/servicedomain/registrar_get
Returns one registrar with its settings form. Secret settings are never returned.
Permission: Manage registrars (servicedomain.manage_registrars)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The registrar’s id. |
Returns: id, title (its name), label (the adapter’s description), config (the saved settings; each secret one is null, with <name>_set saying whether it has a value), secret_fields (their names), form (the adapter’s settings fields) and test_mode.
Errors:
- Registrar ID is missing (code 9999)
- Registrar not found (code 9999)
Example
Request parameters:
{ "id": 2}result:
{ "id": 2, "title": "Example Registrar", "label": "Manages domains with the registrar's API", "config": { "user_id": "12345", "api_key": null, "api_key_set": true }, "secret_fields": [ "api_key" ], "form": { "user_id": [ "text", { "label": "Reseller ID", "required": true } ], "api_key": [ "password", { "label": "API key", "required": true } ] }, "test_mode": 0}batch_sync_expiration_dates
Section titled “batch_sync_expiration_dates”POST /api/admin/servicedomain/batch_sync_expiration_dates
Updates the expiry dates of the domains from their registrars. With the daily domain sync on, it runs one batch of it; otherwise it checks every domain, at most once in 30 days.
Permission: Manage domains (servicedomain.manage_domains)
No parameters.
Returns: true; false when the last full run was less than 30 days ago.
A domain the registrar cannot answer for is logged and skipped. This can take long with many domains.
registrar_update
Section titled “registrar_update”POST /api/admin/servicedomain/registrar_update
Renames a registrar, sets test mode and saves its settings.
Permission: Manage registrars (servicedomain.manage_registrars)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The registrar’s id. |
title |
string | Its name. |
test_mode |
integer | 1 to use the registrar’s test system, 0 for live. |
config |
object | Settings to change, by field name from form; the others keep their values. A secret setting sent empty keeps its saved value. |
Returns: true.
Errors:
- Registrar ID is missing (code 9999)
- Registrar not found (code 9999)
- Registrar … is missing required configuration: … (code 9999)
Changing a secret setting is logged, without its value.
price_sync_get
Section titled “price_sync_get”POST /api/admin/servicedomain/price_sync_get
Returns a registrar’s price list settings (TLDs and prices): whether it offers a price list, the markup, rounding and sync mode.
Permission: Manage TLDs (servicedomain.manage_tlds)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The registrar’s id. |
Returns: id, name, supported (the registrar offers a price list), settings (as admin/price_sync_update returns), fetched_at (when its price list was last fetched, or null) and currency (the default currency code).
Errors:
- Registrar ID is missing (code 9999)
- Registrar not found (code 9999)
price_sync_update
Section titled “price_sync_update”POST /api/admin/servicedomain/price_sync_update
Saves how a registrar’s costs become your TLD prices, and whether a daily sync runs.
Permission: Manage TLDs (servicedomain.manage_tlds)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The registrar’s id. |
mode |
string | The daily sync: off (default), notify (email staff about cost changes) or apply (update prices; a change above 50% still waits for staff). |
markup |
object | Per action (register, renew, transfer): { "type": "percent" or "fixed", "value": number }, up to 2 decimals (at most 1000 percent or 100000). Default 0 percent. |
rounding |
string | The ending prices are rounded up to: `` (none, default), .00, .50, .95 or .99. |
Returns: The saved settings: mode, markup (per action type and value) and rounding.
Errors:
- Registrar ID is missing (code 9999)
- Registrar not found (code 9999)
- Unknown sync mode or rounding. (code 9999)
- Enter each markup as a number from 0 with up to 2 decimals (at most …). (code 9999)
Example
Request parameters:
{ "id": 2, "mode": "notify", "markup": { "register": { "type": "percent", "value": 20 }, "renew": { "type": "percent", "value": 20 }, "transfer": { "type": "fixed", "value": 2 } }, "rounding": ".99"}result:
{ "mode": "notify", "markup": { "register": { "type": "percent", "value": 20 }, "renew": { "type": "percent", "value": 20 }, "transfer": { "type": "fixed", "value": 2 } }, "rounding": ".99"}price_sync_fetch
Section titled “price_sync_fetch”POST /api/admin/servicedomain/price_sync_fetch
Gets the registrar’s price list, for up to about 15 seconds per call: call it again until done is true. A list younger than a day is reused.
Permission: Manage TLDs (servicedomain.manage_tlds)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The registrar’s id. |
refresh |
boolean | true fetches a new list even when the saved one is younger than a day. |
Returns: done (the whole list is in), priced (TLDs priced so far), remaining (TLDs still to price) and fetched_at (when the last complete list finished, or null).
Errors:
- Registrar ID is missing (code 9999)
- Registrar not found (code 9999)
- Not supported by this registrar. (code 9999)
- The registrar returned no prices. Nothing was changed; try again later. (code 9999)
- The registrar charges in …, which is not one of your currencies. Add … under Currencies first: its rate converts the costs. (code 9999)
price_sync_preview
Section titled “price_sync_preview”POST /api/admin/servicedomain/price_sync_preview
Compares the last complete price list with your TLD prices: for each TLD the registrar prices, its cost, current price and the new price your settings give.
Permission: Manage TLDs (servicedomain.manage_tlds)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The registrar’s id. |
Returns: rows, counts (rows per status), currency (the registrar’s), rate, fetched_at and fingerprint (pass it to admin/price_sync_apply). Each row has tld, tld_id (null for a TLD you do not sell), status (change, same, new, locked (Keep my price), other (sold through another registrar) or no_price), cost, current and new (each per action register, renew, transfer), registrar (the other registrar’s name, for other), rate_only (only the exchange rate moved), fixed_currencies (currencies with fixed prices for it, which are never changed) and offers_transfer.
Errors:
- Registrar ID is missing (code 9999)
- Registrar not found (code 9999)
- Get the price list first. (code 9999)
price_sync_apply
Section titled “price_sync_apply”POST /api/admin/servicedomain/price_sync_apply
Applies the new prices of the TLDs you tick in the preview: creates new TLDs (inactive), updates changed ones and moves ticked TLDs of other registrars to this one. Nothing is applied when anything fails.
Permission: Manage TLDs (servicedomain.manage_tlds)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The registrar’s id. |
fingerprint |
string, required | The fingerprint of the preview you checked. |
tlds |
array, required | The TLDs to apply, as a list or a comma-separated string. Each must have status change or new, or other and be in move. |
move |
array | TLDs of other registrars (status other) to move to this registrar with the new prices. |
Returns: created, updated and moved: how many TLDs each.
Errors:
- Registrar ID is missing (code 9999)
- Check the preview first (code 9999) when
fingerprintis missing. - Tick at least one TLD. (code 9999)
- Prices changed since the preview. Check the preview again before applying. (code 9999)
- … cannot be applied. Nothing was changed. (code 9999)
New renewal prices apply to existing domains at their next renewal; unpaid invoices keep their amount. Fixed prices in other currencies are not changed.
Example
Request parameters:
{ "id": 2, "fingerprint": "9f2c…", "tlds": [ ".com", ".net" ]}result:
{ "created": 0, "updated": 2, "moved": 0}Client calls
Section titled “Client calls”update_nameservers (client)
Section titled “update_nameservers (client)”POST /api/client/servicedomain/update_nameservers
Changes the nameservers of one of the client’s active domains at the registrar.
| Parameter | Type | Description |
|---|---|---|
order_id |
integer, required | The domain order’s id. |
ns1 |
string, required | Nameserver 1. |
ns2 |
string, required | Nameserver 2. |
ns3 |
string | Nameserver 3; left out it is cleared. |
ns4 |
string | Nameserver 4; left out it is cleared. |
Returns: true.
Errors:
- Order ID is required (code 9999)
- Order not found (code 9999)
- Subscription expired (code 9999)
- Order is not activated (code 9999) when the order is not active.
- Nameserver 1 is required (code 9999)
- Nameserver 2 is required (code 9999)
Fires onBeforeClientChangeNameservers and onAfterClientChangeNameservers. With the Email registrar the change waits in the domain’s support ticket for staff. An authorized user needs the Manage domain settings permission (managedomains).
Example
Request parameters:
{ "order_id": 21, "ns1": "ns1.example.com", "ns2": "ns2.example.com"}result:
trueupdate_contacts (client)
Section titled “update_contacts (client)”POST /api/client/servicedomain/update_contacts
Changes the registrant (WHOIS) contact of one of the client’s active domains at the registrar.
| Parameter | Type | Description |
|---|---|---|
order_id |
integer, required | The domain order’s id. |
contact |
object, required | The contact, with the fields of admin/update_contacts. |
Returns: true.
Errors:
- Order ID is required (code 9999)
- Order not found (code 9999)
- Subscription expired (code 9999)
- Order is not activated (code 9999)
- Required field first_name is missing (code 9999), and the same for each required contact field.
An authorized user needs Manage domain settings (managedomains).
enable_privacy_protection (client)
Section titled “enable_privacy_protection (client)”POST /api/client/servicedomain/enable_privacy_protection
Turns on WHOIS privacy for one of the client’s active domains.
| Parameter | Type | Description |
|---|---|---|
order_id |
integer, required | The domain order’s id. |
Returns: true.
Errors:
- Order ID is required (code 9999)
- Order not found (code 9999)
- Subscription expired (code 9999)
- Order is not activated (code 9999)
An authorized user needs Manage domain settings (managedomains).
disable_privacy_protection (client)
Section titled “disable_privacy_protection (client)”POST /api/client/servicedomain/disable_privacy_protection
Turns off WHOIS privacy for one of the client’s active domains.
| Parameter | Type | Description |
|---|---|---|
order_id |
integer, required | The domain order’s id. |
Returns: true.
Errors:
- Order ID is required (code 9999)
- Order not found (code 9999)
- Subscription expired (code 9999)
- Order is not activated (code 9999)
An authorized user needs Manage domain settings (managedomains).
sync (client)
Section titled “sync (client)”POST /api/client/servicedomain/sync
Reads one of the client’s active domains from the registrar and saves what it reports (lock, privacy, nameservers, contacts, dates).
| Parameter | Type | Description |
|---|---|---|
order_id |
integer, required | The domain order’s id. |
Returns: true.
Errors:
- Order ID is required (code 9999)
- Order not found (code 9999)
- Subscription expired (code 9999)
- Order is not activated (code 9999)
An authorized user needs View domains (domains).
get_transfer_code (client)
Section titled “get_transfer_code (client)”POST /api/client/servicedomain/get_transfer_code
Gets the transfer (EPP) code of one of the client’s active domains from the registrar.
| Parameter | Type | Description |
|---|---|---|
order_id |
integer, required | The domain order’s id. |
Returns: The transfer code; an empty string with the Email registrar, where staff send it in the domain’s ticket.
Errors:
- Order ID is required (code 9999)
- Order not found (code 9999)
- Subscription expired (code 9999)
- Order is not activated (code 9999)
An authorized user needs Manage domain settings (managedomains).
lock (client)
Section titled “lock (client)”POST /api/client/servicedomain/lock
Turns on the transfer lock of one of the client’s active domains.
| Parameter | Type | Description |
|---|---|---|
order_id |
integer, required | The domain order’s id. |
Returns: true.
Errors:
- Order ID is required (code 9999)
- Order not found (code 9999)
- Subscription expired (code 9999)
- Order is not activated (code 9999)
An authorized user needs Manage domain settings (managedomains).
unlock (client)
Section titled “unlock (client)”POST /api/client/servicedomain/unlock
Turns off the transfer lock of one of the client’s active domains, so it can be transferred away.
| Parameter | Type | Description |
|---|---|---|
order_id |
integer, required | The domain order’s id. |
Returns: true.
Errors:
- Order ID is required (code 9999)
- Order not found (code 9999)
- Subscription expired (code 9999)
- Order is not activated (code 9999)
An authorized user needs Manage domain settings (managedomains).
Guest calls
Section titled “Guest calls”tlds (guest)
Section titled “tlds (guest)”POST /api/guest/servicedomain/tlds
Lists the active TLDs with their prices.
| Parameter | Type | Description |
|---|---|---|
allow_register |
boolean | When given (any value), lists only TLDs open to registration. |
allow_transfer |
boolean | When given (any value), lists only TLDs open to transfers. |
Returns: A list of TLDs with id, tld, price_registration, price_renew, price_transfer, active, allow_register, allow_transfer, require_transfer_code, min_years, periods, domain_fields and transfer_fields. Prices are in the default currency; when the visitor chose a currency with fixed prices, those prices are given as their default-currency amount.
A store call: when the store is closed to the caller it returns an empty list.
Example
Request parameters:
{ "allow_register": true}result:
[ { "id": 1, "tld": ".com", "price_registration": "12.00", "price_renew": "14.00", "price_transfer": "12.00", "active": 1, "allow_register": 1, "allow_transfer": 1, "require_transfer_code": true, "min_years": 1, "periods": null, "domain_fields": [], "transfer_fields": [] }]pricing (guest)
Section titled “pricing (guest)”POST /api/guest/servicedomain/pricing
Returns one TLD with its prices.
| Parameter | Type | Description |
|---|---|---|
tld |
string, required | The TLD, such as .com. |
Returns: The TLD, with the fields of guest/tlds. It is returned also when the TLD is inactive.
Errors:
- TLD is missing (code 9999)
- TLD not found (code 9999)
- The store is not available. (code 9999) when the store is closed to the caller.
check (guest)
Section titled “check (guest)”POST /api/guest/servicedomain/check
Asks the registrar whether a domain is free to register.
| Parameter | Type | Description |
|---|---|---|
sld |
string, required | The name without the TLD, such as example. |
tld |
string, required | The TLD, such as .com. |
g-recaptcha-response |
string | The CAPTCHA answer, when one is asked (see guest/lookup_captcha); cf-turnstile-response or h-captcha-response for those CAPTCHAs. |
Returns: true when the domain is available.
Errors:
- SLD is missing (code 9999)
- TLD is missing (code 9999)
- Domain … is invalid (code 9999)
- Domain availability could not be determined. TLD is not configured. (code 9999)
- Domain availability could not be determined. TLD is not active. (code 9999)
- Domain cannot be registered (code 403)
- Domain is not available. (code 9999)
- The store is not available. (code 9999)
- The CAPTCHA errors, such as “You have to complete the CAPTCHA to continue”.
Domain searches have their own rate limit per IP address, and a visitor who is not signed in answers the CAPTCHA once an hour when the CAPTCHA is on.
Example
Request parameters:
{ "sld": "example", "tld": ".com"}result:
truecheck_bulk (guest)
Section titled “check_bulk (guest)”POST /api/guest/servicedomain/check_bulk
Checks one name in several TLDs, 5 TLDs per call. The first call starts the search; then call again with the returned search until it is null.
| Parameter | Type | Description |
|---|---|---|
sld |
string | First call: the name without the TLD. |
tlds |
array | First call: up to 20 TLDs, each active and open to registration. |
search |
string | Later calls: the search id the previous call returned. It expires after 5 minutes. |
g-recaptcha-response |
string | First call: the CAPTCHA answer, when one is asked. |
Returns: search (the id for the next call, or null when all TLDs are checked) and results: for each TLD of this batch, domain, available (true, false, or null when the registrar could not answer) and the TLD’s fields of guest/tlds.
Errors:
- TLD is missing (code 9999)
- Choose up to 20 extensions. (code 9999)
- Domain … is invalid (code 9999)
- Domain availability could not be determined. TLD is not active. (code 9999)
- This search has expired. Search again. (code 9999)
- The store is not available. (code 9999)
The first call counts against the domain search rate limit (and may ask for the CAPTCHA); the later calls have their own limit.
Example
Request parameters:
{ "sld": "example", "tlds": [ ".com", ".net" ]}result:
{ "search": null, "results": [ { "domain": "example.com", "available": false, "id": 1, "tld": ".com", "price_registration": "12.00", "price_renew": "14.00", "price_transfer": "12.00", "active": 1, "allow_register": 1, "allow_transfer": 1, "require_transfer_code": true, "min_years": 1, "periods": null, "domain_fields": [], "transfer_fields": [] } ]}pinned_tlds (guest)
Section titled “pinned_tlds (guest)”POST /api/guest/servicedomain/pinned_tlds
Lists the TLDs pinned at the top of the domain search that are still on sale, in their order.
No parameters.
Returns: A list of TLD names, such as [".com", ".net"].
A store call: when the store is closed to the caller it returns an empty list.
can_be_transferred (guest)
Section titled “can_be_transferred (guest)”POST /api/guest/servicedomain/can_be_transferred
Asks the registrar whether a domain can be transferred in.
| Parameter | Type | Description |
|---|---|---|
sld |
string, required | The name without the TLD. |
tld |
string, required | The TLD, such as .com. |
g-recaptcha-response |
string | The CAPTCHA answer, when one is asked. |
Returns: true when it can be transferred.
Errors:
- SLD is missing (code 9999)
- TLD is missing (code 9999)
- TLD is not configured. (code 9999)
- TLD is not active. (code 9999)
- Domain cannot be transferred (code 403) when the TLD is closed to transfers.
- Domain cannot be transferred. (code 9999)
- The store is not available. (code 9999)
Same rate limit and CAPTCHA as guest/check.
lookup_captcha (guest)
Section titled “lookup_captcha (guest)”POST /api/guest/servicedomain/lookup_captcha
Says whether the next domain search must include a CAPTCHA answer.
No parameters.
Returns: true when the caller is not signed in, the Anti-Spam CAPTCHA is on and the caller has not answered it in the last hour; otherwise false.

