In this article, you will learn:
- How WAPI works
- How to activate WAPI in the customer administration panel
- How to set up communication and authentication
- Basic requests
- Return codes
- Basic terms
WEDOS API
The WEDOS API, also called WAPI, is used to manage services directly from your own information system.
To use WAPI, you need an active credit account, from which the system deducts payments for domain registrations, renewals, transfers and other charges.
WAPI currently supports the management of:
Restrictions
To prevent misuse, we apply the following restrictions to WAPI:
- One user account can send a maximum of 1000 requests per hour. This applies to all types of requests. When this limit is reached, WAPI rejects further requests until the timeout expires.
- One user account is allowed to make a maximum of 100 domain availability requests per hour. This applies to the domain-check, domain-create and domain-transfer-check requests.
- Repeated invalid requests (authorization failure, access from an unauthorized IP address, incorrect input, missing or incorrect parameters, unknown commands, commands resulting in any error, or any request beyond other restrictions) will cause the IP address to be blocked for 1 minute for each invalid request in excess of 10. With each additional invalid request, the system increases the blocking time.
Synchronous and Asynchronous Requests
Most of the requests executed via WAPI are synchronous – you send the request and you usually get the result within a few seconds.
Some requests are asynchronous – processing such requests can take a very long time (even hours or days). In such cases, WAPI doesn’t return the final result, but only information about receiving the request. The system then sends you information about the progress and the final result in the form of notifications.
WAPI Activation
Before you start using WAPI, activate it in the customer administration by following these steps:
- Log into the customer administration panel.
- In the navigation bar, select My Account Customer.
- In the left menu, select WAPI Interface.
- Set up allowed IPs, a notification method, a preferred protocol and a password.
- Confirm by clicking the Set button.
You can change all these settings later in the same way. To disable WAPI entirely, delete the contents of the Allowed IPs field.
Communication and Authentication
Communication with the WAPI interface takes place via the HTTPS protocol. Data is passed by the POST method in the request parameter in XML or JSON format. The basic structure of both the request and response is the same for all commands. Data encoding is UTF-8.
The interface URLs are:
- XML:
https://api.wedos.com/wapi/xml
- JSON:
https://api.wedos.com/wapi/json
Request Structure
The request consists of the following data:
- user: Your WEDOS customer account login (email), required.
- auth: Authorization string, required. This is a sha1 hash of a string composed of the username, the sha1 hash of the WAPI password and the current time (00-23). The time zone is Europe/Prague (UTC+1 CET, or UTC+2 CET with DST adjustment). See code below for a specific example.
- command: The actual WAPI request. Required.
- clTRID: Request ID, optional. You can put any string in this element as an identifier that WAPI will return in the response.
- data: The data part of the request. Optional.
- test: Test mode flag, optional. If you include a test element with a value of 1 in the request, WAPI will only check the command, but not make any changes in the system.
Enter the WAPI password when communicating with WAPI. The customer account password does not work.
JSON Request Template
{ "request": { "user": "your@login.tld", "auth": "auth-string", "command": "request-name", "data": { request data } "clTRID": "request-id (optional)", "test": "1 (to only test the request, optional)" } }
XML Request Template
<request> <user>your@login.tld</user> <auth>auth string</auth> <command>request-name</command> <data> ... </data> <clTRID>request id (optional)</clTRID> <test>1 (if you only want to test the request, optional)</test> </request>
PHP Template (JSON)
The following sample script requires the curl extension to run.
<?php date_default_timezone_set('Europe/Prague'); $login = 'your@login.tld'; $wpass = 'your-WAPI-password'; $auth = sha1($login.sha1($wpass).date('H', time())); $url = 'https://api.wedos.com/wapi/json'; $input = [ 'request' => [ 'user' => $login, 'auth' => $auth, 'command' => 'request-name', 'data' => ['request-data'], 'clTRID' => 'request-id (optional)', 'test' => '1 (if you want to test the request only)' ] ]; $post = json_encode($input); $ch = curl_init($url); curl_setopt($ch,CURLOPT_TIMEOUT,60); curl_setopt($ch,CURLOPT_POST,true); curl_setopt($ch,CURLOPT_POSTFIELDS, 'request=' . $post); curl_setopt($ch,CURLOPT_RETURNTRANSFER,true); curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/x-www-form-urlencoded']); $res = curl_exec($ch); ?>
PHP example:
<?php
date_default_timezone_set('Europe/Prague');
$login = 'your@login.tld';
$wpass = 'your-WAPI-password';
$auth = sha1($login.sha1($wpass).date('H', time()));
$url = 'https://api.wedos.com/wapi/json';
$input = [ 'request' => [
'user' => $login,
'auth' => $auth,
'command' => 'request name',
'data' => ['request data'],
'clTRID' => 'request identifier',
'test' => '1 (if you only want to test the request)'
]
];
$post = json_encode($input);
$ch = curl_init($url);
curl_setopt($ch,CURLOPT_TIMEOUT,60);
curl_setopt($ch,CURLOPT_POST,true);
curl_setopt($ch,CURLOPT_POSTFIELDS, 'request=' . $post);
curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/x-www-form-urlencoded']);
$res = curl_exec($ch);
?>
Response Structure
The response consists of the following data:
- code: The return code for the given request. You can find more information in the chapter Return Codes.
- result: Return code description.
- timestamp: Command execution time in UNIX format.
- clTRID: Client’s request identifier.
- svTRID: Server’s request identifier.
- command: WAPI request.
- data: Return data. None if the request fails.
- test: Included with responses for test requests.
A sample JSON response looks like this:
{ "response": { "code": "1000", "result": "ok", "timestamp": "1286356644", "svTRID": "1286356644.0246.21616", "command": "domain-create", "data": { "num": "1311000863", "expiration": "2011-10-06" }, "test": "1" } }
Notifications
Asynchronous requests cannot be performed immediately. You can monitor the progress and result of such operations through notifications. Synchronous requests do not use notifications.
If WAPI cannot complete the operation immediately, it returns Request pending (1001) in response. After the operation is completed (for more complicated actions of individual steps), it creates a notification that is similar to a classic response. You can match the notification to the corresponding request using the clTRID or svTRID parameters.
Notification data is always encoded in UTF-8.
You can receive notifications in the following ways (according to the settings):
- Using the POLL queue.
- Send to specified email address.
- Via HTTP (or HTTPS) protocol to the URL address specified by you using the POST method in the request parameter. An HTTP response with a return code of 200 is considered a success. If delivery fails, the system will attempt to deliver the notification againat several-minute intervals.
A sample notification in JSON format looks like this:
{
"notify": {
"code": 1000,
"result": "OK",
"timestamp": 1286957932,
"svTRID": "1286957874.1271.15706",
"command": "ping-async",
"ID": 2691
}
}
System Notifications
System notifications send information about relevant events, currently only about domain transfers to another registrar. If you have an active WAPI for your account, the system sends such information using notifications, similar to an asynchronous command.
Set the protocol in which WAPI sends system notifications in the customer administration panel according to the chapter WAPI Activation. This option works for notifications sent to an email or URL address. In the case of downloading from the POLL queue, the response is in the same form as the command.
The structure is the same as a classic notification, the command is always system-notify. You will then find more detailed information in the data node.
Basic Requests
Basic requests include ping, ping-async, and commands for working with the POLL queue poll-req and poll-ack.
ping
The ping command is used to test WAPI functionality – for example, login credentials, IP address or code.
The return values are:
- 1000 – OK
JSON ping
JSON request:
{ "request": { "user": "your@login.tld", "auth": "auth code", "command": "ping", "clTRID": "user request id" } }JSON response:
{ "response": { "code": "1000", "result": "OK", "timestamp": "UTF time", "clTRID": "user request id", "svTRID": "server request id", "command": "ping" } }
XML ping
XML request:
<request> <user>your@login.tld</user> <auth>auth code</auth> <command>ping</command> <clTRID>user request id</clTRID> </request>XML response:
<response> <code>1000</code> <result>OK</result> <timestamp>UTF time</timestamp> <clTRID>user request id</clTRID> <svTRID>server request id</svTRID> <command>ping</command> </response>
ping-async
The ping-async command tests the functionality of WAPI notifications.
The return values are:
- 1000 – OK
- 1001 – Waiting for request
JSON ping-async
JSON request:
{ "request": { "user": "your@login.tld", "auth": "auth code", "command": "ping", "clTRID": "user request id" } }JSON response:
{ "response": { "code": "1001", "result": "Request pending", "timestamp": "UTF time", "clTRID": "user request id", "svTRID": "server request id", "command": "ping" } }JSON notification:
{ "notify": { "code": “1000”, "result": "OK", "timestamp": "UTF time", "clTRID": "user request id", "svTRID": "server request id", "command": "ping-async", "id": "poll queue id", "data": { "round": "attempt number", "time": "time", "done": 1 } } }
XML ping-async
XML request:
<request> <user>your@login.tld</user> <auth>auth code</auth> <command>ping-async</command> <clTRID>user request id</clTRID> </request>XML response:
<response> <code>1001</code> <result>Request pending</result> <timestamp>UTF time</timestamp> <clTRID>user request id</clTRID> <svTRID>server request id</svTRID> <command>ping-async</command> </response>Follow-up XML notification:
<notify> <code>1000</code> <result>OK</result> <timestamp>UTF time</timestamp> <clTRID>user request id</clTRID> <svTRID>server request id</svTRID> <command>ping-async</command> <id>poll queue id</id> <data> <round>attempt number</round> <time>time</time> <done>1</done> </data> </notify>
poll-req and poll-ack
You can receive notifications from the POLL queue by combining poll-req and poll-ack commands:
- Use the poll-req command to download the oldest available notification.
- With the poll-ack command, mark the notification as read and make newer ones available until the queue is exhausted.
The return values for poll-req are:
- 1000 – notification received
- 1003 – no unread notification in queue
- 2150 – poll queue notifications disabled for this account
JSON poll-req
JSON request:
{ "request": { "user": "your@login.tld", "auth": "auth code", "command": "poll-req", "clTRID": "user request id" } }JSON response (notification available):
{ "response": { "code": “1000”, "result": "OK", "timestamp": "UTF time", "clTRID": "user request id", "svTRID": "server request id", "command": "poll-req", "data": { "notify": { "code": “1000”, "result": "OK", "timestamp": "UTF time", "clTRID": "request user id", "svTRID": "request server id", "command": "request name", "id": "poll queue id" } } } }JSON response (empty notification queue):
{ "response": { "code": 1003, "result": "Empty notifications queue", "timestamp": “1286962852”, "clTRID": "user request id", "svTRID": "server request id", "command": "poll-req" } }
XML poll-req
XML request:
<request> <user>your@login.tld</user> <auth>auth code</auth> <command>poll-req</command> <clTRID>user request id</clTRID> </request>XML response (notification available):
<response> <code>1000</code> <result>OK</result> <timestamp>UTF čas</timestamp> <clTRID>user request id</clTRID> <svTRID>server request id</svTRID> <command>poll-req</command> <data> <notify> <code>1000</code> <result>OK</result> <timestamp>UTF time</timestamp> <clTRID>request user id</clTRID> <svTRID>request server id</svTRID> <command>requestname</command> <id>poll queue id</id> </notify> </data> </response>XML response (empty notification queue):
<response> <code>1003</code> <result>Empty notifications queue</result> <timestamp>UTF time</timestamp> <clTRID>user request id</clTRID> <svTRID>server request id</svTRID> <command>poll-req</command> </response>
Include the following parameters in the poll-ack request:
- id – current poll notification ID
The return values for poll-ack are:
- 1002 – notification marked as read
- 2151 – notification not found
JSON poll-ack
JSON request:
{ "request": { "user": "your@login.tld", "auth": "auth code", "command": "poll-ack", "clTRID": "user request id", "data": { "id": “poll notification id” } } }JSON response:
{ "response": { "code": “1002”, "result": "Notification acquired", "timestamp": "UTF time", "clTRID": "user request id", "svTRID": "server request id", "command": "poll-ack" } }
XML poll-ack
XML request:
<request> <user>your@login.tld</user> <auth>auth code</auth> <command>poll-ack</command> <clTRID>user request id</clTRID> <data> <id>poll notification id</id> </data> </request>XML response:
<response> <code>1002</code> <result>Notification acquired</result> <timestamp>UTF time</timestamp> <clTRID>user request id</clTRID> <svTRID>server request id</svTRID> <command>poll-ack</command> </response>
Return Codes
Return codes in responses and notifications can help you diagnose the state or possible errors of your WAPI request.
Basic return code breakdown:
- 1xxx – the request was successful.
- 2xxx – invalid request (such as missing input items, invalid format or value).
- 3xxx – target object error – the requested action cannot be performed, the object is not in the correct state (for example, trying to register an already registered domain, etc.).
- 4xxx – request error (e.g. domain registry unavailable, communication error, etc.).
- 5xxx – internal system error
- x0xx, x1xx – general
- x2xx – domains
- x3xx – DNS
1xxx - ok
- 1000 OK
- 1001 Request pending
- 1002 Notification aquired
- 1003 Empty notifications queue
12xx - system notifications
- 1200 Domain transferred out
2xxx - invalid request - general
- 2000 Request parse error
- 2001 Invalid request – required parameter missing: user
- 2002 Invalid request – required parameter missing: auth
- 2003 Invalid request – required parameter missing: command
- 2004 Invalid request – only one data element is allowed
- 2005 Invalid request – clTRID parameter is too long
- 2006 Requests limit exceeded
- 2007 Invalid request – maximum request size exceeded
- 2008 Invalid request – request is too complex
- 2009 Invalid request – request is empty
- 2010 Unknown command
- 2011 Command disabled
- 2050 Authentication failure
- 2051 Access not allowed from this IP address
- 2052 IP adress temporarily blocked due to too many failed requests
- 2100 Required parameter missing
- 2101 Parameters mismatch
- 2102 Invalid request – input data encoding mismatch
- 2150 Notification polling not allowed for this account
- 2151 Notification does not exist
22xx - invalid request - domains
- 2201 Unsupported TLD
- 2202 Invalid or unsupported domain name format
- 2203 Invalid period
- 2204 Invalid request – required parameter missing: owner_c
- 2205 Invalid request – required parameter missing: domain
- 2206 Invalid request – internal error
- 2207 Invalid request – invalid format: owner_c
- 2208 Invalid request – invalid format: admin_c
- 2209 Invalid request – invalid format: nsset
- 2210 Invalid request – invalid format: dns
- 2211 Invalid request – too many DNS servers
- 2212 Invalid request – required parameter missing: nsset
- 2213 Invalid request – required parameter missing: dns
- 2214 Invalid request – duplicate DNS entry
- 2215 Invalid request – required parameter missing: auth info
- 2216 Invalid or unsupported contact name format
- 2217 Invalid request – invalid contact data
- 2218 Invalid request – contact identificator is created automatically
- 2219 Invalid request – required parameter missing: company
- 2220 Invalid request – required parameter missing: fname
- 2221 Invalid request – required parameter missing: lname
- 2222 Invalid request – required parameter missing: email
- 2223 Invalid request – invalid format: email
- 2224 Invalid request – required parameter missing: email2
- 2225 Invalid request – invalid format: email2
- 2226 Invalid request – required parameter missing: phone
- 2227 Invalid request – invalid format: phone
- 2228 Invalid request – required parameter missing: fax
- 2229 Invalid request – invalid format: fax
- 2230 Invalid request – required parameter missing: ic
- 2231 Invalid request – invalid format: ic
- 2232 Invalid request – required parameter missing: dic
- 2233 Invalid request – invalid format: dic
- 2234 Invalid request – required parameter missing: addr_street
- 2235 Invalid request – required parameter missing: addr_city
- 2236 Invalid request – required parameter missing: addr_zip
- 2237 Invalid request – required parameter missing: addr_country
- 2238 Invalid request – invalid format: addr_country
- 2239 Invalid request – required parameter missing: addr_state
- 2240 Invalid request – required parameter missing in other data
- 2241 Invalid request – invalid format in other data
- 2242 Invalid request – invalid status
- 2243 Invalid request – function SendAuthInfo is not allowed for this domain
- 2244 Invalid request – contact transfer is not allowed for this TLD
- 2245 Invalid request – rules agree missing
- 2246 Invalid request – invalid format: rules agree
- 2247 Invalid or unsupported NSSET name format
- 2248 Invalid request – invalid NSSET data
- 2249 Invalid request – NSSET transfer is not allowed for this TLD
- 2250 Invalid request – domain check – max. query hour limit exceeded
- 2251 Invalid request – domain check failed, try again later
- 2252 Invalid request – domain transfer check – max. query hour limit exceeded
- 2253 Invalid request – invalid format: addr_zip
23xx - invalid request - DNS
- 2301 Invalid request – WDNS domain – invalid type format
- 2302 Invalid request – WDNS domain – required parameter missing: primary_ip
- 2303 Invalid request – WDNS domain – invalid primary_ip format
- 2304 Invalid request – WDNS domain – invalid axfr_enabled format
- 2305 Invalid request – WDNS domain – required parameter missing: axfr_ips
- 2306 Invalid request – WDNS domain – invalid axfr_ips format
- 2308 Invalid request – WDNS domain – invalid ns format
- 2309 Invalid request – WDNS domain – invalid rdtype format
- 2310 Invalid request – WDNS domain – rows count limit reached
- 2311 Invalid request – WDNS domain – invalid name format
- 2312 Invalid request – WDNS domain – invalid name format for this rdtype
- 2313 Invalid request – WDNS domain – invalid CNAME for this name
- 2314 Invalid request – WDNS domain – invalid rdata format for this rdtype
- 2315 Invalid request – WDNS domain – invalid TTL
- 2316 Invalid request – WDNS domain – this row exists
- 2317 Invalid request – WDNS domain – invalid TTL limit
- 2318 Invalid request – WDNS domain – unsupported action for secondary domain
- 2319 Invalid request – WDNS domain – unsupported action for primary domain
- 2320 Invalid request – WDNS domain – invalid or unsupported new domain name format
- 2321 Invalid request – WDNS domain – unsupported TLD of new domain name
- 2322 Invalid request – WDNS domain – maximum user domains count exceeded
30xx - target object error - general
- 3001 Billing error – invalid currency
- 3002 Billing error – insufficient credit
- 3003 Account error – undefined contact data
32xx - target object error - domains
- 3201 Domain is registered
- 3202 Domain is not available (unknown reason)
- 3203 Domain is not available
- 3204 Domain is not available, quarantine
- 3205 Domain is not available, reserved
- 3206 Domain is not available, blocked
- 3207 Registered by target registrar
- 3208 Transfer not allowed, expiration too close
- 3209 Domain send auth info failed
- 3210 Domain send auth info failed: domain is not available
- 3211 Contact owner_c is not available
- 3212 Contact admin_c is not available
- 3213 Contact send auth info failed: contact is not available
- 3214 NSSET is not available
- 3215 Contact send auth info failed
- 3216 Domain info failed
- 3217 NSSET send auth info failed
- 3219 Domain already pending for transfer
- 3220 Domain is already registered in our system
- 3221 Domain create failed
- 3222 Domain open failed
- 3223 Domain authentication error
- 3224 Domain renew failed
- 3225 Domain update DNS failed
- 3226 Domain transfer failed
- 3227 Domain transfer failed – authorization error
- 3228 Contact is not supported
- 3229 Contact is not available
- 3230 Contact create failed
- 3231 Contact is already registered
- 3232 Contact is not available (unknown reason)
- 3233 Contact is not available
- 3234 Contact is not available, quarantine
- 3235 Contact is not available, reserved
- 3236 Contact is not available, blocked
- 3237 Contact is already registered by target registrar
- 3238 Contact update – authorization error
- 3239 Contact update failed
- 3240 Contact transfer – authorization error
- 3241 Contact transfer failed
- 3242 NSSET is not supported
- 3243 NSSET is not available
- 3244 NSSET create failed
- 3245 NSSET is registered
- 3246 NSSET is not available (unknown reason)
- 3247 NSSET is not available
- 3248 NSSET is not available, quarantine
- 3249 NSSET is not available, reserved
- 3250 NSSET is not available, blocked
- 3251 NSSET is registered by target registrar
- 3252 NSSET update – authorization error
- 3254 NSSET update failed
- 3255 NSSET transfer – authorization error
- 3256 NSSET transfer failed
- 3257 NSSET send auth info failed: NSSET is not available
33xx - target object error - WEDOS DNS (WDNS)
- 3301 WDNS domain delete failed
- 3302 WDNS domain add failed
- 3303 WDNS domain exists
- 3304 WDNS domain update failed
- 3305 WDNS domain user locked
- 3306 WDNS domain is deleted
- 3307 WDNS domain row add failed
- 3308 WDNS domain row delete failed
- 3309 WDNS domain row ID does not exist
- 3310 WDNS domain row update failed
- 3311 WDNS domain copy failed
- 3312 WDNS new domain exists
40xx - request error - general
- 4000 Internal error
- 4001 Internal exception
- 4002 Billing error – credit deduction failed
- 4003 Billing error – billing failed
42xx - request error - domains
- 4201 Domain check failed, try again later
- 4202 Contact owner_c is not available, try again later
- 4203 Contact admin_c is not available, try again later
- 4204 NSSET is not available, try again later
- 4205 Domain info failed, try again later
- 4206 Domain transfer check failed, try again later
- 4207 Domain create failed, try again later
- 4208 Domain renew failed, try again later
- 4209 Domain transfer failed, try again later
- 4210 Domain update DNS failed, try again later
- 4211 Contact check failed, try again later
- 4212 Contact is not available, try again later
- 4213 Contact create failed, try again later
- 4214 Domain send auth info failed, try again later
- 4215 Contact update failed, try again later
- 4216 Contact transfer failed, try again later
- 4217 Contact send auth info failed, try again later
- 4218 NSSET check failed, try again later
- 4219 NSSET create failed, try again later
- 4220 NSSET update failed, try again later
- 4221 NSSET transfer failed, try again later
- 4222 NSSET send auth info failed, try again later
5xxx - internal errors and status codes
- 5000 Fatal error
- 5001 Internal authentication error
- 5002 Internal pricing error
- 5003 Out of order
Glossary
- Asynchronous request: A request taking a long time to get executed returns only a notification of acceptance, you can follow the further progress via notifications.
- API: Application Programming Interface. An interface that allows you to use your own code to retrieve data or manage a third-party application.
- Data: Contents of some commands specifying detailed settings. The data structure depends on the specific command.
- JSON: JavaScript Object Notation. A modern way of communicating with an API.
- Notification: JSON or XML code with messages about the progress of an asynchronous command.
- Request: A piece of code/data carrying instructions for an API.
- Return code: A number identifying the WAPI response type.
- Synchronous request: A request executed practically instantly. Returns a complete response almost immediately, does not use notifications.
- System notifications: A special type of notifications about events in the system, WAPI sends them automatically in a set format.
- UTF-8: Unicode Transformation Format. A widely used international character encoding standard supporting a large number of characters.
- WAPI: An interface for managing some parts of customer administration (credit account, domains, DNS).
- XML: eXtended Markup Language. A legacy way of communicating with an API.