Basics

Security

Login & Security

All transactions are secured by SSL. The DMAPI server is using an official SSL certificate. Within the login procedure, the client is assigned an unique authorisation id ('Auth-Sid').

Username and Password

Every request (except login, of course) requires the presence of this Auth-Sid variable. An active session will expire after a period of inactivity (default: 1 hour).

Example:

https://dmapi.joker.com/request/query-domain-list?auth-sid=20ddb8c3b2ea758dcf9fa4c7f46c0784

In case you use a browser to access this interface, a session id will be set as a cookie, hence need not to be specified as Auth-Sid (unless cookies are not supported, or turned off). In any case, Auth-Sid has precedence if provided.

API Keys

Instead of using your user- and password credentials, you may also use so called 'API keys' for login. This way, you can create several DMAPI access facilities, which has several advantages:

you do not need to expose username and password in your scripts
API keys can be restricted to be "read only" (no modifications possible), or to allow 'modifications only' (can not produce costs)
you may hand API keys to your staff to enable them to do specific things with Joker.com

Create your API keys in 'My Profile' in section 'Manage Joker.com API access keys'

Example usage:

https://dmapi.joker.com/request/login?api-key=Key_created_in_your_Profile_at_Joker.com

The result is the same as for "login"-request, you have to use the provided auth-sid for the subsequent actions.

Last update: 2019-12-18 16:26

Commonalities for all requests

DMAPI-Server URL

This is the service address which has to be used for all requests:

https://dmapi.joker.com

This is how a request looks like:

https://dmapi.joker.com/request/<name-of-request>?<name-of-parameter-1>=<value-of-parameter-1>

&<name-of-parameter-2>=<value-of-parameter-2>&auth-sid=<your-session-id>

Header fields which are returned by most requests

Tracking Id	Unique server-assigned tracking id, assigned to almost all requests
Status-Code	0 if no error occured, otherwise other than 0
Status-Text	Human readable error description
Result	ACK or NACK (= "Acknowlegded" or "Not Acknowledged")
Error	May be returned if (and only if) the request was rejected, in this case reason(s) will be provided. Presence of this line in headers is indicative for that processing didn't take place.
Warning	Indicative of non-fatal processing or validation problems
Proc-Id	Joker.com processing ID
HTTP error codes	200 if everything is OK (request was accepted and processed or queued for processing), otherwise the reason will be provided in Error header lines (or, if this is absent, HTTP error code should be used).

IMPORTANT: Every request (except "login") requires the presence of the Auth-Sid variable ("Session ID"), which is returned by the "login" request (login). An active session will expire after some inactivity period (default: 1 hour).

In case you are using a browser to access this service, the session id will be set as a cookie, hence need not to be specified as Auth-Sid (unless cookies are not supported or turned off). In any case, Auth-Sid has precedence, if provided.

Requests consist of these parts:

"Requires": Defines variables (sometimes referred to as 'fields') that MUST be present
"Accepts": Defines variables that MAY be present (but not required)
"Returns": Describes the request's output - header fields and extra data (if any). If "Returns" is omitted, then a standard reply should be expected (Status-Code, Status-Text, Proc-ID etc)

Last update: 2019-12-18 16:27

Whois Privacy Services with DMAPI

Whois Privacy Services

Please find general details about Joker.com Whois Privacy Services here: Whois Privacy Services

Privacy services are available for most generic top level domain names. The availablitiy of privacy services is indicated in Joker.com's price list and domain search.

For requests "domain-register" and "domain-transfer-in-reseller", there exists an additional parameter "privacy":

privacy=basic (owner contact name and/or organisation left intact, address & emails are masked)
privacy=pro (everything is masked)
privacy=none (same as "no privacy parameter provided")

For "domain-renew", the additional parameter privacy works similar:

privacy=basic (owner contact name and/or organisation left intact, address & emails are masked)
privacy=pro (everything is masked)
privacy=none (explicitly do a renew without privacy services, even if currently privacy is enabled)
privacy=keep (renew with the same level of privacy service which is currently active for the domain) - this now is also default; for domains without an existing privacy service subscription, "keep" means "none", so there will be no privacy service ordered. If there is an existing privacy service subscription active, and this privacy service is not set to "off", "keep" will also renew this privacy service subscription, together with the domain.

To order privacy services for existing domains, the new request "domain-privacy-order"can be used:

    domain=example.com
    period=12 (in months, as usual)
    expyear=2016 (privacy expiration year, similar to domain renewal request)
    privacy=basic|pro 

    If neither period nor expyear is provided, then privacy is ordered for
    remaining domain lifetime, whatever it is.

    Example:
    https://dmapi.joker.com/request/domain-privacy-order?domain=example.com&privacy=basic&auth-sid=<your-current-session-id>

The request "domain-set-property" allows to manage privacy services for domains which already do have a valid privacy service subscription:

privacy=basic (activate "basic" privacy service)
privacy=pro (activate "pro" privacy service)
privacy=off (deactivate privacy service - Whois data will be disclosed)

Samples:

Ordering domain with privacy:

https://dmapi.joker.com/request/domain-register?domain=example.com&period=12&owner-c=CCOM-1&billing-c=CCOM-1&admin-c=CCOM-1&tech-c=CCOM-1&ns-list=a.ns.joker.com:b.ns.joker.com&privacy=pro&auth-sid=<your-current-session-id>

Renew domain and order privacy:

https://dmapi.joker.com/request/domain-register?domain=example.com&period=12&privacy=basic&auth-sid=<your-current-session-id>

Request incoming transfer and enable privacy:

https://dmapi.joker.com/request/domain-transfer-in-reseller?domain=example.com&transfer-auth-id=zigzag&billing-c=CCOM-1&admin-c=CCOM-1&tech-c=CCOM-1&privacy=pro&auth-sid=<your-current-session-id>

Temporarily disable privacy (assuming that it is active):

https://dmapi.joker.com/request/domain-set-property?domain=example.com&privacy=off&auth-sid=<your-current-session-id>

Fetch real contact data from privacy protected domain:

https://dmapi.joker.com/request/query-whois?domain=example.com&internal=1&auth-sid=<your-current-session-id>

Last update: 2017-06-12 10:45

Differences to Email Gateway

The main differences in handling between DMAPI and Email Gateway at Joker.com are:

DMAPI only accepts pre-registered contact and name-server handles. This means that before you can register (or modify) domains, you MUST create all necessary contacts and name-servers.
universal requests - unlike with the email interface, there is no differentiation in requests for different domain/contact types.
some requests are asynchronous, means, they are processes within a queue in the background. The acceptance of a request by DMAPI not necessarily means that it is already processed (or will be processed at all because of later errors). The immediate request reply states, wether the request has been accepted by the system. The 'real' reply (results, acknowledgement or refusal) will be stored on the server and can be retrieved later. To list available replies, you should use the requests "result-list", "result-retrieve" and "result-delete" periodically.

NOTE: Not retrieved replies will be kept on the server for a period of 30 days, after this time, only the status of specific request will be available (success or failure).

IMPORTANT: Please also note that the registration/renewal period is in MONTHS, NOT YEARS! This is to allow future micro-registrations.

Last update: 2016-04-04 13:43