# Account and Handling

## login

### Login with Username & Password

<span style="font-family: arial,helvetica,sans-serif; font-size: small;"> </span>

<span style="font-family: arial,helvetica,sans-serif; font-size: small;">**Requires (mandatory):**</span>

<table border="1" id="bkmrk-username-joker.com-u" style="width: 80%;"><tbody><tr><td>*<span style="font-family: arial,helvetica,sans-serif; font-size: small;">username</span>*</td><td><span style="font-family: arial,helvetica,sans-serif; font-size: small;"> Joker.com username (email address)</span></td></tr><tr><td>*<span style="font-family: arial,helvetica,sans-serif; font-size: small;">password</span>*</td><td><span style="font-family: arial,helvetica,sans-serif; font-size: small;">Joker.com password</span></td></tr></tbody></table>

<span style="font-family: arial,helvetica,sans-serif; font-size: small;"> **Returns:**</span>

<table border="1" id="bkmrk-auth-sid-authenticat" style="width: 80%;"><tbody><tr><td>*<span style="font-family: arial,helvetica,sans-serif; font-size: small;">Auth-SID</span>*</td><td><span style="font-family: arial,helvetica,sans-serif; font-size: small;">Authenticated Session ID, must be provided with any other request (parameter *auth-sid*)  
</span></td></tr><tr><td>*<span style="font-family: arial,helvetica,sans-serif; font-size: small;">List of TLDs</span>*</td><td><span style="font-family: arial,helvetica,sans-serif; font-size: small;">List of domain TLDs which are available to the reseller.</span></td></tr></tbody></table>

<span style="font-family: arial,helvetica,sans-serif; font-size: small;"> To be able to use the entire API, you must have a reseller account with Joker.com (and use this account to log in). </span>

<span style="font-family: arial,helvetica,sans-serif; font-size: small;"> </span><span style="font-family: arial,helvetica,sans-serif; font-size: small;">**Example:**</span>

`<span style="font-size: small; font-family: courier new,courier;">  https://dmapi.joker.com/request/login?username=johndoe&password=mypass</span>`

### 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

<span style="font-family: arial,helvetica,sans-serif; font-size: small;">**Returns: Nothing** </span>

<span style="font-family: arial,helvetica,sans-serif; font-size: small;">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).</span>

## result-list

<span style="font-family: arial,helvetica,sans-serif; font-size: small;">**Accepts:** </span>

<table border="0" id="bkmrk-pending%C2%A0%C2%A0%C2%A0%C2%A0%C2%A0-get-res" style="width: 643px; height: 271px;"><tbody><tr><td>*pending* </td><td>get results of requests still in progress

</td></tr><tr><td>*showall*</td><td>get all results incl. deletes using result-delete</td></tr><tr><td>*period*</td><td>get results for specifed period of days (default: 90)

</td></tr><tr><td>*date*</td><td>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</td></tr><tr><td>*offset*</td><td>start dispalying results from specified position

</td></tr><tr><td>*limit*</td><td>only get number of results specified by limit</td></tr><tr><td>*status*</td><td>get results having specified status (ack/nack/?)

</td></tr><tr><td>*count-only* </td><td>when set to 1, only count number of records and return single line in format "Records: N"

</td></tr><tr><th colspan="2">All following filters may use patterns ("\*" and "?")

</th></tr><tr><td>*rtype*

</td><td>get results for requests of specified type (domain-register/etc)</td></tr><tr><td>*objid*</td><td>get results for specified object ids (domain names, contacts, hosts)

</td></tr><tr><td>*procid*</td><td>get results for specified proc-id</td></tr><tr><td>*svtrid*</td><td>get results for specifued SvTrId</td></tr><tr><td>*cltrid*</td><td>get results for specified ClTrId</td></tr></tbody></table>

<span style="font-family: arial,helvetica,sans-serif; font-size: small;"> </span><span style="font-family: arial,helvetica,sans-serif; font-size: small;">**Returns:**</span>

List of answers from joker.com (one per line):<span style="font-family: arial,helvetica,sans-serif; font-size: small;">  
</span>

```
TimeStamp SvTrId Proc-ID request-type status ClTrId
```

<span style="font-family: arial,helvetica,sans-serif; font-size: small;">**Where:**</span>

```
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
```

<span style="font-family: arial,helvetica,sans-serif; font-size: small;"> </span>**Example:**

```
https://dmapi.joker.com/request/result-list
```

## result-retrieve

<span style="font-family: arial,helvetica,sans-serif; font-size: small;">**Accepts:**</span>

<table border="1" id="bkmrk-proc-id-one-of-these" style="width: 80%;"><tbody><tr><td>*<span style="font-family: arial,helvetica,sans-serif; font-size: small;">Proc-ID</span>*</td><td rowspan="2"><span style="font-family: arial,helvetica,sans-serif; font-size: small;">One of these must be specified. If both are specified, SvTrId has precedence.</span></td></tr><tr><td>*<span style="font-family: arial,helvetica,sans-serif; font-size: small;">SvTrID</span>*</td></tr></tbody></table>

