Do you manage lots of domain names? Or do you sell them to your own customers? Then you can order them through the Site.eu API. Your script pays from your wallet, and the order starts right away.
With the API, you can register, transfer, renew and restore domain names. Each call is one order for one domain name. Want to order web hosting? Read how to order plans with the API. New to our API? Then first read how to get started with the API.
What you need
An API key. Make one in your dashboard under Settings, on the API keys tab. Only tick the permissions you need, under API Endpoints:
- domains.order.create: order domain names (register, transfer, renew and restore).
- domains.view: look up the IDs of your domain names, and the price of a premium domain name.
- contacts.required_info: only when you send extra details about the domain holder with an order.
Money in your wallet. Orders through the API are always paid from your online wallet. The balance must cover the whole order, VAT included.
Orders only work with an API key. In your browser, you simply use the shopping cart.
How an order works
You send a POST request to the API. Put your API key in the X-API-Key header, and the details of the order as JSON in the body. For example, to register a domain name:
POST https://backend.site.eu/v2/domain_names/register
X-API-Key: your API key
Content-Type: application/jsonIn the body, you send at least domain_name, for example example.nl. Then this happens:
- Same price. You pay the same as when you order on our website.
- Nothing is charged when something is wrong. You get an error code that says why.
- Test it first. Send dry_run: true. The answer shows the price, the VAT and whether your wallet balance covers it. Nothing is ordered or charged.
- We start the order within about a minute. From then on, it goes like any other order, with the same emails.
- It goes on your monthly invoice, marked "Via API". That also happens when monthly invoicing is off.
The API documentation lists every field and gives examples of each request and answer.
Register or transfer a domain name
POST https://backend.site.eu/v2/domain_names/register
POST https://backend.site.eu/v2/domain_names/transferYou can send these fields:
- domain_name (required): the full domain name, like example.nl.
- auth_key (transfers only): the transfer key from your current provider. Read how to request the transfer key.
- order_period: 1 to 5 terms. The default is 1. A term is the shortest registration period of the extension, usually 1 year.
- contact_id: the contact that becomes the domain holder. Without it, we use your default contact.
- name_servers: a list of 2 to 8 nameservers. Without it, the domain name gets your default nameservers.
- privacy_protection: true hides the domain holder in the WHOIS, where the extension allows it.
- expected_price: the price in cents, without VAT, that you accept. You need it for premium domain names.
- dry_run: true only checks and prices the order.
Not sure if the domain name is still free? Check it first. You don't need an API key for this:
GET https://backend.site.eu/v2/domain_names/check_availability?domain_name=example.nlDoes the answer say premium: true? Then ask for its price with GET /v2/domain_names/premium_quote. Send that price as expected_price with your order.
The transfer itself can take a few days. Did it fail? Then read what to do when your domain transfer failed.
Renew or restore a domain name
POST https://backend.site.eu/v2/domain_names/6731/renew
POST https://backend.site.eu/v2/domain_names/6731/restoreHere, 6731 is the ID of the domain name. You find it with GET /v2/domain_names. In the body, you can send order_period, expected_price and dry_run.
- Renew: for an active domain name. A premium domain name can only be renewed in the last year before it expires.
- Restore: for a domain name that has expired, as long as it's still in its restore period. That period differs per extension.
The answer
Did the order go through? Then you get its order_id, with order_status paid. You also get the prices in cents: amount_excluding_vat_in_cents, vat_amount_in_cents and total_including_vat_in_cents. Under payment, wallet_balance_in_cents shows what's left in your wallet.
Follow the order with its ID:
GET https://backend.site.eu/v2/orders/5925Each line of the order has a status: unprocessed, processing, processed, awaiting_required_info, transfer_failed, failed or cancelled.
Never pay twice
Sometimes the connection drops right after you send an order. Did it go through or not? To be safe, send an Idempotency-Key header with every order. That's a unique code of up to 255 characters, like a UUID.
Send the same order again with the same key? Then you get the first answer back, and you're never charged twice. Use the key for a different order, and you get the error ORDER_005.
Does the domain holder need extra details?
Some extensions, like .es and .it, need extra details about the domain holder. An ID number, for example. Is the contact not ready for the extension yet? Then the order stops with ORDER_003 and the reason contact_required_info. Nothing is charged. The answer lists the fields you still need under required_info.
You can send those details with the order, as required_info. Or you make the contact ready first. Read how to create a contact and make it ready with the API.
Error codes
With every error, nothing is charged. These are the most common ones:
- ORDER_001: your wallet balance is too low. Under top_up, the answer gives the amount to add and a link to top up your wallet.
- ORDER_002: the price is not your expected_price. The answer has the current price.
- ORDER_003: this order isn't possible. The reason field says why.
- ORDER_004: paying from the wallet isn't possible for your account.
- ORDER_005: you already used this Idempotency-Key for a different order.
- DOMAIN_NOT_AVAILABLE: the domain name is taken (registration), isn't registered (transfer) or is already with us.
- REG_001: we couldn't reach the registry. Try again a bit later.
Good to know
- There's no test environment. Every order is real. So test with dry_run first.
- Is a registration waiting for holder details, or did a transfer fail? Then you can cancel that line with PATCH /v2/domain_name_orders/22455/cancel. Here, 22455 is the ID of the line in the order. Your API key needs domains.order.cancel. We put the money back in your wallet.
