# DMAPI
# Basics
## 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/?=`
`&=&auth-sid=`
Header fields which are returned by most requests
Tracking Id
Unique server-assigned tracking id, assigned to almost all requests
Status-Code
0 or 1000-1999 if no error occured, all other values indicate some sort of error.
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)## 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](https://joker.com/goto/prices) and [domain search](https://joker.com/goto/order).
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=
```
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=`
Renew domain and order privacy:
`https://dmapi.joker.com/request/domain-register?domain=example.com&period=12&privacy=basic&auth-sid=`
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=`
Temporarily disable privacy (assuming that it is active):
`https://dmapi.joker.com/request/domain-set-property?domain=example.com&privacy=off&auth-sid=`
Fetch real contact data from privacy protected domain:
`https://dmapi.joker.com/request/query-whois?domain=example.com&internal=1&auth-sid=`
**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**!
# Account and Handling
## login
### Login with Username & Password
**Requires (mandatory):**
*username*
Joker.com username (email address)
*password*
Joker.com password
**Returns:**
*Auth-SID*
Authenticated Session ID, must be provided with any other request (parameter *auth-sid*)
*List of TLDs*
List of domain TLDs which are available to the reseller.
To be able to use the entire API, you must have a reseller account with Joker.com (and use this account to log in). **Example:**
` https://dmapi.joker.com/request/login?username=johndoe&password=mypass`
### Login with 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**](https://joker.com/goto/myjoker)' 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.
## logout
**Returns: Nothing** Used to forcibly close (terminate) a session. The session identified by Auth-SID may not be used anymore to send requests. Normally not required as session will timeout anyway (default: 1 hour).
## result-list
**Accepts:**
*pending*
get results of requests still in progress
*showall*
get all results incl. deletes using result-delete
*period*
get results for specifed period of days (default: 90)
*date*
get results received on (or before) specified date. When date is specified, parameter "period" will be applied to this date (instead of today) and defaults to 1
*offset*
start dispalying results from specified position
*limit*
only get number of results specified by limit
*status*
get results having specified status (ack/nack/?)
*count-only*
when set to 1, only count number of records and return single line in format "Records: N"
All following filters may use patterns ("\*" and "?")
*rtype*
get results for requests of specified type (domain-register/etc)
*objid*
get results for specified object ids (domain names, contacts, hosts)
*procid*
get results for specified proc-id
*svtrid*
get results for specifued SvTrId
*cltrid*
get results for specified ClTrId
**Returns:**
List of answers from joker.com (one per line):
```
TimeStamp SvTrId Proc-ID request-type status ClTrId
```
**Where:**
```
TimeStamp: The time when request was made, YYYYMMDDHHMMSS
SvTrID: Tracking-Id associated with this request.
Proc-ID: Proc-Id associated with this request.
request-type: The type of the request.
request-object: The object name (host, domain or contact handle)
status: ack, nack or ?, where ack means that request was completed successfully.
ClTrId: User specified transaction ID, or "-" if nothing was provided by the user
```
**Example:**
```
https://dmapi.joker.com/request/result-list
```
## result-retrieve
**Accepts:**
*Proc-ID*
One of these must be specified. If both are specified, SvTrId has precedence.
*SvTrID*
**Returns:**
Answer (processing result) associated with specified Tracking/Processing ID. If detailed information (content) is not available, only status will be returned
**Please note:** Since there is no requirement of uniqueness for user-specified transaction ids, it is not possible to use them to retrieve specific results. **Example:**
` https://dmapi.joker.com/request/result-retrieve?proc-id=8181810&auth-sid=`
## result-delete**Accepts:**
*Proc-ID*
One of these must be specified. If both are specified, SvTrId has precedence
*SvTrID*
**Returns:** A descriptive message (confirmation) in case of success.
This request will delete the content (not the status) of a reply to an asynchronous request. Deleted results will not be listed anymore when using *result-list*.
## query-profile **Returns:** Returns reseller profile data in format "key: value". May be used to query account balanceExample:
```
https://dmapi.joker.com/request/query-profile
```
## query-account-balance
**Returns:**
Returns actual account balance - available, pending and total.
Example:
```
https://dmapi.joker.com/request/query-account-balance
```
You will get a response like this:
```
Status-Code: 1000
Status-Text: OK
Columns: available,pending,total,currency
Separator: TAB
975.00 25.00 1000.00 USD
```
The columns are:
available
amount available for orders
pending
amount reserved for pending operations (renewals, transfers etc)
total
the sum of available and pending, i.e. the effective balance
currency
currency of your account
## query-order-list
##### Parameters
show-all
Show all orders including those which did not incur any charges.
after
Show only orders after specified date (inclusive). Date must be in ISO format: YYYY-MM-DD
before
Show only orders before specified data (inclusive).
If neither "after" or "before" is specified, the default is a list of orders within last 30 days.
type
Show only orders of specified type. Types are:
create
create domain
renew
renew domain
transfer
transfer domain
restore
restore domain from RGP
delete\_domain
delete domain
cor
COR (Change Of Registrant aka Domain Owner Change)
create-contact
create contact
autons
modify DNS zone
lock
lock domain
unlock
unlock domain
privacy\_pp1
Privacy Basic
privacy\_pp2
Privacy Pro
credit-increase
account top-up
payment\_fee
payment fee, amount deducted from account top-up
status
Show only orders with specified completion status.
Possible values are: ok, error, pending
tld
Filter by TLD. By default all TLDs are included.
fqdn
Filter by FQDN (domain name). By default all domains (and other objects) are included.
fqdn-like
Filter by FQDN with wilcards. Wildcards are "\*" (any number of any characters) and "?" (exactly one any character).
*Example*: "\*.com" will list orders involving any .com domains.
order-id
Only show order with specified id.
order-id-after
Show orders with ids greater or equal than specified.
order-id-before
Show orders with ids less or equal than than specified.
proc-id
Only show order with specified processing id.
proc-id-after
Show orders with processing ids greater or equal than specified.
proc-id-before
Show orders with processing ids less or equal than than specified.
limit
Limit the number of returned rows. Used only when above described id ranges are specified. Ignored when parameters `after` or `before` are used.
The default (and the maximum) is 1000.
asc
If true, sort ascending - recent orders come last. The default is false - recent orders come first.
separator
Use specified separator in table output. Default is "tab". Possible values:
tab
\\t
comma
,
semicolon
;
pipe
|
num-comma
If true, use comma (",") as decimal separator in numbers. Default is false, i.e. use dot (".")
Please note that "comma" separator cannot be used when "num-comma" is set to "true".
csv
If true, return result as a downloadable CSV file, without DMAPI headers.
per-page
Number of rows returned per single request when using paging. Must be at least 10.
page
Page number when `per_page` is set. Pages are numbered starting with 1.
count-only
Only count number of rows that would be returned given specified parameters.
##### Returns
A CSV-like list following the usual DMAPI header:
```
Status-Code: 1000
Status-Text: OK
Row-Count: 6
Columns: order_id,proc_id,created_at,status,type,amount_brutto,amount_netto,currency,identifier
85671266 917263183 2024-03-17T07:58:14Z ok renew 10.19 10.19 USD example.org
85671265 917263182 2024-03-17T07:58:12Z ok renew 10.19 10.19 USD example.com
85671256 917263173 2024-03-17T07:57:06Z ok renew 29.40 29.40 USD example.net
85671255 917263172 2024-03-17T07:57:05Z ok create 2.00 2.00 USD example.zone
85671227 917263144 2024-03-17T07:54:07Z ok service_request 0 0 example.com
85671226 917263143 2024-03-17T07:54:07Z ok create-contact 0 0 CCOM-91167381
```
##### Output columns description
order\_id
Order ID
proc\_id
Processing ID
created\_at
Order creation time (UTC)
status
Order status: ok, error, pending
type
Order type
amount\_brutto
Amount charged including VAT. If VAT is not deducted then it has same value as amount\_netto.
amount\_netto
Amount charged excluding VAT.
currency
Currency if amount is non-zero; empty if amount is zero.
identifier
Domain or other object name that is affected by the order
Positive amounts are amounts ***paid***, i.e. ***deducted*** from your balance.
Negative amounts are amounts ***received***, i.e. ***added*** to your balance. This usually happens if you get a refund.
If `status` is not `ok`, then the amount is neither added or deducted - it is just a reference to the cost of the order.
If `show-all=false` (the default) then only orders processed within last 3 years are visible.
If `show-all=true` then only orders from last 90 days are visible.
Period covered by `after`/`before` parameters may not be longer than 90 days. The period is enforced *silently*, you will get no warning - just orders within 90 days, so if there are none you will see empty response.
Empty (no rows) output means that there are no orders matching specified parameters are visible.
If you use ranged search by `order-id` or `proc-id` and do not limit search period using `after` and/or `before`, the maximum number of rows returned is 1000 (and is the default). It could be lowered by using `limit` parameter, but 1000 is the maximum anyway.
However, if you do use `after` and/or `before` parameters, they will be applied `independently` - this means that if specified id range does not fit into specified time range, you will get no results.
Parameters `fqdn` and `fqdn-like` actually could be used not only for domain names but for other object identifies, like contact handles - it depends on operation.
**Please note that all returned data, including amounts charged, is for informational purposes only!**
The sum of amounts may not exactly match the issued invoices due to possible adjustments related to discounts, manual processing, and other corrections that cannot be properly reflected in this list.
Returns additional column, showing domain status; may be 0 or 1
*showgrants*
Returns additional column, showing domain grants; may be 0 or 1
*showprivacy *
Returns additional columns, showing privacy status; may be 0 or 1
The following columns will be added:
privacy-status - shows the currently active privacy status
privacy-origin - shows the privacy status, which was bought
privacy-expiration - shows the expiration date of privacy
**Returns**
List of registered domains and their expiration dates (one per line, separated by whitespace). If "showstatus" is present, the the list will be with three columns, the last one showing domain status (like "lock,autorenew" etc - comma separated). **Example:**
`https://dmapi.joker.com/request/query-domain-list?pattern=a*&showstatus=1&auth-sid=`
## domain-register
**Requires (mandatory)**
*domain*
Domain name to register
*period*
Registration period in **months** (not in years!)
*status*
Set domain status (only "production" is accepted so far)
*owner-c*
Owner contact handle
*billing-c*
Billing contact handle
*admin-c*
Administrative contact handle
*tech-c*
Technical contact handle
*ns-list*
List of name servers, delimited by colon
**Accepts (optional)**
*autorenew*
if set to "1", domain will be autorenewed upon expiration
*language*
3 letter language code for IDN domains
*registrar-tag*
Registrar tag, also known as "Membership token", currently only needed for .**XXX** domains
*privacy*
basic|pro|none - adds whois privacy subscription to domain order, see also Whois Privacy Services
*max-price*
maximum price user is willing to pay for a domain registration, renewal or transfer. If provided, it must be a number (fractions allowed) above 0.
If not provided and domain has non-standard pricing, or if *max-price* is lower than actual domain price at the moment of registration, the request will fail.
If *max-price* is higher than the actual domain price, then only the actual price will be deducted
This request allows to **register** a domain.
You must have **registered contacts** (handles) to be able to register a domain.(=> contact-create, query-contact-list)
**Important:** Please note that the registration period is in **months, not years**. In most cases, this number is a **multiple of 12**.
**Example:**`https://dmapi.joker.com/request/domain-register?domain=example.com&period=12&status=production&owner-c=COCO-4711&billing-c=COCO-4712&admin-c=COCO-4712&tech-c=COCO-4712&ns-list=a.ns.joker.com,b.ns.joker.com,c.ns.joker.com&auth-sid=`
## domain-renew
**Requires (mandatory)**
*domain*
domain name to renew
*period*
renewal period in **months** (not in years!)
*expyear*
the wanted expiration year (e.g. '2014')
**Accepts (optional)**
*privacy*
basic|pro|none|keep - adds whois privacy subscription to domain renewal
none: explicitly do a renew without privacy services, even if currently privacy is enabled
keep: renew with the same level of privacy service which is currently active for the domain
see also Whois Privacy Services
*max-price*
maximum price user is willing to pay for a domain registration, renewal or transfer. If provided, it must be a number (fractions allowed) above 0.
If not provided and domain has non-standard pricing, or if *max-price* is lower than actual domain price at the moment of registration, the request will fail.
If *max-price* is higher than the actual domain price, then only the actual price will be deducted
With this request you can renew the domain. Please be aware that all renewals are not refundable.
"**expyear**" is a safety option which can be used **instead of "period"** to renew domain till specified year (not longer). If you use "period", and by mistake send the request more than once, domain will be renewed again, while with "expyear", it will not be renewed if it's expiration year is greater or equals to specified.
**Only one of "period" or "expyear" may be used, but not both.**
**Please note:**
- registration period is in **months, not years**! In most cases, this number is a **multiple of 12**.
- to prevent from unintended/errorneous multiple renewals, **a specific domain name can only be renewed once per 6 hours.** This means, if you want to renew a domain for 2 years, you should use a period of "24" - in case you want to renew using two requests with a period of "12", the 2nd request must not be sent before 6 hours after the 1st one.
**Example:**` https://dmapi.joker.com/request/domain-renew?domain=example.com&period=12&auth-sid=`
## domain-modify
**Requires (mandatory)**
*domain*
domain name to modify
**Accepts (optional)**
* billing-c*
domain contact data to modify
* admin-c*
* tech-c*
* ns-list *
list of new nameservers delimited by colon ":" (it will **replace** existing nameservers!)
*registrar-tag*
Registrar tag, also known as "Membership token", currently used for **.XXX** domains
*dnssec*
if specified, allows setting or removal of DNSSEC keys for domain. If not specified, DNSSEC records will not be changed. Value of "0" will remove DNSSEC, value of "1" will add DNSSEC (and ds-N parameters must be provided) ds-1 list of DNSSEC parameter sets (min. 2, max. 6) for DNSSEC enabled domains
ds-2 for com/net/org/tv/cc each entry has format:
ds-3 tag:alg:digest-type:digest
ds-4 for de:
ds-5 protocol:alg:flags:pubkey-base64
ds-6
With this request you can modify
- contact handles
- nameservers
- DNSSEC parameters (for DNSSEC capable nameservers and TLDs supporting DNSSEC) Please only specify contact handles which you want to modify, all unspecified handles will be left as is.For DNSSEC, you will find more information [here](http://en.wikipedia.org/wiki/Domain_Name_System_Security_Extensions) .
**Example:**
if present and set to '1', 'Y' or 'Yes', the domain will be deleted even if older than 72 hours.
With this request you can delete a domain. If you delete a domain (**gTLDs only**) within the **first 72 hours** after the registration, **the registration-fee will be refunded** to your account. To delete a domain which is registered for more than 72 hours, you must specify "force=1", otherwise the request will be rejected.
Please note: The number of refundable deletions of domains per month is limited, and depends on the number of domains in a portfolio, and the related TLD registry.**Example:**
(optional) full name (if empty, fname + lname will be used)
*fname*
first name
*lname*
last name
*title*
(optional)
*individual*
(optional) Y, Yes, N, No
*organization *
(optional if individual)
*email*
mailaddress of the contact
*address-1*
street address
*address-2*
(optional)
*address-3*
(optional)
*city*
*state*
(optional)
*postal-code*
*country*
ISO country code (2 letters)
*phone*
*extension*
(optional)
*fax*
(optional)
*lock-opt-out*
(optional) yes, no **(new IRTP-C: do not apply a 60 days transfer lock to the domain)**
With this request you can change the visible **WHOIS owner** of a domain. Either "name" or "lname" and "fname" must be provided. Fields **not** marked as optional are mandatory, and must not be empty. For the revised ICANN IRTP-C (change of registrar) policy, please also visit our [documentation](https://joker.com/goto/resdocs).
**Example:**
With this request you can **lock a domain** to **prevent from fraudulent transfer attempts**. If a domain is locked, each transfer-request from a foreign registrar will be declined. **Example:**`https://dmapi.joker.com/request/domain-lock?domain=example.com&auth-sid=`
## domain-unlock
**Requires (mandatory)**
*domain*
domain name to unlock
With this request you can **unlock a domain**. If you want to transfer a domain to a foreign registrar, it has to be unlocked.**Example:**`https://dmapi.joker.com/request/domain-unlock?domain=example.com&auth-sid=`
## domain-transfer-in-reseller
**Requires (mandatory)**
*domain*
full qualified domain name to transfer to Joker.com
*transfer-auth-id*
AUTH-ID required for all domains except .eu
*owner-c*
new owner contact handle to be used for transferred domain
Accepts (optional)
*admin-c*
new admin contact handle
*tech-c*
new tech contact handle
*billing-c*
new billing contact handle
*status*
new domain status to be set after transfer (lock, production)
*period*
renewal period in months, **not** in years! \[not in use, please leave empty\]
*autorenew*
Autorenew flag for the domain (0 or 1); if not set explicitly, defaults to 1
*ns-list*
list of colon-separated nameservers
*privacy*
basic|pro|none - adds whois privacy subscription to domain transfer, see also Whois Privacy Services
*max-price*
maximum price user is willing to pay for a domain registration, renewal or transfer. If provided, it must be a number (fractions allowed) above 0.
If not provided and domain has non-standard pricing, or if *max-price* is lower than the actual domain price at the moment of registration, the request will fail.
If *max-price* is higher than the actual domain price, then only the actual price will be deducted
With this request you can initiate a transfer of the domain from another registrar to Joker.com.You have to provide a valid **AUTH-ID** (you have to request this from the **current** provider of the domain).
**Please note:**
- please make sure, that there is no so-called 'registry lock' active for the domain to be transferred. Please verify, that the current registrar does not block the domain, resp. deactivates the blocking
- the domain to be transferred must have been active for at least 60 days at the current registrar, otherwise the transfer may fail
- the domain to be transferred must not be object of an active ICANN UDRP dispute procedure
- the domain should have a remaining term of least 7 days, to ensure that the transfer succeeds within the time limits (a maximum of 5 days is granted to confirm or object a transfer). In case the domain has less than 7 days of remaining term, a successful transfer cannot be warranted.
- this procedure will trigger email notifications to the owner and the admin contact of the domain to be transferred (this is following mandatory ICANN transfer provisions)
**Example:**
With this request you can set a property (flag) for a domain or a set of domains, selected by wildcard pattern.
List of available properties and their effects:
*autorenew*
0 or 1
If set to 1, the domain will be automatically renewed on expiration (if you have enough funds in your account)
*whois-opt-out*
0 or 1
currently only used for .tel domains; if set to 1, owner information will not be shown in whois
*privacy*
off or basic or pro (if available)
*gdpr-opt-in*
0 or 1
opt-in to display contact data which is normally redacted by GDPR
If an empty value is provided, then the property will be cleared, i.e. the default will be used.
**Example:**
Retrieves domain's **Auth-ID**, which is required when transfering domains to another registrar. This request is not real-time, i.e. you have to check detailed reply (use "result-retrieve") to get the Auth-ID. **Please note**: **Every request will generate a new Auth-ID**, thus rendering any previously requested Auth-ID invalid. **Example:**
## domain-transfer-control
This request allows to retrieve status information for all pending transfers. Additionally, transfers can be cancelled, or the FOA email can be re-sent.
**Parameters:**
```
action One of: list, show, resend-foa, cancel
domain Domain name to control transfer of (ignored when action=list)
```
**action=*list***
When action=list, this request returns a list (columns are separated by tabs) of all currently pending transfers:
```
```
where <state> is one of (listed in "natural" transition order):
```
IN_DB
PAYMENT_PREPARED
PAYMENT_ACQUIRED
PENDING_FOA_SENDING
Joker.com could not parse the recipient of the FOA.
Manual action from Joker.com is required and happens
during office hours, thus in worst case it may take
few days (during weekend or holidays).
FOA_BEEN_SENT
FOA is sent and Joker.com is waiting for owner's
reaction. Owner has 5 days to react, thus the state
may last up to 5 days.
FOA_NACK FOA is rejected
FOA_ACK FOA is accepted
REGISTRY_REQUEST_SENT
REGISTRY_REQUEST_RECEIVED_NOW_WAITING
FOA had been accepted, transfer request is sent
and the losing registrar has to release the domain.
This state may take up to 5 days, we could do nothing
to speed it up.
While in this state, transfer may be cancelled
by using "action=cancel".
REGISTRY_CANCELATION_PENDING
The user has requested cancel of domain transfer
by using "action=cancel".
DOMAIN_WITH_JOKER_PENDING_COMPLETE
The domain is actually with Joker.com, but either
we haven’t noticed yet (batch pending) or manual
work is necessary.
Please contact Joker.com if this state lasts longer
than 1 hour.
PAYMENT_COMMITTED
TRANSFER_PROCESSED_SUCCESSFULLY
```
**action=*show***
When action=*show*, the status of a specified domain is returned like:
```
domain: example.com
status: FOA_BEEN_SENT
owner_email: owner@example.com
admin_email: admin@example.com
transfer-id: 123456
```
**action=*resend-foa***
When action=resend-foa, FOA will be resent (only possible in state FOA\_BEEN\_SENT).
**action=*cancel***
When action=cancel, the (pending) transfer will be cancelled.
**Returns**
Status code is 1000 for successful request, or >= 2000 otherwise.
**Example**
```
https://dmapi.joker.com/request/domain-transfer-control?domain=example.com&action=resend-foa
```
## domain-check
**Requires (mandatory)**
*domain*
domain name to check
**Accepts (optional)**
*check-price*
If provided, specifically check the price for: **create**, **renew**, **transfer**, **restore**
*period*
If provided, price will be calculated based on specified period. Period may be specified in years (values from 1 to 10) or in traditional for DMAPI months (>= 12, must be a multiple of 12).
*language*
Relevant only for IDN domains, specifies language as 2 letter (ISO 639.1) or 3 letter (ISO 639.2) code:
[https://www.loc.gov/standards/iso639-2/php/code\_list.php](https://www.loc.gov/standards/iso639-2/php/code_list.php)
With this request you can **check if a domain is available for registration, and what type of domain pricing will be applied for different types of orders.**
**Returns** one or more lines with key-value pairs as follows:
**domain-status:** <status>
<status> can be one of:
**available**
regular domain (non-premium) available for registration
**premium**
premium domain available for registration
**unavailable**
domain is not available for registration
If <status> is "unavailable", then domain-register request will fail, though domain-transfer-\* and domain-renew (if domain is with Joker.com) are possible, of course.
**domain-status-reason:** <status-reason>
Provides human-readable description why domain is unavailable for registration, like *blocked*, *reserved*, *registered* etc.
May be absent if registry does not provide specific reason. Should not be parsed as value is registry dependent and could be virtually anything.
**domain-class:** <class>
Specifies price-class. Anything but "standard" is considered "premium", though some registries use "tier-1", "premium", "BBB" etc.
Mostly a hint, values except "standard" should not be interpreted as they have no useful meaning and vary among registries.
**domain-price-<type>:** <price> <currency> <period>y
Reports domain price, where <type> will be value provided in check-price parameter, i.e. create, renew, transfer, restore.
- <price> is the final price, i.e. amount that will be deducted from the user's account, considering all discounts, promos etc.
- <currency> is a 3-letter currency code, serves only as information.
- <period> is reported in years and suffixed by "y", like "5y", and it may be different from "period" parameter value (depends on registry), for instance when requested period is not available, too low or too high.
The price reported is valid only for specified period, i.e. if price is 100 for 2 years it does not necessarily mean that price for 1 year is 50, thus it only makes sense to check price for the period which will be used verbatim in subsequent request of specified <type>.
**domain-price-promo:** <start> <end>
<start> and <end> are ISO timestamps in format like *2019-07-01T00:00:00.000Z*
For domains that have promotional pricing, this provides start and end timestamps of promotional period. Usually its mere presence means that promo-pricing is in effect, but to be sure values have to be checked explicitly.
**If "domain-status" returned "premium" or "domain-class" returned anything but "standard", then the parameter *max-price* must be present in register/transfer/renew requests.**
Full response example (web.blog):
```
domain-status: unavailable domain-status-reason: blocked domain-class: standard domain-price-create: 8.21 USD 1y domain-price-promo: 2019-09-01T00:00:00.000Z 2019-12-31T23:59:59.000Z
```
**Example:**`https://dmapi.joker.com/request/domain-check?domain=example.com&auth-sid=`
# Contacts
## query-contact-list
**Accepts:**
*pattern*
pattern to match (against handle)
*from*
start from this item in list
*to*
end by this item in list
*tld*
limits output to contact handles which may be used with specified toplevel domain (tld), like "com".
*extended-format*
provides additional information for every contact listed: name & organization. May be "1" or "0", defaults to "0"
**Returns:** List of registered contacts (handles), one per line. When "extended-format" is requested, output columns are separated by tabs ("\\t"), and "Columns" header provides column names. **Example:**
`https://dmapi.joker.com/request/query-contact-list?pattern=coco-47*&tld=com&auth-sid=`
## contact-create
**Requires:**
*tld*
target TLD where this contact is intended to be used.
*name*
full name (if empty, fname + lname will be used)
*fname*
first name (required for .FI contacts)
*lname*
last name (required for .FI contacts)
*title*
(optional)
*individual*
(optional) Y, Yes, N, No
*organization*
(optional if individual)
*email*
mailaddress of the contact
*address-1*
street address
*address-2*
(optional)
*city*
*state*
(optional)
*postal-code*
*country*
ISO country code (2 letters)
*phone*
*fax*
(optional)
*lang*
language to use for .EU contacts
*app-purpose*
required for .US contacts
*nexus-category*
required for .US contacts
*nexus-category-country*
required for .US contacts
*account-type*
required for .UK contacts, if used as owner contact
*company-number*
required for .UK contacts with specific account types
*orgid*
required for .SE/.NU contacts
*vatid*
(optional) for .SE/.NU contacts
*x-ficora-type*
required for .FI contacts
*x-ficora-is-finnish*
(yes/no) required for .FI contacts
*x-ficora-registernumber*
required for .FI contacts, if ficora-type is company
*x-ficora-identity*
required for .FI contacts, if type is person and finnish
*x-ficora-birthdate*
required for .FI contacts, if type is persion and not finnish
*x-ficora-legalemail*
(optional) for .FI contacts
Either "name" or "lname" and "fname" must be provided. Fields **not** marked '(optional)' are mandatory (and must not be empty).
Parameters "lname" and "fname", if provided, will be converted to "name" (simple concatenation of "fname" and "lname"), because registries support only "name" format. In general, use of "fname" and "lname" is deprecated, and support for these fields will be removed in version 1.2.
"**orgid**" represents Swedish personal or organisational number and is required for .SE/.NU contacts.
It starts with ISO 3166 Alpha-2 country code in square brackets. If the country code for Sweden is given \[SE\] a valid Swedish personal or organisational number must be given (6 digits, dash, 4 digits), otherwise 1 to 123 characters can follow.
If organization is empty and the country code for Sweden \[SE\] is given, orgid must be a personal number, not an organisational number.
"**vatid**" is optional for .SE/.NU contacts. It starts with a two letter country code (uppercase), followed by an optional space, followed by a country specific string containing digits 0-9, and letters a-z and A-Z, maximum 64 Chars.
**For .fi contacts:**
**"x-ficora-type"** is required for .fi contacts. The following values are accepted: privateperson, company, corporation, institution, politicalparty, township, government, publiccommunity
**"x-ficora-registernumber"** is required if x-ficora-type is set to "company".
**"x-ficora-is-finnish"** is always required for .fi contacts: yes = finnish company or person, no = not a finnish person or company
**"x-ficora-identity"** is required for .fi contacts, if x-ficora-type is set to 'privateperson' and x-ficora-is-finnish is set to 'yes'
**"x-ficora-birthdate"** is required for .fi contacts, if x-ficora-type is set to 'privateperson' and x-ficora-is-finnish is set to 'no' in the following date format "YYYY-MM-DD".
**Please note:**
- Parameters listed here (except "tld") may be used (or are required) in other requests, this is indicated by referring to "Contact fields".
- "lang" must contain two-letter ISO country (language) code, and is only required when creating .EU contacts. The purpose is to specify language to be used in notifications emails, sent from EURid. Please note - this field cannot be modified later, and the default is 'EN' (English)!
- "app-purpose", "nexus-category" and "nexus-category-contry" are required only when creating .US contacts, and cannot be modified later.
**Example:**`https://dmapi.joker.com/request/contact-create?tld=com&name=John Doe&email=johnd@someisp.com&address-1=Smartroad 1&city=Smalltown&postal-code=40122&country=US&phone=+1.422.8001&auth-sid=`
## contact-modify
**Requires:**
*handle*
contact handle to modify.
**Accepts:** Field names exactly like in contact-create request, except that omitted fields won't be modified. That is, if you specify a field, it will be used as a new value, if you omit it, the old value will remain. The field "tld" is not relevant for this request and will be ignored if present.
## contact-delete
**Requires:**
* handle *
contact handle to delete
With this request you can delete previously registered contacts **Example:**
`https://dmapi.joker.com/request/contact-delete?handle=coco-4711&auth-sid=`
# Nameservers
## query-ns-list
**Accepts:**
*pattern*
pattern to match (against host name, like "ns.dom\*")
*full*
include IPs if non-zero (0 or 1)
**Returns:**
List of registered name servers, one per line. If "full" is non-zero, then the list will include IP addresses, IPv4 (2nd column) and IPv6 (3rd column).Columns will be separated by tab ("\\t") character. If specific IP is not present (say, there is only IPv4 or IPv6), it will be listed as "-". Example of list with IPs:
IPv4 address (must not be from IANA's reserved range)
*ipv6*
IPv6 address (short notation like fec0::17 is accepted)
With this request a new nameserver can be registered with the registry. This is needed to use a nameserver with glue records.Either an IPv4 or IPv6 address is required.Multiple IPs could be specified using "," (comma) as a separator, like "ip=1.2.3.4,4.5.6.7"
## ns-modify or host-modify
**Requires:**
*host*
full qualified host name
*ip*
IPv4 address (must not be from IANA's reserved range)
*ipv6*
IPv6 address (short notation like 'fec0::17' is accepted)
With this request you can modify the IP address of a registered nameserver. Multiple IPs could be specified using "," (comma) as a separator, like "ip=1.2.3.4,4.5.6.7"
## ns-delete or host-delete
**Requires:**
*host *
Full qualified host name
With this request you can delete a registered nameserver.
# Modify Zonedata
## dns-zone-list
**Accepts:**
* pattern*
Pattern to match (globbing, like "dom\*")
**Returns:**
List zones (domains) which are managed and served by Joker.com name
servers. Zones are listed one per line.
## dns-zone-get
**Requires:**
*domain*
Zone (domain) name to fetch data from
**Accepts:**
include-defaults
If specified with value "1", the zone will always include default values (which are omitted otherwise)
**Returns:**Returns list of zone records.
The format of zone is as follows (one record per line):
```