<span style="font-family: arial,helvetica,sans-serif; font-size: small;">**Returns:**</span>

<table border="1" id="bkmrk-answer-%28processing-r" style="width: 80%;"><tbody><tr><td><span style="font-family: arial,helvetica,sans-serif; font-size: small;">Answer (processing result) associated with specified Tracking/Processing ID. </span>

<span style="font-family: arial,helvetica,sans-serif; font-size: small;">If detailed information (content) is not available, only status will be returned</span>

</td></tr></tbody></table>

<span style="font-family: arial,helvetica,sans-serif; font-size: small;">**Please note:** </span>

<span style="font-family: arial,helvetica,sans-serif; font-size: small;">Since there is no requirement of uniqueness for user-specified transaction ids, it is not possible to use them to retrieve specific results. </span>

<span style="font-family: arial,helvetica,sans-serif; font-size: small;">**Example:**</span>

`<span style="font-size: small; font-family: courier new,courier;">  https://dmapi.joker.com/request/result-retrieve?proc-id=8181810&auth-sid=<your-current-session-id></span>`

## result-delete<span style="font-family: arial,helvetica,sans-serif; font-size: small;">   
</span>

<span style="font-family: arial,helvetica,sans-serif; font-size: small;">**Accepts:**</span>

<table border="1" id="bkmrk-proc-id-one-of-these-1" style="width: 80%;"><tbody><tr><td>*<span style="font-family: arial,helvetica,sans-serif; font-size: small;">Proc-ID</span>*

</td><td rowspan="2"><span style="font-family: arial,helvetica,sans-serif; font-size: small;">One of these must be specified. If both are specified, SvTrId has precedence</span>

</td></tr><tr><td>*<span style="font-family: arial,helvetica,sans-serif; font-size: small;">SvTrID</span>*

</td></tr></tbody></table>

<span style="font-family: arial,helvetica,sans-serif; font-size: small;">**Returns:**</span>

<span style="font-family: arial,helvetica,sans-serif; font-size: small;"> 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*.</span>

## query-profile <span style="font-family: arial,helvetica,sans-serif; font-size: small;">  
</span>

<span style="font-family: arial,helvetica,sans-serif; font-size: small;">**Returns:**</span>

<span style="font-family: arial,helvetica,sans-serif; font-size: small;"> Returns reseller profile data in format "key: value". May be used to query account balance</span>

<span style="font-family: arial,helvetica,sans-serif; font-size: small;"> </span>Example:

```
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:

<table border="1" id="bkmrk-available-amount-ava" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 16.4692%;"></col><col style="width: 83.6297%;"></col></colgroup><tbody><tr><td>available  
</td><td>amount available for orders

</td></tr><tr><td>pending  
</td><td>amount reserved for pending operations (renewals, transfers etc)  
</td></tr><tr><td>total  
</td><td>the sum of available and pending, i.e. the effective balance  
</td></tr><tr><td>currency  
</td><td>currency of your account</td></tr></tbody></table>

## query-order-list

##### Parameters

<table border="1" id="bkmrk-show-all-show-all-or" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 18.6191%;"></col><col style="width: 81.4762%;"></col></colgroup><tbody><tr><td>show-all</td><td>Show all orders including those which did not incur any charges.</td></tr><tr><td>after</td><td>Show only orders after specified date (inclusive). Date must be in ISO format: YYYY-MM-DD

</td></tr><tr><td>before</td><td>Show only orders before specified data (inclusive).

<p class="callout info">If neither "after" or "before" is specified, the default is a list of orders within last 30 days.</p>

</td></tr><tr><td>type</td><td>Show only orders of specified type. Types are:

<table border="1" style="border-collapse: collapse; width: 100.169%; height: 296px;"><colgroup><col style="width: 18.1627%;"></col><col style="width: 81.7059%;"></col></colgroup><tbody><tr style="height: 29.6px;"><td style="height: 29.6px;">create</td><td style="height: 29.6px;">create domain</td></tr><tr style="height: 29.6px;"><td style="height: 29.6px;">renew</td><td style="height: 29.6px;">renew domain</td></tr><tr style="height: 29.6px;"><td style="height: 29.6px;">transfer</td><td style="height: 29.6px;">transfer domain</td></tr><tr><td>restore</td><td>restore domain from RGP</td></tr><tr style="height: 29.6px;"><td style="height: 29.6px;">delete\_domain</td><td style="height: 29.6px;">delete domain</td></tr><tr><td>cor</td><td>COR (Change Of Registrant aka Domain Owner Change)</td></tr><tr style="height: 29.6px;"><td style="height: 29.6px;">create-contact</td><td style="height: 29.6px;">create contact</td></tr><tr style="height: 29.6px;"><td style="height: 29.6px;">autons</td><td style="height: 29.6px;">modify DNS zone</td></tr><tr style="height: 29.6px;"><td style="height: 29.6px;">lock</td><td style="height: 29.6px;">lock domain</td></tr><tr style="height: 29.6px;"><td style="height: 29.6px;">unlock</td><td style="height: 29.6px;">unlock domain</td></tr><tr style="height: 29.6px;"><td style="height: 29.6px;">privacy\_pp1</td><td style="height: 29.6px;">Privacy Basic</td></tr><tr style="height: 29.6px;"><td style="height: 29.6px;">privacy\_pp2</td><td style="height: 29.6px;">Privacy Pro</td></tr><tr><td>credit-increase</td><td>account top-up</td></tr><tr><td>payment\_fee</td><td>payment fee, amount deducted from account top-up</td></tr></tbody></table>

</td></tr><tr><td>status</td><td>Show only orders with specified completion status.

Possible values are: ok, error, pending

</td></tr><tr><td>tld</td><td>Filter by TLD. By default all TLDs are included.</td></tr><tr><td>fqdn</td><td>Filter by FQDN (domain name). By default all domains (and other objects) are included.</td></tr><tr><td>fqdn-like  
</td><td>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.

</td></tr><tr><td>order-id  
</td><td>Only show order with specified id.  
</td></tr><tr><td>order-id-after  
</td><td>Show orders with ids greater or equal than specified.</td></tr><tr><td>order-id-before  
</td><td>Show orders with ids less or equal than than specified.</td></tr><tr><td>proc-id</td><td>Only show order with specified processing id.</td></tr><tr><td>proc-id-after  
</td><td>Show orders with processing ids greater or equal than specified.  
</td></tr><tr><td>proc-id-before  
</td><td>Show orders with processing ids less or equal than than specified.  
</td></tr><tr><td>limit  
</td><td>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.

</td></tr><tr><td>asc</td><td>If true, sort ascending - recent orders come last. The default is false - recent orders come first.</td></tr><tr><td>separator</td><td>Use specified separator in table output. Default is "tab". Possible values:

<table border="1" style="border-collapse: collapse; width: 62.2089%;"><colgroup><col style="width: 50.0376%;"></col><col style="width: 50.0376%;"></col></colgroup><tbody><tr><td>tab</td><td>\\t</td></tr><tr><td>comma</td><td>,</td></tr><tr><td>semicolon</td><td>;</td></tr><tr><td>pipe</td><td>|</td></tr></tbody></table>

  
</td></tr><tr><td>num-comma</td><td>If true, use comma (",") as decimal separator in numbers. Default is false, i.e. use dot (".")

<p class="callout info">Please note that "comma" separator cannot be used when "num-comma" is set to "true".</p>

</td></tr><tr><td>csv</td><td>If true, return result as a downloadable CSV file, without DMAPI headers.

</td></tr><tr><td>per-page</td><td>Number of rows returned per single request when using paging. Must be at least 10.

</td></tr><tr><td>page</td><td>Page number when `per_page` is set. Pages are numbered starting with 1.

</td></tr><tr><td>count-only</td><td>Only count number of rows that would be returned given specified parameters.

</td></tr></tbody></table>

##### 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

<table border="1" id="bkmrk-order_id-order-id-pr" style="border-collapse: collapse; width: 100%; height: 265.125px;"><colgroup><col style="width: 22.1826%;"></col><col style="width: 77.8969%;"></col></colgroup><tbody><tr style="height: 29.4583px;"><td style="height: 29.4583px;">order\_id</td><td style="height: 29.4583px;">Order ID</td></tr><tr style="height: 29.4583px;"><td style="height: 29.4583px;">proc\_id</td><td style="height: 29.4583px;">Processing ID</td></tr><tr style="height: 29.4583px;"><td style="height: 29.4583px;">created\_at</td><td style="height: 29.4583px;">Order creation time (UTC)</td></tr><tr style="height: 29.4583px;"><td style="height: 29.4583px;">status</td><td style="height: 29.4583px;">Order status: ok, error, pending</td></tr><tr style="height: 29.4583px;"><td style="height: 29.4583px;">type</td><td style="height: 29.4583px;">Order type</td></tr><tr style="height: 29.4583px;"><td style="height: 29.4583px;">amount\_brutto</td><td style="height: 29.4583px;">Amount charged including VAT. If VAT is not deducted then it has same value as amount\_netto.</td></tr><tr style="height: 29.4583px;"><td style="height: 29.4583px;">amount\_netto</td><td style="height: 29.4583px;">Amount charged excluding VAT.</td></tr><tr style="height: 29.4583px;"><td style="height: 29.4583px;">currency</td><td style="height: 29.4583px;">Currency if amount is non-zero; empty if amount is zero.</td></tr><tr style="height: 29.4583px;"><td style="height: 29.4583px;">identifier</td><td style="height: 29.4583px;">Domain or other object name that is affected by the order</td></tr></tbody></table>

<p class="callout info">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.</p>

<p class="callout info">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.</p>

<p class="callout info">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.  
</p>

<p class="callout info">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.</p>

<p class="callout warning">**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.  
</p>