NAV

Introduction

Welcome to the JotUrl API Version i1! This is the right place to find information on how to programmatically interact with the JotUrl interface.

Authentication

Session token

Step 1: acquiring a token

Example

  {PUBLIC_KEY} = "ae7b4635320411fe"

 {PRIVATE_KEY} = "9283c835ef5e21d3"

{GMT_DATETIME} = "2018-11-30T20:04Z"

    {PASSWORD} = HMAC_SHA256({PRIVATE_KEY}, {PUBLIC_KEY} + ':' + {GMT_DATETIME}) =
               = HMAC_SHA256("9283c835ef5e21d3", "ae7b4635320411fe:2018-11-30T20:04Z") =
               = "e78a507e8e031a02c5c81a2eacb5bd6c1f846a99af7c5d0f339f006dc44384aa"

Request

https://joturl.com/a/i1/users/login?username=test@example.com&password=e78a507e8e031a02c5c81a2eacb5bd6c1f846a99af7c5d0f339f006dc44384aa

The above request returns a JSON structured like this:

{
    "status": {
        "code": 200,
        "text": "OK",
        "error": "",
        "rate": 0
    },
    "result": {
        "session_id": "93bed02bf74e191294e22da6272a18a8",
        "datetime": "2018-11-30T20:04Z"
    }
}

Session authentication needs the generation of a session token session_id that is used to sign all other request to the API endpoints.

To generate the session_id you have to make a request (GET or POST) to the API endpoint:

https://joturl.com/a/i1/users/login?username={EMAIL}&password={PASSWORD}

where {EMAIL} is the email you use to login the JotUrl dashaboard and {PASSWORD} is obtained by using an HMAC_SHA256 hash function:

{PASSWORD} = HMAC_SHA256({PRIVATE_KEY}, {PUBLIC_KEY} + ':' + {GMT_DATETIME})

{PUBLIC_KEY} and {PRIVATE_KEY} are your public and private API keys, respectively (API Keys).

Parameter {GMT_DATETIME} is the the GMT date/time in the format YYYY-MM-ddThh:mmZ where:

Parameter {GMT_DATETIME} must be generated on a device as synchronized as possible with the GMT date/time (each request requires a new {GMT_DATETIME}).

Step 2: sign API calls

Example

_sid = {session_id} =
     = "93bed02bf74e191294e22da6272a18a8"

  _h = HMAC_SHA256({PRIVATE_KEY}, {session_id} + ':' + {GMT_DATETIME}) =
     = HMAC_SHA256("9283c835ef5e21d3", "93bed02bf74e191294e22da6272a18a8:2018-11-30T20:04Z") =
     = "c9afd295a66bdfd68b2ee5a6c1031ff343d17691d56af17504127cf22d5a9d5b"

Request

https://joturl.com/a/i1/users/info?_sid=93bed02bf74e191294e22da6272a18a8&_h=c9afd295a66bdfd68b2ee5a6c1031ff343d17691d56af17504127cf22d5a9d5b

Response 

{
    "status": {
        "code": 500,
        "text": "INVALID session",
        "error": "",
        "rate": 0
    },
    "result": []
}

Every request to API endpoints have to be signed with the parameters _sid and _h. Where _sid is the session token {session_id} obtained in step 1 and _h is generated with the same method used for the {PASSWORD} parameter in step 1:

_h = HMAC_SHA256({PRIVATE_KEY}, {session_id} + ':' + {GMT_DATETIME})

Parameter {GMT_DATETIME} is obtained in the same way and follows the same rules as in step 1.

The session token

The session token session_id expires approximately every 30 days, but may expire sooner due to various factors and if you call the API method users/logout.

As a best practice, we suggest you to continue to use it until you get an "INVALID session" error response from the API endpoint. In this case, you have to restart the authentication procedure from the beginning.

Examples

The examples in this section return the expected values for the HMAC_SHA256 hash, these values can be used to test the implementation of the HMAC_SHA256 hash you are using. You can find SDKs and examples here.

PHP

PHP example.

<?php

function HMAC_SHA256( $private_key, $message, $time = null ) {
    return hash_hmac(
        'sha256',
        $message . ':' . ( $time ?: gmdate( "Y-m-d\TH:i\Z", time() ) ), 
        $private_key 
    );
}

$public_key = "ae7b4635320411fe";
$private_key = "9283c835ef5e21d3";
$gmt_datetime = "2018-11-30T20:04Z";

// e78a507e8e031a02c5c81a2eacb5bd6c1f846a99af7c5d0f339f006dc44384aa
echo HMAC_SHA256( $private_key, $public_key, $gmt_datetime );

Python

Python example.

# coding: utf8
import sys
import hmac
import hashlib

try:
    def HMAC_SHA256(private_key="", message="", time=""):
        message += ":"

        if time:
            message += str(time)
        else:
            message += str(datetime.datetime.utcnow().strftime('%Y-%m-%dT%H:%MZ'))

        return hmac.new(str.encode(private_key), str.encode(message), hashlib.sha256).hexdigest()

    public_key = "ae7b4635320411fe"
    private_key = "9283c835ef5e21d3"
    gmt_datetime = "2018-11-30T20:04Z"

    # e78a507e8e031a02c5c81a2eacb5bd6c1f846a99af7c5d0f339f006dc44384aa
    print(HMAC_SHA256(private_key, public_key, gmt_datetime))

except Exception as t:
    print(t)
    sys.exit(0)
# end try

NodeJS

NodeJS example.

const crypto = require('crypto');

try {
    function gmdate() {
        var iso = (new Date()).toISOString();

        return iso.substr(0, iso.length - 8) + 'Z';
    }

    function create_sha256(key, message) {
        var hmac = crypto.createHmac('sha256', key);
        hmac.update(message);

        return hmac.digest('hex');
    }

    function HMAC_SHA256(private_key, message, time) {
        var msg = message + ":" + (time ? time : gmdate());

        return create_sha256(private_key, msg);
    }

    var public_key = "ae7b4635320411fe";
    var private_key = "9283c835ef5e21d3";
    var gmt_datetime = "2018-11-30T20:04Z";

    // e78a507e8e031a02c5c81a2eacb5bd6c1f846a99af7c5d0f339f006dc44384aa
    console.log(HMAC_SHA256(private_key, public_key, gmt_datetime));

} catch (e) {
    console.log(e.message);
}

Java

Java example.

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.security.NoSuchAlgorithmException;
import java.security.InvalidKeyException;
import java.text.SimpleDateFormat;
import java.util.Locale;
import java.util.Date;
import java.util.TimeZone;

public class HMAC_SHA256_EXAMPLE {

  public static String gmdate() {
    String pattern = "yyy-MM-dd'T'HH:mm'Z'";
    SimpleDateFormat simpleDateFormat = new SimpleDateFormat(pattern);
    simpleDateFormat.setTimeZone(TimeZone.getTimeZone("UTC"));

    return simpleDateFormat.format(new Date());
  }

  public static String hex(byte[] bytes) {
    StringBuilder result = new StringBuilder();
    for (byte aByte: bytes) {
      result.append(String.format("%02x", aByte));
    }

    return result.toString();
  }

  public static String HMAC_SHA256(String private_key, String message, String date_time)
        throws NoSuchAlgorithmException, InvalidKeyException {
    Mac sha256_HMAC = Mac.getInstanceNumber("HmacSHA256");
    SecretKeySpec secret_key = new SecretKeySpec(private_key.getBytes(), "HmacSHA256");
    sha256_HMAC.initClient(secret_key);

    return hex(sha256_HMAC.doFinal((message + ":" + date_time).getBytes()));
  }

  public static String HMAC_SHA256(String private_key, String message)
        throws NoSuchAlgorithmException, InvalidKeyException {
    return HMAC_SHA256(private_key, message, gmdate());
  }

  public static void main(String[] args) {
    try {
      String public_key = "ae7b4635320411fe";
      String private_key = "9283c835ef5e21d3";
      String date_time = "2018-11-30T20:04Z";

      // e78a507e8e031a02c5c81a2eacb5bd6c1f846a99af7c5d0f339f006dc44384aa
      System.out.println(HMAC_SHA256(private_key, public_key, date_time));
    }
    catch(Exception e) {
      System.out.println("Error");
    }
  }
}

C#

C# example.

using System;
using System.Security.Cryptography;
using System.Text;

namespace HMAC_SHA256_EXAMPLE
{
    class Program
    {
        public static string gmdate()
        {
            return DateTime.UtcNow.ToString("yyyy-MM-ddTHH:mmZ");
        }

        public static string hex(byte[] ba)
        {
            StringBuilder hex = new StringBuilder(ba.Length * 2);

            foreach (byte b in ba)
            {
                hex.AppendFormat("{0:x2}", b);
            }

            return hex.ToString();
        }

        private static string HMAC_SHA256(string private_key, string message, string time = "")
        {
            var hash = new HMACSHA256(Encoding.ASCII.GetBytes(private_key));

            return hex(hash.ComputeHash(Encoding.ASCII.GetBytes(message + ":" + (time ?? gmdate()))));
        }

        static void Main(string[] args)
        {
            var public_key = "ae7b4635320411fe";
            var private_key = "9283c835ef5e21d3";
            var gmt_datetime = "2018-11-30T20:04Z";

            // e78a507e8e031a02c5c81a2eacb5bd6c1f846a99af7c5d0f339f006dc44384aa
            Console.WriteLine(HMAC_SHA256(private_key, public_key, gmt_datetime));
        }
    }
}

Flutter (Dart)

Flutter (Dart) example.

import 'dart:convert';
import 'package:crypto/crypto.dart';

void main() {
  String public_key = 'ae7b4635320411fe';
  String private_key = '9283c835ef5e21d3';
  String gmt_datetime = '2018-11-30T20:04Z';

  // e78a507e8e031a02c5c81a2eacb5bd6c1f846a99af7c5d0f339f006dc44384aa
  print(HMAC_SHA256(private_key, public_key, gmt_datetime));
}

String gmdate() {
  String iso = DateTime.now().toUtc().toIso8601String();

  return iso.substring(0, 16) + 'Z';
}

String create_sha256(String key, String message) {
  var hmacSha256 = new Hmac(sha256, utf8.encode(key));
  var digest = hmacSha256.convert(utf8.encode(message));

  return digest.toString();
}

String HMAC_SHA256(String private_key, String message, [String time = '']) {
  String msg = message + ":" + (!time.isEmpty ? time : gmdate());

  return create_sha256(private_key, msg);
}

Token authentication

Token authentication (also called bearer authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens.

Step 1: acquiring a token

Request

https://joturl.com/a/i1/apis/tokens

The above request returns a JSON structured like this:

{
    "status": {
        "code": 200,
        "text": "OK",
        "error": "",
        "rate": 0
    },
    "result": {
        "read_write_token": "tok_RWxtd74zqlcv18d6qiau75kr1bwpagqbq5",
        "read_only_token": "tok_RO064cmpvzcsxc5ufg0xzx58ms3q15bn10"
    }
}

API tokens authentication needs a read-only or read/write token that is used to sign all other request to the API endpoints. API tokens do not expire and can be reset using the endpoint apis/tokens.

To get API tokens you have to make a request (GET or POST) to the endpoint:

https://joturl.com/a/i1/users/tokens

you must already be logged in using the session token.

Step 2: sign API calls

Every request to API endpoints have to be signed with the Authorization HTTP header:

Authorization: Bearer {token}

where {token} is one of the API tokens obtained in step 1.

With the read-only token you can only call endpoints with access [read].

You can find the required access of each endpoint immediately below the endpoint itself in this documentation.

Input requests

Example

https://joturl.com/a/i1/urls/shorten?long_url=https%3A%2F%2Fwww.joturl.com%2F&alias=jot

Parameters to each JotUrl API can be passed both with the GET and POST methods.

Output formats

Query

format=json

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 87
  },
  "result": {DATA}
}

Query

format=jsonp&callback=clbfunc

Response

clbfunc({
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 87
  },
  "result": {DATA}
})

Query

format=jsonp

Response

{
  "status": {
    "code": 500,
    "text": "MISSING callback",
    "error": "",
    "rate": 21
  },
  "result": []
}

Query

format=xml

Response

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <code>200</code>  
    <text>OK</text>  
    <error></error>  
    <rate>87</rate>  
  </status>  
  <result>{DATA}</result>  
</response>

Query

format=txt

Response

status_code=200
status_text=OK
status_error=
status_rate=87
result={DATA}

Query

format=plain

Response

{DATA}

The JotUrl API supports Cross Origin Resource Sharing (CORS) requests from any domain.

All JotUrl APIs support five return formats: json, jsonp, xml, txt, plain. Note that the formats txt and plain may return only limited information.

The default output format is format = json that is also used when the parameter format is invalid (e.g., format = jsonp but no callback parameter is specified).

Rate limits

If the rate limits are exceeded, the call fails and returns a 403 status code, with a LIMIT EXCEEDED status text (see Output formats for details).

Typical response 

{
    "status": {
        "code": <STATUS CODE>,
        "text": "<STATUS TEXT>",
        "error": "<STATUS ERROR>",
        "rate": <REQUESTS PER SECOND>
    },
    "result": <DATA>
}

If you send requests too quickly, make sure that the rate parameter in the status response is below the rate limits set for your account. The rate parameter is always expressed in requests per second. If you exceed the limits set for your account, our engine may block your requests for a time directly proportional to the speed with which you are sending the requests: the greater the gap with your rate limits, the greater the blocking time. Finally, if you do not fall within your rate limits for a long time, our engine could permanently block any further requests.

QR-Codes

A QR-Code is provided for each shorten URL. To generate it append .qrcode or .qr to the end of any shortened link. For example: http://jo.my/jotvideo.qrcode, http://jo.my/jotvideo.qr

Errors

For each request the status code is equal to the HTTP response status that can be:

code text error explanation
200 OK successful request
403 LIMIT EXCEEDED details on the error if available rate limit exceeded
404 NOT FOUND details on the error if available the query is well-formed but there is no available response
405 METHOD NOT ALLOWED details on the error if available the endpoint is not available to the calling user
414 Request-URI Too Large details on the error if available GET request contains long query information, use a POST request instead
500 INVALID [PARAMETER] details on the error if available invalid parameter [PARAMETER] in the request
INVALID METHOD [METHOD] details on the error if available invalid method [METHOD]
MISSING [ARGUMENT] details on the error if available the required argument [ARGUMENT] is missing in the request
503 GENERIC ERROR details on the error if available a generic error occurred and/or the service is temporarily unavailable 1

1 A GENERIC ERROR (503) is also issued in all those cases where a parameter has passed all validation checks, but for some reason our engine cannot use it to complete the request. For example, if you try to create a tracking link with the alias $alias you will see the error INVALID alias (500), since the alias $alias contains the forbidden character $, but if you try to create a tracking link with the alias alias and it is already have been used, you will see the error GENERIC ERROR (503) and the error field of the output status will be "The chosen alias is not available".

Parameters types

API endpoints require some parameters to be sent as part of the request. Most parameters are simple strings, but some endpoints require other types to be provided.

type description example
string sequence of alphanumeric text or other symbols hamburger
id variable length string obtained as a result of an API call 62613864764b3762725a343966673d3d
array comma separated list of type string, a maximum of 100 items are allowed hamburger, test
array_of_ids comma separated list of type id, a maximum of 100 items are allowed 62613864764b375a343966673d3d, 86590152f1891e680, 5952b26623c9b47ad9e
integer integer 12
float float with . (point) as a decimal separator 12.34
boolean boolean parameter, accepted values are true, false, on, off, 1, 0 1
date date in the format yyyy-mm-dd (UTC) 2019-06-04
datetime date/time in the format yyyy-mm-dd hh:mm:ss (UTC) 2019-06-04 19:21:34
json stringified JSON object or associative array {"test":"check"}, param[test]=check
enum is a string with a value chosen from a list of allowed values remarketing

JotUrl SDKs

JotUrl SDKs help you develop apps, websites and plugins that relies on all the functionality of our APIs. We currently support PHP, Python, Java and NodeJS, but you can easily integrate our APIs with all development technologies.

PHP SDK

Click here to download the SDK for PHP with an example included.

PHP example

<?php

// replace [your login] with the email you use to login into JotUrl
define( 'SDK_USER_NAME', '[your login]' );
// replace [public key] with your public key: https://www.joturl.com/reserved/settings.html#tools-api
define( 'SDK_PUBLIC_API_KEY', '[public key]' );
// replace [private key] with your private key: https://www.joturl.com/reserved/settings.html#tools-api
define( 'SDK_PRIVATE_API_KEY', '[private key]' );

require_once 'sdk/JotUrlSDK.php';

try {
    // create an instance of JotUrlSDK
    $joturl = new JotUrlSDK( SDK_USER_NAME, SDK_PUBLIC_API_KEY, SDK_PRIVATE_API_KEY );

    $joturl->wrapper( function ( $sdk ) {
        // get logged user information
        $url = $sdk->buildURL( 'users/info' );
        echo "Getting user info" . PHP_EOL;
        $result = $sdk->call( $url );
        echo "====== USER INFO ======" . PHP_EOL;
        print_r( $result );
    } );

    $joturl->wrapper( function ( $sdk ) {
        // get first 5 projects
        $url = $sdk->buildURL( 'projects/list', array( "fields" => "id,name", "length" => 5 ) );
        echo "Getting first 5 projects (if available)" . PHP_EOL;
        $result = $sdk->call( $url );
        echo "====== PROJECTS ======" . PHP_EOL;
        print_r( $result );
    } );
} catch ( Throwable $t ) {
    die( $t->getMessage() );
}

Documentation

<?php

/**
 * Creates an instance of the JotUrl SDK.
 *
 * @param string $username    the username used to login into JotURL dashboard
 * @param string $public_key  public api key, you can find it on https://www.joturl.com/reserved/settings.html#tools-api
 * @param string $private_key private api key, you can find it on https://www.joturl.com/reserved/settings.html#tools-api
 */
new JotUrlSDK( $username, $public_key, $private_key );

/**
 * Automatically try to access the JotURL API, the callback is called if the access is successful.
 *
 * @param mixed $callback callback to be called on success
 *
 * @return mixed value returned by the $callback function, an exception is thrown on error
 */
function wrapper( $callback );

/**
 * Given an endpoint and parameters (optional) returns the URL to be called.
 *
 * @param string $endpoint   endpoint to be called
 * @param array  $parameters associative array [param => value]
 *
 * @return string the URL to be called
 */
function buildURL( $endpoint, $parameters = array() );

/**
 * Call and get results from the API endpoint.
 *
 * @param string $url            URL to be called
 * @param array  $postParameters [OPTIONAL] array containing post parameters
 *
 * @return bool|array associative array containing the result of the call
 */
function call( $url, $postParameters = array() );

Python SDK

Click here to download the SDK for Python 3+ with an example included.

Python example

# coding: utf8
import sys
from sdk.JotUrlSDK import JotUrlSDK

# replace [your login] with the email you use to login into JotUrl
SDK_USER_NAME = "[your login]"
# replace [public key] with your public key: https://www.joturl.com/reserved/settings.html#tools-api
SDK_PUBLIC_API_KEY = "[public key]"
# replace [private key] with your private key: https://www.joturl.com/reserved/settings.html#tools-api
SDK_PRIVATE_API_KEY = "[private key]"

try:
    # create an instance of JotUrlSDK
    joturl = JotUrlSDK(SDK_USER_NAME, SDK_PUBLIC_API_KEY, SDK_PRIVATE_API_KEY)

    def getUserInfo(sdk):
        # get logged user information
        url = sdk.buildURL("users/info")
        print("Getting user info")
        result = sdk.call(url)
        print("====== USER INFO ======")
        print(result)


    joturl.wrapper(getUserInfo)


    def getProjectsList(sdk):
        # get first 5 projects
        url = sdk.buildURL("projects/list", {"fields": "id,name", "length": 5})
        print("Getting first 5 projects (if available)")
        result = sdk.call(url)
        print("====== PROJECTS ======")
        print(result)


    joturl.wrapper(getProjectsList)


    def getProjectsListWithPOSTRequest(sdk):
        # get first 5 projects
        url = sdk.buildURL("projects/list")
        print("Getting first 5 projects (if available) with a POST request")
        result = sdk.call(url, {"fields": "id,name", "length": 5})
        print("====== PROJECTS ======")
        print(result)


    joturl.wrapper(getProjectsListWithPOSTRequest)
except Exception as t:
    print(t)
    sys.exit(0)
# end try

Documentation

""" 
Creates an instance of the JotUrl SDK.

@param username    the username used to login into JotURL dashboard
@param public_key  public api key, you can find it on https://www.joturl.com/reserved/settings.html#tools-api
@param private_key private api key, you can find it on https://www.joturl.com/reserved/settings.html#tools-api
"""
def __init__(self, username="", public_key="", private_key=""):

"""
Automatically try to access the JotURL API, the callback is called if the access is successful.

@param callback callback to be called on success

returns True on success, raises an exception on error
"""
def wrapper(self, callback=None):

"""
Given an endpoint and parameters (optional) returns the URL to be called.

@param endpoint   endpoint to be called
@param parameters associative array [param => value]

returns the URL to be called
"""
def buildURL(self, endpoint="", parameters={}):

"""
Call and get results from the API endpoint.

@param url            URL to be called
@param postParameters [OPTIONAL] array containing post parameters

returns bool|array JSON containing the result of the call, false on failure, raises an exception on error 
"""
def call(self, url="", postParameters={}):

NodeJS SDK

Click here to download the SDK for NodeJS with an example included.

NodeJS example

// replace [your login] with the email you use to login into JotUrl
const SDK_USER_NAME = '[your login]';

// replace [public key] with your public key: https://www.joturl.com/reserved/settings.html#tools-api
const SDK_PUBLIC_API_KEY = '[public key]';

// replace [private key] with your private key: https://www.joturl.com/reserved/settings.html#tools-api
const SDK_PRIVATE_API_KEY = '[private key]';

try {
    // create an instance of JotUrlSDK
    let joturl = require('./sdk/JotUrlSDK.js')(SDK_USER_NAME, SDK_PUBLIC_API_KEY, SDK_PRIVATE_API_KEY);

    // get logged user information
    console.log("Getting user info");
    joturl.call('users/info').then(result => {
        console.log(result);

        /* get first 5 projects */
        console.log("Getting first 5 projects (if available)");
        joturl.call('projects/list', {"fields": "id,name", "length": 5}).then(result => {
            console.log(result);
        }).catch(e => {
            console.log(e.message);
        });
    }).catch(e => {
        console.log(e.message);
    });
} catch (e) {
    console.log(e.message);
}

Documentation

/**
 * Creates an instance of the JotUrl SDK.
 *
 * @param _username the username used to login into JotURL dashboard
 * @param _public_key public api key, you can find it on https://www.joturl.com/reserved/settings.html#tools-api
 * @param _private_key private api key, you can find it on https://www.joturl.com/reserved/settings.html#tools-api
 * @param base_url the base URL to be use to call API endpoints, defaults to https://joturl.com/a/i1/
 *
 * @returns {JotUrlSDK}
 */
require('JotUrlSDK')(_username, _public_key, _private_key, base_url);

/**
 * Call and get results from the API endpoint.
 *
 * @param endpoint API endpoint to be called
 * @param parameters [OPTIONAL] parameters to be passed to the call
 * @param postParameters [OPTIONAL] post parameters to be passed to the call
 *
 * @returns {Promise}
 */
function call(endpoint, parameters = {}, postParameters = {});

Java SDK

Click here to download the SDK for Java with an example included.

Java example

import joturlsdk.JotUrlRunnable;
import joturlsdk.JotUrlSDK;

public class JotUrlExample {

    public static void main(String[] args) {
        try {
            JotUrlSDK sdk = new JotUrlSDK("[username]", "[public_key]", "[private_key]");

            sdk.call("users/info", new JotUrlRunnable() {
                public void run() {
                    System.out.println(this.result);
                }
            });
        } catch (Exception e) {
            System.out.println("Error: " + e.getMessage());
        }
    }
}

Documentation

/**
 * Creates an instance of the JotUrl SDK.
 *
 * @param _username the username used to login into JotURL dashboard
 * @param _public_key public api key, you can find it on https://www.joturl.com/reserved/settings.html#tools-api
 * @param _private_key private api key, you can find it on https://www.joturl.com/reserved/settings.html#tools-api
 *
 * @returns {JotUrlSDK}
 */
JotUrlSDK sdk = new JotUrlSDK(_username, _public_key, _private_key);

/**
 * Call and get results from the API endpoint.
 *
 * @param endpoint API endpoint to be called
 * @param parameters parameters to be passed to the call (null to ignore)
 * @param postParameters post parametersto be passed to the call (null to ignore)
 *
 */
JotUrlSDK.call(String endpoint, JotUrlRunnable callback, Map<String, String> parameters, Map<String, String> postParameters);
JotUrlSDK.call(String endpoint, JotUrlRunnable callback);
JotUrlSDK.callGET(String endpoint, Map<String, String> parameters, JotUrlRunnable callback);
JotUrlSDK.callPOST(String endpoint, Map<String, String> postParameters, JotUrlRunnable callback);

Flutter SDK

Click here to download the SDK for Flutter with an example included.

Dart example

import 'package:joturlsdk/joturlsdk.dart';

void main() async {
  final String username = '[username]';
  final String public_key = '[public_key]';
  final String private_key = '[private_key]';

  try {
    JotUrlSDK sdk = new JotUrlSDK(username, public_key, private_key);

    dynamic result = await sdk.call("users/info");

    print('result: ' + result.toString());
  } catch (e) {
    print("Error: " + e.toString());
  }
}

Documentation

/**
 * Creates an instance of the JotUrl SDK.
 *
 * @param _username the username used to login into JotURL dashboard
 * @param _public_key public api key, you can find it on https://www.joturl.com/reserved/settings.html#tools-api
 * @param _private_key private api key, you can find it on https://www.joturl.com/reserved/settings.html#tools-api
 * @param base_url the base URL to be use to call API endpoints, defaults to https://joturl.com/a/i1/
 *
 * @returns JotUrlSDK
 * @constructor
 */
JotUrlSDK sdk = new JotUrlSDK(_username, _public_key, _private_key);

/**
 * Call and get results from the API endpoint.
 *
 * @param endpoint API endpoint to be called
 * @param getParameters query parameters to be passed to the call (null to ignore)
 * @param postParameters post parametersto be passed to the call (null to ignore)
 *
 */
sdk.call(endpoint, {Map<String, dynamic> getParameters = null, Map<String, dynamic> postParameters = null});

API reference

/decode

access: [READ]

This method converts API error codes into a friendly text message (in the current user language).

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/decode?code=10

Query parameters

code = 10

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "message": "An error occurred while deleting the QR codes of a URL"
  }
}
Required parameters
parameter description
codeSTRING numeric code representing the error message
Return values
parameter description
lang language in which the message is
message decoded text message

/timestamp

access: [READ]

This method returns the current server timestamp (UTC) with microseconds as float.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/timestamp

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "timestamp": 1699710773.373
  }
}
Return values
parameter description
timestamp the current Unix timestamp with microseconds

/translate

access: [READ]

This method translates an error codes into a friendly text message.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/translate?code=sample_message&lang=en

Query parameters

code = sample_message
lang = en

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "text": "This is a sample error message",
    "lang": "en"
  }
}
Required parameters
parameter description
codeSTRING string code representing the error message
Optional parameters
parameter description
langSTRING language in which you want to translate the message
Return values
parameter description
lang language in which the message is
text text message corresponding to code

/apis

/apis/accepted

access: [WRITE]

This method returns the actual result from an accepted (202) API endpoint.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)Example 5 (json)Example 6 (xml)Example 7 (txt)Example 8 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/apis/accepted

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": []
}
Optional parameters
parameter description
_accepted_idID ID returned by the accepted (202) API endpoint
stop_taskBOOLEAN 1 to stop the background task, _accepted_id is mandatory if stop_task is 1
Return values
parameter description
_accepted_count [OPTIONAL] completed subtasks (e.g., the number of imported tracking links)
_accepted_dt [OPTIONAL] starting date/time of the task
_accepted_errors [OPTIONAL] total number of subtasks not completed correctly (e.g., the number of tracking links for which the import has failed)
_accepted_id [OPTIONAL] ID of the task started by the accepted (202) API endpoint
_accepted_key [OPTIONAL] key that uniquely identifies the accepted (202) API endpoint that started the task
_accepted_perc [OPTIONAL] percentage of completition of the task
_accepted_total [OPTIONAL] total number of subtasks (e.g., the total number of tracking links to be imported)
data [OPTIONAL] data returned at the end of the task from the accepted (202) API endpoint
stopped [OPTIONAL] 1 if the task has been stopped, 0 otherwise, returned only if stop_task is 1

/apis/has_access

access: [READ]

User permissions can remove access to this version of the API. This method returns 1 only if the user has access to this version of the API.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/apis/has_access

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "has_access": 0
  }
}
Return values
parameter description
has_access 1 if the user has access to this API version, 0 otherwise

/apis/keys

access: [WRITE]

This method returns the API keys associated to the logged in user.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)Example 5 (json)Example 6 (xml)Example 7 (txt)Example 8 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/apis/keys

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "public": "57200a3bc09c91dfb037a3c21fcaa8dd",
    "private": "1041ab3414ecc8c175a5dbcece085e54"
  }
}
Optional parameters
parameter description
passwordSTRING current account password, to be sent if reset = 1
resetBOOLEAN 1 to reset API keys, if this parameter is 1 the POST method is required (because the password is sent)
Return values
parameter description
private the user private API key
public the user public API key

/apis/lab

/apis/lab/add

access: [WRITE]

This method adds a new LAB script.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/apis/lab/add?name=test+script&script=LogManager.log%28%27script%27%29%3B

Query parameters

  name = test script
script = LogManager.log('script');

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "name": "test script",
    "script": "LogManager.log('script');",
    "id": "99fd73c4455f9d0a56b8631a18f16df7",
    "creation": "2023-11-11 13:52:51"
  }
}
Required parameters
parameter description
nameSTRING LAB script name
scriptHTML LAB script content
Return values
parameter description
creation creation date/time of the LAB script
id ID of the LAB script
name LAB script name (max length: 100000 bytes)

/apis/lab/count

access: [READ]

This method returns the number of LAB scripts.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)Example 5 (json)Example 6 (xml)Example 7 (txt)Example 8 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/apis/lab/count?search=a

Query parameters

search = a

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "count": 1
  }
}
Optional parameters
parameter description
searchSTRING filter LAB scripts by searching them
Return values
parameter description
count total number of LAB scripts, filtered by search: if passed

/apis/lab/delete

access: [WRITE]

This method deletes LAB scripts by using the parameter ids.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)Example 5 (json)Example 6 (xml)Example 7 (txt)Example 8 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/apis/lab/delete?ids=7f6ffaa6bb0b408017b62254211691b5,bff030594cd09ce531297feac0327b3f

Query parameters

ids = 7f6ffaa6bb0b408017b62254211691b5,bff030594cd09ce531297feac0327b3f

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "deleted": 2
  }
}
Required parameters
parameter description
idsARRAY_OF_IDS comma-separated list of LAB script IDs to be deleted, max number of IDs in the list: 100
Return values
parameter description
deleted number of deleted scripts

/apis/lab/edit

access: [WRITE]

This method edits a LAB script.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/apis/lab/edit?id=d571dc55934ef2427db8b08f3c02d41b&name=test+script

Query parameters

  id = d571dc55934ef2427db8b08f3c02d41b
name = test script

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "id": "d571dc55934ef2427db8b08f3c02d41b",
    "name": "test script",
    "updated": 1
  }
}
Required parameters
parameter description
idID ID of the LAB script to edit
Optional parameters
parameter description
nameSTRING LAB script name
scriptHTML content of the LAB script
Return values
parameter description
updated 1 on success, 0 otherwise

/apis/lab/info

access: [READ]

This method returns info about a LAB script.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/apis/lab/info

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": [
    {
      "id": "ef4bddc83d14018032cf099431440a07",
      "name": "script name 0",
      "creation": "2023-11-11 14:05:18",
      "script": "LogManager.log('script 0');"
    },
    {
      "id": "1e0ec2d21a463acc1c6151b8c78ccecb",
      "name": "script name 1",
      "creation": "2023-11-11 14:58:34",
      "script": "LogManager.log('script 1');"
    },
    {
      "id": "286204ba4f93e9f864868d96c5c2a703",
      "name": "script name 2",
      "creation": "2023-11-11 15:32:10",
      "script": "LogManager.log('script 2');"
    },
    {
      "id": "41ca30bc6e8b2847ed87d0822f356781",
      "name": "script name 3",
      "creation": "2023-11-11 17:40:52",
      "script": "LogManager.log('script 3');"
    },
    {
      "id": "f3af7c0347183ac0980aef578db287be",
      "name": "script name 4",
      "creation": "2023-11-11 19:34:36",
      "script": "LogManager.log('script 4');"
    }
  ]
}
Required parameters
parameter description
idID ID of the LAB script
Return values
parameter description
creation creation date/time of the LAB script
id ID of the LAB script
name name of the LAB script
script content of the LAB script

/apis/lab/list

access: [READ]

This method returns a list of available custom scripts for the current user.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/apis/lab/list

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": [
    {
      "id": "483bcae530b38bca6276190e077b5bf1",
      "name": "script name 0",
      "creation": "2023-11-11 14:52:20"
    },
    {
      "id": "b28552804102742acf7bf0dda421be83",
      "name": "script name 1",
      "creation": "2023-11-11 15:04:56"
    },
    {
      "id": "94b49bd1e891c68550e9b174517524f8",
      "name": "script name 2",
      "creation": "2023-11-11 16:32:28"
    },
    {
      "id": "b21997752e871864beadc0728895790b",
      "name": "script name 3",
      "creation": "2023-11-11 19:20:19"
    },
    {
      "id": "ca3ecf47ee0f12c2da0eedb4db96a0ef",
      "name": "script name 4",
      "creation": "2023-11-11 19:42:23"
    }
  ]
}
Optional parameters
parameter description
searchSTRING filters items to be extracted by searching them
Return values
parameter description
count total number of LAB scripts
data list of available/filtered LAB scripts for the current user

/apis/limits

access: [READ]

This method returns the API limits for the logged user.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/apis/limits

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "primary": {
      "limit": 500,
      "unit": "HOUR"
    },
    "secondary": {
      "limit": 50000,
      "unit": "DAY"
    }
  }
}
Return values
parameter description
primary object containing the primary rate limit: an integer limit and the unit in which the limit is expressed. unit is one of the following [MINUTE,HOUR,DAY,3_DAY]. 3_DAY is equivalent to 3 days
secondary object containing the secondary rate limit: an integer limit and the unit in which the limit is expressed. unit is one of the following [MINUTE,HOUR,DAY,3_DAY]. 3_DAY is equivalent to 3 days

/apis/list

access: [READ]

This method returns the list of available versions of the API.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/apis/list

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "count": 2,
    "data": [
      {
        "id": "v1",
        "name": "Version v1"
      },
      {
        "id": "i1",
        "name": "Version i1"
      }
    ]
  }
}
Optional parameters
parameter description
lengthINTEGER extracts this number of items (maxmimum allowed: 100)
orderbySTRING orders items by field
searchSTRING filters items to be extracted by searching them
sortSTRING sorts items in ascending (ASC) or descending (DESC) order
startINTEGER starts to extract items from this position
Return values
parameter description
count total number of versions
data array containing required information on API versions the user has access to

/apis/tokens

access: [WRITE]

This method returns the API tokens associated to the logged in user.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)Example 5 (json)Example 6 (xml)Example 7 (txt)Example 8 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/apis/tokens

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "read_write_token": "tok_RWce06c53e93ef1dc577277e95c1cd2d34",
    "read_only_token": "tok_ROc5a7bafba56cc4a3a0ab3b46ff146017"
  }
}
Optional parameters
parameter description
passwordSTRING current account password, to be sent if reset = 1
resetBOOLEAN 1 to reset the API tokens, if this parameter is 1 the POST method is required (because the password is sent)
Return values
parameter description
read_only_token the read-only API access token
read_write_token the read/write API access token

/cdns

/cdns/add

access: [WRITE]

This method allows to upload a resource to the CDN.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/cdns/add?type=image&info=%7B%22name%22%3A%22this+is+my+resource%22%7D

Query parameters

type = image
info = {"name":"this is my resource"}

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "id": "e49d5a6f04e3a3fa377b98b080f26503",
    "name": "this is my resource",
    "creation": "2023-11-11 13:52:51",
    "url": "https://cdn.endpoint/path/to/resource",
    "width": 533,
    "height": 400,
    "size": 20903,
    "mime_type": "image/png"
  }
}
Required parameters
parameter description
typeSTRING CDN type, see i1/cdns/property for details
Optional parameters
parameter description max length
external_urlURL URL to an external resource (not managed by the CDN), this URL must be with HTTPS 4000
infoJSON JSON containing additional info on the resource
inputSTRING name of the HTML form field that contains data for the resource, if not passed the default value input will be used (i.e., input = input)

NOTES: The parameter input contains the name of the field of the HTML form that is used to send resource data to this method. Form must have enctype = "multipart/form-data" and method = "post".

<form 
    action="/a/i1/cdns/add" 
    method="post" 
    enctype="multipart/form-data">

    <input name="input" value="resource_field" type="hidden"/>

    [other form fields]

    <input name="resource_field" type="file"/>    

</form>
Return values
parameter description
creation date/time when the CDN resource was created
height height in pixels of the CDN resource, if available
id ID of the CDN resource
mime_type MIME type of the resource, or 'external_url' for external URLs
name name of the CDN resource
size size in bytes of the CDN resource, if available
url URL of the CDN resource
width width in pixels of the CDN resource, if available

/cdns/count

access: [READ]

This method returns the number of resources on the CDN.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/cdns/count

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "count": 3
  }
}
Required parameters
parameter description
typeSTRING CDN resource type, for available types see i1/cdns/list
Optional parameters
parameter description
filtersJSON filters to be used to count media, for available filters see i1/cdns/list
searchSTRING filters CDN resources to be extracted by searching them
Return values
parameter description
count number of (filtered) CDN resources

/cdns/delete

access: [WRITE]

This method deletes a resource from the CDN.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/cdns/delete?id=50716886037245d427e34fa43ddaa439

Query parameters

id = 50716886037245d427e34fa43ddaa439

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "id": "50716886037245d427e34fa43ddaa439",
    "deleted": 1
  }
}
Required parameters
parameter description
idID ID of the CDN resource to delete
Optional parameters
parameter description
confirmBOOLEAN If 1 this method deletes the CDN resource even if it is linked to a tracking link
Return values
parameter description
deleted 1 if successful, otherwise a generic error message is issued
id echo back of the id input parameter

/cdns/edit

access: [WRITE]

This method allows to modify a CDN resource.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/cdns/edit?type=image&info=%7B%22name%22%3A%22this+is+my+resource%22%7D&id=6f47e2700b56e45deea91d95eeebdc84

Query parameters

type = image
info = {"name":"this is my resource"}
  id = 6f47e2700b56e45deea91d95eeebdc84

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "id": "6f47e2700b56e45deea91d95eeebdc84",
    "name": "this is my resource",
    "creation": "2023-11-11 13:52:51",
    "url": "https://cdn.endpoint/path/to/resource",
    "width": 533,
    "height": 400,
    "size": 20903,
    "mime_type": "image/png"
  }
}
Required parameters
parameter description
idID ID of the CDN resource
typeSTRING CDN type, see i1/cdns/property for details
Optional parameters
parameter description max length
external_urlURL URL to an external resource (not managed by the CDN), this URL must be with HTTPS 4000
infoJSON JSON containing additional info on the resource
inputSTRING name of the HTML form field that contains data for the resource, if not passed the default value input will be used (i.e., input = input)

NOTES: The parameter input contains the name of the field of the HTML form that is used to send resource data to this method. Form must have enctype = "multipart/form-data" and method = "post".

<form 
    action="/a/i1/cdns/edit" 
    method="post" 
    enctype="multipart/form-data">

    <input name="input" value="resource_field" type="hidden"/>

    [other form fields]

    <input name="resource_field" type="file"/>    

</form>
Return values
parameter description
creation date/time when the CDN resource was created
height height in pixels of the CDN resource, if available
id ID of the CDN resource
mime_type MIME type of the resource, or 'external_url' for external URLs
name name of the CDN resource
size size in bytes of the CDN resource, if available
url URL of the CDN resource
width width in pixels of the CDN resource, if available

/cdns/info

access: [READ]

This method returns information about a resource on the CDN.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/cdns/info?id=a34cd98f9833caa2ee47d0e6cb246cb3

Query parameters

id = a34cd98f9833caa2ee47d0e6cb246cb3

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "data": {
      "id": "a34cd98f9833caa2ee47d0e6cb246cb3",
      "name": "this is my resource",
      "creation": "2019-06-25 13:01:23",
      "url": "https://cdn.endpoint/path/to/resource",
      "width": 533,
      "height": 400,
      "size": 20903,
      "mime_type": "image/png"
    }
  }
}
Required parameters
parameter description
idID ID of the CDN resource
Return values
parameter description
data array containing required information on CDN resources

access: [WRITE]

This method allows to add an association between a CDN resource and a key and/or a tracking link. This method allows multiple instances for the combination (CDN resource,key).

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/cdns/links/add?key=my_custom_config_key&cdn_id=c54ccc8e21ef3d0a5057a01eee9b1831&value=%7B%22position%22%3A%22top_left%22%7D

Query parameters

   key = my_custom_config_key
cdn_id = c54ccc8e21ef3d0a5057a01eee9b1831
 value = {"position":"top_left"}

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "added": 1
  }
}
Required parameters
parameter description max length
cdn_idID ID of the CDN resource
keySTRING key that identifies the CDN resource/tracking link association, available values: reports_config, instaurl, instaurl_bg, instaurl_images, preview_image 50
Optional parameters
parameter description
url_idID ID of the tracking link
valueJSON value for the association, it must be a stringified JSON
Return values
parameter description
added 1 on success, 0 otherwise

access: [WRITE]

This method deletes all the associations between a CDN resource and a key and/or a tracking link. If the resource ID is not passed, it deletes all associations by using the key.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/cdns/links/delete?key=my_custom_config_key&cdn_id=62261cc3c52968c8b9395aff2625d2ff

Query parameters

   key = my_custom_config_key
cdn_id = 62261cc3c52968c8b9395aff2625d2ff

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "deleted": 5
  }
}
Required parameters
parameter description max length
keySTRING key that identifies the CDN resource/tracking link association, available values: reports_config, instaurl, instaurl_bg, instaurl_images, preview_image 50
Optional parameters
parameter description
cdn_idID if passed, only the associations with the CDN resource identified by this ID will be deleted
url_idID if passed, only the associations with the tracking link identified by this ID will be deleted
Return values
parameter description
deleted number of deleted associations

access: [READ]

This method returns all the associations between a CDN resource and a key and/or a tracking link.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/cdns/links/get?key=my_custom_config_key&cdn_id=8ce8742a6883d9089e49957bb09ffb72

Query parameters

   key = my_custom_config_key
cdn_id = 8ce8742a6883d9089e49957bb09ffb72

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "data": {
      "id": "b9c857f814a883ddd33d2fbaf4227f64",
      "key": "my_custom_config_key",
      "value": {
        "position": "top_left"
      },
      "cdn_id": "8ce8742a6883d9089e49957bb09ffb72",
      "url_id": "3f237d058b81e4edaa5aeff669b6a1d4",
      "name": "this is my resource",
      "creation": "2019-06-25 13:01:23",
      "url": "https://cdn.endpoint/path/to/resource",
      "width": 533,
      "height": 400,
      "size": 20903,
      "mime_type": "image/png"
    }
  }
}
Required parameters
parameter description max length
keySTRING key that identifies the CDN resource/tracking link association, available values: reports_config, instaurl, instaurl_bg, instaurl_images, preview_image 50
Optional parameters
parameter description
cdn_idID if passed, only the associations with the CDN resource identified by this ID will be returned
url_idID if passed, only the associations with the tracking link identified by this ID will be returned
Return values
parameter description
data array containing information on the association and the linked CDN resource

access: [WRITE]

This method allows to set the association between a CDN resource and a key and/or a tracking link. This method allows only one instance for the combination (CDN resource,key).

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/cdns/links/set?key=my_custom_config_key&cdn_id=4d6dfb90f5591165ffefa87488ed01b8&value=%7B%22position%22%3A%22top_left%22%7D

Query parameters

   key = my_custom_config_key
cdn_id = 4d6dfb90f5591165ffefa87488ed01b8
 value = {"position":"top_left"}

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "set": 1
  }
}
Required parameters
parameter description max length
cdn_idID ID of the CDN resource
keySTRING key that identifies the CDN resource/tracking link association, available values: reports_config, instaurl, instaurl_bg, instaurl_images, preview_image 50
Optional parameters
parameter description
url_idID ID of the tracking link
valueJSON value for the association, it must be a stringified JSON
Return values
parameter description
set 1 on success, 0 otherwise

/cdns/list

access: [READ]

This method returns a list of resource on the CDN linked with the current user.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/cdns/list?type=image

Query parameters

type = image

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "count": 1,
    "data": {
      "id": "1234567890abcdef",
      "name": "this is my resource",
      "creation": "2019-06-25 13:01:23",
      "url": "https://cdn.endpoint/path/to/resource",
      "width": 533,
      "height": 400,
      "size": 20903,
      "mime_type": "image/png"
    }
  }
}
Required parameters
parameter description
typeSTRING CDN type, see i1/cdns/property for details
Optional parameters
parameter description
filtersJSON filters to be used extracing media
lengthINTEGER extracts this number of CDN resources (maxmimum allowed: 100)
searchSTRING filters CDN resources to be extracted by searching them
startINTEGER starts to extract CDN resources from this position
Return values
parameter description
count total number of (filtered) CDN resources
data array containing required information on CDN resources

/cdns/property

access: [READ]

This method return limits for uploading a resource on the CDN.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)Example 5 (json)Example 6 (xml)Example 7 (txt)Example 8 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/cdns/property

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "image": {
      "max_size": 5242880,
      "allowed_types": [
        "gif",
        "jpg",
        "png",
        "svg",
        "webp"
      ],
      "allowed_mimes": [
        "image/gif",
        "image/jpeg",
        "image/jpg",
        "image/pjpeg",
        "image/x-png",
        "image/png",
        "image/svg+xml",
        "application/svg+xml",
        "image/webp"
      ]
    }
  }
}
Optional parameters
parameter description
typeSTRING CDN resource type, available types: image
Return values
parameter description
[ARRAY] it is an object (type,(max_size,allowed_types,allowed_mimes)), see parameters max_size, allowed_types, allowed_mimes for details
allowed_mimes array containing the allowed mimes for the resource
allowed_types array containing the allowed types for the resource
max_size it is the maximum size in bytes the resource can have

/conversions

/conversions/affiliates

/conversions/affiliates/count

access: [READ]

This method returns the number of affiliates.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/conversions/affiliates/count

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "count": 9
  }
}
Optional parameters
parameter description
idID ID of the affiliate network
Return values
parameter description
count number of affiliate networks

/conversions/affiliates/list

access: [READ]

This method lists all affiliates network.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/conversions/affiliates/list

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "data": {
      "id": "644a4b356f74446f62613864764b3762725a343966673d3d",
      "name": "Network name",
      "actual_url_params": "id={:CLICK_ID:}",
      "postback_url_params": "clickid={id}&comm={comm}",
      "integration_link": ""
    }
  }
}
Optional parameters
parameter description
idID ID of the affiliate network
lengthINTEGER number of items to return (default: 1000, max value: 1000)
searchSTRING filter items by searching them
startINTEGER index of the starting item to retrieve (default: 0)
Return values
parameter description
count number of affiliate networks
data array containing affiliate networks

/conversions/codes

/conversions/codes/add

access: [WRITE]

Create a conversion code for the logged user.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/conversions/codes/add?name=name+of+the+new+conversion+code¬es=this+is+a+note+for+the+conversion+code

Query parameters

 name = name of the new conversion code
notes = this is a note for the conversion code

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "name": "name of the new conversion code",
    "notes": "this is a note for the conversion code",
    "id": "d6eef741f3a6a5721ccc89935094312a",
    "enable_postback_url": 0,
    "affiliate_network_id": ""
  }
}
Required parameters
parameter description max length
nameSTRING conversion name 100
Optional parameters
parameter description max length
affiliate_network_idID ID of the linked affiliate network, see i1/conversions/affliates/list for details
enable_postback_urlBOOLEAN 1 to enable postback URLs for the conversion
notesSTRING notes for the conversion 255
Return values
parameter description
affiliate_network_id echo back of the affiliate_network_id input parameter
enable_postback_url echo back of the enable_postback_url input parameter
id ID of the conversion code
name echo back of the name input parameter
notes echo back of the notes input parameter

/conversions/codes/count

access: [READ]

This method returns the number of defined conversion codes.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)Example 5 (json)Example 6 (xml)Example 7 (txt)Example 8 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/conversions/codes/count

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "count": 4321
  }
}
Optional parameters
parameter description
searchSTRING filters conversion codes to be extracted by searching them
Return values
parameter description
count number of (filtered) conversion codes

/conversions/codes/delete

access: [WRITE]

This method deletes a set of conversion codes using their IDs.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)Example 5 (json)Example 6 (xml)Example 7 (txt)Example 8 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/conversions/codes/delete?ids=799bc3139013a3cf925a7d11aa487e7b,33c562167dd80fc5f9f7fe1aacfbd7c1,1391b049184ffef167b0f6e1be94ba36

Query parameters

ids = 799bc3139013a3cf925a7d11aa487e7b,33c562167dd80fc5f9f7fe1aacfbd7c1,1391b049184ffef167b0f6e1be94ba36

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "deleted": 3
  }
}
Required parameters
parameter description
idsARRAY_OF_IDS comma-separated list of conversion code IDs to be deleted
Return values
parameter description
deleted number of deleted conversion codes
ids [OPTIONAL] list of conversion code IDs whose delete has failed, this parameter is returned only when at least one delete error has occurred

/conversions/codes/edit

access: [WRITE]

Edit fields of a conversion.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/conversions/codes/edit?id=c5c5f970acc28552fe2fa6cd863ae97f¬es=new+notes+for+the+conversion+code

Query parameters

   id = c5c5f970acc28552fe2fa6cd863ae97f
notes = new notes for the conversion code

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "id": "c5c5f970acc28552fe2fa6cd863ae97f",
    "notes": "new notes for the conversion code"
  }
}
Required parameters
parameter description
idID ID of the conversion code
Optional parameters
parameter description max length
affiliate_network_idID ID of the affiliate network linked to the conversion code, it is ignored if enable_postback_url = 0
enable_postback_urlBOOLEAN 1 to enabled postback URLs for the conversion code, 0 to disable it
nameSTRING name of the conversion code 100
notesSTRING notes for the conversion code 255
Return values
parameter description
affiliate_network_id [OPTIONAL] echo back of the affiliate_network_id input parameter
enable_postback_url [OPTIONAL] echo back of the enable_postback_url input parameter
id echo back of the id input parameter
name [OPTIONAL] echo back of the name input parameter
notes [OPTIONAL] echo back of the notes input parameter

/conversions/codes/info

access: [READ]

This method returns information about conversion code.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/conversions/codes/info?id=185b38186df409ad1f218b6e413f3285&fields=id,name,notes

Query parameters

    id = 185b38186df409ad1f218b6e413f3285
fields = id,name,notes

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "id": "185b38186df409ad1f218b6e413f3285",
    "name": "name",
    "notes": "notes"
  }
}
Required parameters
parameter description
fieldsARRAY comma separated list of fields to return, available fields: id, ext_id, ext_postback_id, name, notes, enable_postback_url, affiliate_network_id, creation, clicks, last_click, value, performance
idID NA
Return values
parameter description
[ARRAY] see i1/conversions/codes/list for details on returned fields

/conversions/codes/list

access: [READ]

This method returns a list of user's conversions, specified in a comma separated input called fields.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/conversions/codes/list?fields=count,id,name

Query parameters

fields = count,id,name

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "count": 4,
    "data": [
      {
        "id": "d621eaca8a6a50a0c8a6f2824ea89e30",
        "name": "conversion code 1"
      },
      {
        "id": "6434704bd4a7e99d927bbdf48f306575",
        "name": "conversion code 2"
      },
      {
        "id": "338f67d223ffd8b33b028d4c0bbad019",
        "name": "conversion code 3"
      },
      {
        "id": "e9ba6f51aea7ce6902c1a32982b3f0c1",
        "name": "conversion code 4"
      }
    ]
  }
}
Required parameters
parameter description
fieldsARRAY comma separated list of fields to return, available fields: count, id, ext_id, ext_postback_id, name, notes, enable_postback_url, affiliate_network_id, creation, clicks, last_click, value, performance
Optional parameters
parameter description
lengthINTEGER extracts this number of coversion codes (maxmimum allowed: 100)
orderbyARRAY orders coversion codes by field, available fields: count, id, ext_id, ext_postback_id, name, notes, enable_postback_url, affiliate_network_id, creation, clicks, last_click, value, performance
searchSTRING filters coversion codes to be extracted by searching them
sortSTRING sorts coversion codes in ascending (ASC) or descending (DESC) order
startINTEGER starts to extract coversion codes from this position
Return values
parameter description
count [OPTIONAL] total number of (filtered) coversion codes, returned only if count is passed in fields
data array containing required information on coversion codes

/conversions/codes/params

/conversions/codes/params/count

access: [READ]

This method returns the number of parameters linked to a conversion code.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/conversions/codes/params/count

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "count": 2
  }
}
Required parameters
parameter description
idID ID of the conversion code
Optional parameters
parameter description
param_numSTRING filter conversion parameters by parameter number, see i1/conversions/codes/params/list for details
searchSTRING filters conversion parameters to be extracted by searching them
Return values
parameter description
count number of (filtered) conversion parameters
/conversions/codes/params/has_params

access: [READ]

This method returns the number of parameters related to a conversion code.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/conversions/codes/params/has_params?id=798e38bb762e4f758729e1278dc91342

Query parameters

id = 798e38bb762e4f758729e1278dc91342

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "has_params": 1,
    "param": 1,
    "ep00": 1,
    "ep01": 0,
    "ep02": 0,
    "ep03": 0,
    "ep04": 0,
    "ep05": 0,
    "ep06": 0,
    "ep07": 0,
    "ep08": 0,
    "ep09": 0,
    "ep10": 0,
    "ep11": 0,
    "ep12": 0,
    "ep13": 0,
    "ep14": 0
  }
}
Required parameters
parameter description
idID ID of the conversion code
Return values
parameter description
ep00 1 if the extended parameter ep00 is associated to the conversion code
ep01 1 if the extended parameter ep01 is associated to the conversion code
ep02 1 if the extended parameter ep02 is associated to the conversion code
ep03 1 if the extended parameter ep03 is associated to the conversion code
ep04 1 if the extended parameter ep04 is associated to the conversion code
ep05 1 if the extended parameter ep05 is associated to the conversion code
ep06 1 if the extended parameter ep06 is associated to the conversion code
ep07 1 if the extended parameter ep07 is associated to the conversion code
ep08 1 if the extended parameter ep08 is associated to the conversion code
ep09 1 if the extended parameter ep09 is associated to the conversion code
ep10 1 if the extended parameter ep10 is associated to the conversion code
ep11 1 if the extended parameter ep11 is associated to the conversion code
ep12 1 if the extended parameter ep12 is associated to the conversion code
ep13 1 if the extended parameter ep13 is associated to the conversion code
ep14 1 if the extended parameter ep14 is associated to the conversion code
has_params 1 if at least one extended parameter is associated to the conversion code
param 1 if param is associated to the conversion code
/conversions/codes/params/list

access: [READ]

This method returns a list of parameters related to a conversion code.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)Example 5 (json)Example 6 (xml)Example 7 (txt)Example 8 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/conversions/codes/params/list?id=d087da322426d8e1ab320107c45bfcf6

Query parameters

id = d087da322426d8e1ab320107c45bfcf6

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "count": 2,
    "data": [
      {
        "param_id": "b64287c328df143773cf6cf65bca7e32",
        "param": "this is the value #1 of parameter 'param'"
      },
      {
        "param_id": "31293f906ad206c408d91af63be498ac",
        "param": "this is the value #2 of parameter 'param'"
      }
    ]
  }
}
Required parameters
parameter description
idID ID of the conversion code
Optional parameters
parameter description
lengthINTEGER extracts this number of coversion parameters (maxmimum allowed: 100)
param_numSTRING if not passed or param_num = 255 it returns the parameter param, if param_num = 0 it returns the extended paarameter ep00, ..., if param_num = 7 it returns the extended paarameter ep07, ..., if param_num = 14 it returns the extended paarameter ep14,
searchSTRING filters coversion parameters to be extracted by searching them
startINTEGER starts to extract coversion parameters from this position
Return values
parameter description
count number of available parameter with the specified param_num
data array containing required information on coversion code parameters

/conversions/codes/urls

/conversions/codes/urls/count

access: [READ]

This method returns the number of tracking links liked to a conversion code.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/conversions/codes/urls/count

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "count": 1
  }
}
Required parameters
parameter description
idID ID of the conversion code
Optional parameters
parameter description
searchSTRING filters tracking pixels to be extracted by searching them
Return values
parameter description
count number of (filtered) tracking pixels
/conversions/codes/urls/list

access: [READ]

This method returns a list of tracking links related to a conversion code.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/conversions/codes/urls/list?id=c3b3b6ef6c4884d78cd83a589942ca6d&fields=count,url_id,alias

Query parameters

    id = c3b3b6ef6c4884d78cd83a589942ca6d
fields = count,url_id,alias

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "count": 2,
    "data": [
      {
        "url_id": "915bef96d90bfa6956ceddec71f2e6a4",
        "alias": "6f697dbc"
      },
      {
        "url_id": "a1306175bb783ac61a2400b87a3ac6fc",
        "alias": "21e3ea00"
      }
    ]
  }
}
Required parameters
parameter description
fieldsARRAY comma-separated list of fields to return, available fields: count, url_id, alias, short_url, creation, long_url, domain_host, domain_id, project_name, project_id
idID ID of the conversion code
Optional parameters
parameter description
lengthINTEGER extracts this number of tracking links (maxmimum allowed: 100)
orderbyARRAY orders tracking links by field, available fields: url_id, alias, short_url, creation, long_url, domain_host, domain_id, project_name, project_id
searchSTRING filters tracking links to be extracted by searching them
sortSTRING sorts tracking links in ascending (ASC) or descending (DESC) order
startINTEGER starts to extract tracking links from this position
Return values
parameter description
count [OPTIONAL] total number of tracking links, returned only if count is passed in fields
data array containing information on the tracking links, the returned information depends on the fields parameter.

/conversions/count

access: [READ]

This method is actually an interface to i1/conversions/codes/count and/or to i1/conversions/pixels/count according to types.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/conversions/count?types=code,pixel

Query parameters

types = code,pixel

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "count": 777
  }
}
Required parameters
parameter description
typesARRAY comma separated list of types; available types are [code, pixel]
Return values
parameter description
count number of conversion, if both types are passed, it contains the sum of number of conversion codes and conversion pixels

/conversions/list

access: [READ]

This method is actually an interface to i1/conversions/codes/list and/or to i1/conversions/pixels/list according to types.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/conversions/list?types=code,pixel&fields=name,id,short_url

Query parameters

 types = code,pixel
fields = name,id,short_url

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "data": [
      {
        "name": "conversion code 1 (postback enabled)",
        "id": "a34cb1c0533f72233120e353b14bd03a",
        "ext_id": "c5b8f13637d874fb1f8bf4ff13b5d10b",
        "ext_postback_id": "9e606f8b41b2d517e492f63f68dac94f",
        "type": "code"
      },
      {
        "name": "conversion code 2",
        "id": "2e5c321589e88f28c912fe3ddf698252",
        "ext_id": "24cd5c8e10118d235848f65e1e4d87e6",
        "type": "code"
      },
      {
        "id": "1b50d6a979639d416ec346b4363a0c70",
        "short_url": "https://domain.ext/tracking_pixel_alias",
        "type": "pixel"
      }
    ]
  }
}
Required parameters
parameter description
typesARRAY comma separated list of types; available types are [code, pixel]
Return values
parameter description
count [OPTIONAL] number of conversion, if both types are passed, it contains the sum of number of conversion codes and conversion pixels
data array containing information on conversions

/conversions/pixels

/conversions/pixels/add

access: [WRITE]

Add a tracking pixel for the logged user.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/conversions/pixels/add?alias=jot&domain_id=55f362c731d0fa7f5023a68ecd91a773&url_project_id=8bbe09cdbc035f5253f734072c444b68¬es=

Query parameters

         alias = jot
     domain_id = 55f362c731d0fa7f5023a68ecd91a773
url_project_id = 8bbe09cdbc035f5253f734072c444b68
         notes =

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "id": "613e89027333c3514daac1fa55a3ea1f",
    "alias": "jot",
    "domain_id": "55f362c731d0fa7f5023a68ecd91a773",
    "domain_host": "jo.my",
    "domain_nickname": "",
    "url_project_id": "8bbe09cdbc035f5253f734072c444b68",
    "project_name": "project name",
    "short_url": "//jo.my/jot",
    "template_type": 2,
    "notes": ""
  }
}
Required parameters
parameter description max length
aliasSTRING alias for the tracking pixel, see i1/urls/shorten for details of available characters in alias 510
Optional parameters
parameter description
conversion_idsARRAY_OF_IDS ID of the associated conversion codes
domain_idID ID of the domain for the tracking pixel, if not set the default domain for the user will be used
notesSTRING notes for the tracking pixel
tagsARRAY comma-separated list of tags for the tracking pixel
url_project_idID ID of the project where the tracking pixel will be put in, if not specified the default: project is used
Return values
parameter description
alias see i1/urls/shorten for details on returnd fields
domain_host see i1/urls/shorten for details on returnd fields
domain_id see i1/urls/shorten for details on returnd fields
domain_nickname see i1/urls/shorten for details on returnd fields
id ID of the created tracking pixel
notes see i1/urls/shorten for details on returnd fields
project_id see i1/urls/shorten for details on returnd fields
project_name see i1/urls/shorten for details on returnd fields
short_url see i1/urls/shorten for details on returnd fields
tags see i1/urls/shorten for details on returnd fields
tags see i1/urls/shorten for details on returnd fields
url_conversions_number number of associated conversion codes

/conversions/pixels/count

access: [READ]

This method returns the number of defined conversion pixels.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/conversions/pixels/count

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "count": 5
  }
}
Optional parameters
parameter description
searchSTRING filters conversion pixels to be extracted by searching them
Return values
parameter description
count number of (filtered) conversion pixels

/conversions/pixels/delete

access: [WRITE]

This method deletes a set of conversion pixel using their IDs.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)Example 5 (json)Example 6 (xml)Example 7 (txt)Example 8 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/conversions/pixels/delete?ids=f055d259c24a67f10bf5f33513cd8697,b97f2adbf25610c5b64c5e1daf0b7254,5ca78e3ee6c908b7c250b04969d5f178

Query parameters

ids = f055d259c24a67f10bf5f33513cd8697,b97f2adbf25610c5b64c5e1daf0b7254,5ca78e3ee6c908b7c250b04969d5f178

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "deleted": 3
  }
}
Required parameters
parameter description
idsARRAY_OF_IDS comma-separated list of tracking pixel IDs to be deleted
Return values
parameter description
deleted number of deleted tracking pixels
tracking_pixel_ids [OPTIONAL] list of tracking pixel IDs whose delete has failed, this parameter is returned only when at least one delete error has occurred

/conversions/pixels/edit

access: [WRITE]

Edit fields of a Tracking Pixel.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/conversions/pixels/edit?id=4398ccb34735069fe5daa548707f60c4&alias=jot&domain_id=ef3cd4e707ec0268a020cc4f214daaa8&url_project_id=f9c4211260d7edc86141b04091e7dac2¬es=new+notes

Query parameters

            id = 4398ccb34735069fe5daa548707f60c4
         alias = jot
     domain_id = ef3cd4e707ec0268a020cc4f214daaa8
url_project_id = f9c4211260d7edc86141b04091e7dac2
         notes = new notes

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "id": "4398ccb34735069fe5daa548707f60c4",
    "alias": "jot",
    "domain_id": "ef3cd4e707ec0268a020cc4f214daaa8",
    "domain_host": "jo.my",
    "domain_nickname": "",
    "url_project_id": "f9c4211260d7edc86141b04091e7dac2",
    "project_name": "project name",
    "short_url": "//jo.my/jot",
    "template_type": 2,
    "notes": "new notes"
  }
}
Required parameters
parameter description
idID ID of the tracking pixel
Optional parameters
parameter description
conversion_idsARRAY_OF_IDS ID of the associated conversion codes
notesSTRING notes for the tracking pixel
tagsARRAY comma-separated list of tags for the tracking pixel
Return values
parameter description
alias see i1/urls/shorten for details on returnd fields
domain_host see i1/urls/shorten for details on returnd fields
domain_id see i1/urls/shorten for details on returnd fields
id ID of the created tracking pixel
long_url see i1/urls/shorten for details on returnd fields
notes see i1/urls/shorten for details on returnd fields
project_id see i1/urls/shorten for details on returnd fields
project_name see i1/urls/shorten for details on returnd fields
short_url see i1/urls/shorten for details on returnd fields
tags see i1/urls/shorten for details on returnd fields
url_conversions_number number of associated conversion codes

/conversions/pixels/info

access: [READ]

This method returns information specified in a comma separated input called fields about a conversion.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/conversions/pixels/info?fields=id,short_url&id=e1b47bd32e31395a1dcce15955d6a7aa

Query parameters

fields = id,short_url
    id = e1b47bd32e31395a1dcce15955d6a7aa

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "data": [
      {
        "id": "e1b47bd32e31395a1dcce15955d6a7aa",
        "short_url": "http://jo.my/72b01650"
      }
    ]
  }
}
Required parameters
parameter description
fieldsARRAY comma separated list of fields to return, see method i1/conversions/pixels/list for reference
idID ID of the tracking pixel whose information is required
Return values
parameter description
data array containing 1 item on success, the returned information depends on the fields parameter.

/conversions/pixels/list

access: [READ]

This method returns a list of tracking pixels.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/conversions/pixels/list?fields=id,short_url&url_project_id=9d99051a74290125cd2bc1f546911019

Query parameters

        fields = id,short_url
url_project_id = 9d99051a74290125cd2bc1f546911019

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "data": [
      {
        "id": "b3505c2788e3560c17ae8fb32252e2b3",
        "short_url": "http://jo.my/a5b992c9"
      },
      {
        "id": "f6749e2259880f7f28930c2d19af0f2c",
        "short_url": "http://jo.my/c49bb24d"
      },
      {
        "id": "94bf94cc82749351b7a2a876fefd2194",
        "short_url": "http://jo.my/fa619c13"
      },
      {
        "id": "64cfbe9e6a343540acde043069e723f3",
        "short_url": "http://jo.my/111e6caf"
      },
      {
        "id": "ae0227435c708b606d815ad292276a7f",
        "short_url": "http://jo.my/a1158987"
      }
    ]
  }
}
Required parameters
parameter description
fieldsARRAY comma separated list of fields to return, available fields: count, id, short_url, creation, url_tags, clicks, unique_visits, qrcodes_visits, conversions_visits, notes, alias
Optional parameters
parameter description
idID ID of the tracking pixel
lengthINTEGER extracts this number of items (maxmimum allowed: 100)
orderbyARRAY orders items by field, available fields: count, id, short_url, creation, url_tags, clicks, unique_visits, qrcodes_visits, conversions_visits, notes, alias
searchSTRING filters items to be extracted by searching them
sortSTRING sorts items in ascending (ASC) or descending (DESC) order
startINTEGER starts to extract items from this position
Return values
parameter description
data array containing information on the tracking pixels, the returned information depends on the fields parameter.

/conversions/settings

/conversions/settings/get

access: [READ]

This method returns global setting for conversions.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/conversions/settings/get

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "last_or_first_click": "last",
    "expiration_cookie": "30",
    "currency_id": "2d6b8cf276eede2b1218c7ab9331c5c1"
  }
}
Return values
parameter description
currency_id ID of the currency to apply to conversions, see i1/currencies/list for details
expiration_cookie expiration period (in days) for conversion cookies
last_or_first_click the click is assigned to the first or last click

/conversions/settings/property

access: [READ]

This method returns default values and properties for conversion settings.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/conversions/settings/property

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "default_last_or_first_click": "last",
    "default_expiration_cookie": "30",
    "default_currency_id": "644a4b356f74446f62613864764b3762725a343966673d3d",
    "default_clickbank_secret_key": "",
    "expiration_cookie_days": [
      1,
      7,
      30,
      60,
      90
    ]
  }
}
Return values
parameter description
default_clickbank_secret_key default ClickBank secret key
default_currency_id default currency ID for the conversion, see i1/currencies/list for details
default_expiration_cookie default expiration (in days) for the conversion cookie
default_last_or_first_click default behavior for the click assignment
expiration_cookie_days list of allowed expiration days

/conversions/settings/set

access: [WRITE]

This method sets global setting for conversions.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/conversions/settings/set?last_or_first_click=last&expiration_cookie=30¤cy_id=c0f92f5cf6c35fc2ad4a1c16a72e028d&clickbank_secret_key=AB2E1AAB8E21B434

Query parameters

 last_or_first_click = last
   expiration_cookie = 30
         currency_id = c0f92f5cf6c35fc2ad4a1c16a72e028d
clickbank_secret_key = AB2E1AAB8E21B434

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "updated": 1
  }
}
Required parameters
parameter description
clickbank_secret_keySTRING ClickBank secret key
currency_idID ID of the currency to apply to conversions, see i1/currencies/list for details
expiration_cookieINTEGER expiration period (in days) for conversion cookies, available values: 1, 7, 30, 60, 90
last_or_first_clickSTRING assign a conversion to the first or last click made by the user on the tracking link/pixel
Return values
parameter description
updated 1 on success, 0 otherwise

/ctas

/ctas/count

access: [READ]

This method returns the number of defined call to actions.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/ctas/count

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "count": 4
  }
}
Optional parameters
parameter description
searchSTRING filters CTAs to be extracted by searching them
typesSTRING comma-separated list of types to filter CTAs, for available types see i1/ctas/property
Return values
parameter description
count number of (filtered) CTAs

/ctas/delete

access: [WRITE]

This method deletes a set of CTAs by using their IDs.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)Example 5 (json)Example 6 (xml)Example 7 (txt)Example 8 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/ctas/delete?ids=f8ec6c7558e1e103268901bd7e5597d9,9f44546291bf1b17f9f39108284257b2,7783935714225c24cd3779221470ed7a

Query parameters

ids = f8ec6c7558e1e103268901bd7e5597d9,9f44546291bf1b17f9f39108284257b2,7783935714225c24cd3779221470ed7a

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "deleted": 3
  }
}
Required parameters
parameter description
idsARRAY_OF_IDS comma separated list of CTA IDs to be deleted
Return values
parameter description
deleted number of deleted CTAs
ids [OPTIONAL] list of CTA IDs whose delete has failed, this parameter is returned only when at least one delete error has occurred

/ctas/download

access: [READ]

This method returns data that is collected for a specific CTA. Only data collected in the last 90 days can be returned.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)Example 5 (json)Example 6 (xml)Example 7 (txt)Example 8 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/ctas/download?id=a2854bf1705379ce8690a74afaf63e42

Query parameters

id = a2854bf1705379ce8690a74afaf63e42

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "headers": [
      "name",
      "age",
      "email"
    ],
    "lines": [
      [
        "John",
        "27",
        "john@example.com"
      ],
      [
        "Doo",
        "31",
        "doo@example.com"
      ]
    ],
    "extracted": 2,
    "skipped": 3,
    "count": 5,
    "next": ""
  }
}
Required parameters
parameter description
idID ID of the call to action
Optional parameters
parameter description
from_dateDATE date (inclusive) from which to start the export (default: 90 days before today)
lengthINTEGER number of items to return (default: 1000, max value: 1000)
return_jsonBOOLEAN if 1 this method returns a JSON data fields instead of headers and lines fields (default: 0)
sampleBOOLEAN 1 to return sample data, 0 otherwise (default: 0)
startINTEGER index of the starting item to retrieve (default: 0)
to_dateDATE date (inclusive) to finish the export (default: today)
Return values
parameter description
count maximum number of items
data [OPTIONAL] alternative to headers and lines, returned if return_json=1
extracted number of extracted items
headers [OPTIONAL] names of the corresponding information returned in lines, returned if return_json=0
lines [OPTIONAL] array containing information of the CTA data, returned if return_json=0
next URL to be called in order to fetch the next page of the list
skipped number of skipped items

/ctas/socialapps

/ctas/socialapps/add

access: [WRITE]

Add a new social app.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/ctas/socialapps/add?provider=facebook&name=my+custom+social+app&appid=700205a5ec4e125b0dcbb71efb05622f&secret=5dd7b11089bdc92ca395c5a8cbc5b8ee

Query parameters

provider = facebook
    name = my custom social app
   appid = 700205a5ec4e125b0dcbb71efb05622f
  secret = 5dd7b11089bdc92ca395c5a8cbc5b8ee

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "provider": "facebook",
    "id": "5cb07d8c9bcd5e79b9775f009c8a52c9",
    "name": "my custom social app",
    "appid": "700205a5ec4e125b0dcbb71efb05622f"
  }
}
Required parameters
parameter description max length
appidSTRING social app ID/Key/Client ID 255
nameSTRING name of the social app 255
providerSTRING name of the provider of the app, available providers: google, facebook, twitter, linkedin, amazon, microsoftgraph 50
secretSTRING social app secret 255
Return values
parameter description
appid social app ID/Key/Client ID
id ID of the social app
name name of the social app
provider name of the provider of the app, available providers: google, facebook, twitter, linkedin, amazon, microsoftgraph

/ctas/socialapps/count

access: [READ]

This method returns the number of defined social apps.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)Example 5 (json)Example 6 (xml)Example 7 (txt)Example 8 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/ctas/socialapps/count

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "count": 5
  }
}
Optional parameters
parameter description max length
providerSTRING name of the provider of the app, available providers: google, facebook, twitter, linkedin, amazon, microsoftgraph 50
searchSTRING count items by searching them
Return values
parameter description
count number of social apps the user has access to (filtered by search if passed)

/ctas/socialapps/delete

access: [WRITE]

Delete a social app.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)Example 5 (json)Example 6 (xml)Example 7 (txt)Example 8 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/ctas/socialapps/delete?ids=5919143eb87da16282e8fda0fb85b93e,5ca6d05ed3a241989b75dfb2513d1354

Query parameters

ids = 5919143eb87da16282e8fda0fb85b93e,5ca6d05ed3a241989b75dfb2513d1354

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "deleted": 2
  }
}
Required parameters
parameter description
idsARRAY_OF_IDS comma separated list of social app IDs to be deleted
Optional parameters
parameter description
confirmBOOLEAN 1 to force the cancellation of social apps even if in use (default: 0)
Return values
parameter description
deleted number of deleted social apps
ids [OPTIONAL] list of social app IDs whose delete has failed, this parameter is returned only when at least one delete error has occurred

/ctas/socialapps/edit

access: [WRITE]

Edit a social app.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/ctas/socialapps/edit?provider=facebook&name=social+app+name&appid=eae02b9a6f10da4a54de0c3892b52ded

Query parameters

provider = facebook
    name = social app name
   appid = eae02b9a6f10da4a54de0c3892b52ded

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "id": "f436e326dcb67ee45925f815c513b636",
    "provider": "facebook",
    "name": "social app name",
    "appid": "eae02b9a6f10da4a54de0c3892b52ded"
  }
}
Required parameters
parameter description
idID ID of the social app
Optional parameters
parameter description max length
appidSTRING social app ID/Key/Client ID 255
nameSTRING name of the social app 255
providerSTRING name of the provider of the app, available providers: google, facebook, twitter, linkedin, amazon, microsoftgraph 50
secretSTRING social app secret 255
Return values
parameter description
appid social app ID/Key/Client ID
id ID of the social app
name name of the social app
provider name of the provider of the app, available providers: google, facebook, twitter, linkedin, amazon, microsoftgraph

/ctas/socialapps/info

access: [READ]

This method returns information on a social app.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/ctas/socialapps/info?id=b3624debf5585d6a28fc228987a8ecda

Query parameters

id = b3624debf5585d6a28fc228987a8ecda

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "id": "b3624debf5585d6a28fc228987a8ecda",
    "provider": "facebook",
    "name": "this is my app name",
    "appid": "24586e11f9e0876cf3d2a33fef921dd4"
  }
}
Required parameters
parameter description
idID ID of the social app
Return values
parameter description
appid social app ID/Key/Client ID
id ID of the social app
name name of the social app
provider name of the provider of the app, available providers: google, facebook, twitter, linkedin, amazon, microsoftgraph

/ctas/socialapps/list

access: [READ]

This method returns a list of social apps.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/ctas/socialapps/list

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "count": 1,
    "data": {
      "id": "c66fb7b091d617729d32bee6c18ef689",
      "provider": "facebook",
      "name": "this is my app name",
      "appid": "117d6f61744bacaeee8dd278ccdc8c07"
    }
  }
}
Optional parameters
parameter description max length
lengthINTEGER extracts this number of items (maxmimum allowed: 100)
orderbyARRAY orders items by field, available fields: start, length, search, orderby, sort, provider, format, callback
providerSTRING filter social apps by provider, available providers: google, facebook, twitter, linkedin, amazon, microsoftgraph 50
searchSTRING filters items to be extracted by searching them
sortSTRING sorts items in ascending (ASC) or descending (DESC) order
startINTEGER starts to extract items from this position
Return values
parameter description
count total number of social apps
data array containing information on social apps the user has access to

/ctas/urls

/ctas/urls/count

access: [READ]

This method returns the number of user's urls related to a call to action.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/ctas/urls/count

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "count": 3
  }
}
Required parameters
parameter description
cta_idID ID of the CTA
Optional parameters
parameter description
searchSTRING filters tracking pixels to be extracted by searching them
Return values
parameter description
count number of (filtered) tracking pixels

/ctas/urls/list

access: [READ]

This method returns a list of user's urls data related to a call to action.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/ctas/urls/list?id=f0b565d26865b8ff012a40f95854258e&fields=count,id,url_url

Query parameters

    id = f0b565d26865b8ff012a40f95854258e
fields = count,id,url_url

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "count": 2,
    "data": [
      {
        "id": "6f4124bd3f5efc8f0536a24d6d2bd74d",
        "url_url": "147dbf25"
      },
      {
        "id": "ada05c50c4a388425ec067d7765b0eb6",
        "url_url": "d102f7b2"
      }
    ]
  }
}
Required parameters
parameter description
cta_idID ID of the CTA
fieldsARRAY comma-separated list of fields to return, available fields: count, id, url_url, short_url, url_creation, url, has_preview, domain_extended_name, domain_id, project_name, project_is_default, project_id
Optional parameters
parameter description
lengthINTEGER extracts this number of tracking links (maxmimum allowed: 100)
orderbyARRAY orders tracking links by field, available fields: id, url_url, short_url, url_creation, url, has_preview, domain_extended_name, domain_id, project_name, project_is_default, project_id
searchSTRING filters tracking links to be extracted by searching them
sortSTRING sorts tracking links in ascending (ASC) or descending (DESC) order
startINTEGER starts to extract tracking links from this position
Return values
parameter description
count [OPTIONAL] total number of tracking links, returned only if count is passed in fields
data array containing information on the tracking links, the returned information depends on the fields parameter.

/ctas/webhooks

/ctas/webhooks/info

access: [READ]

This method return information on a webhook.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/ctas/webhooks/info?id=12afa6f9c3d1e9737f2361ce48269b47

Query parameters

id = 12afa6f9c3d1e9737f2361ce48269b47

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "id": "12afa6f9c3d1e9737f2361ce48269b47",
    "url": "https://my.custom.webhook/",
    "type": "custom",
    "info": [],
    "notes": ""
  }
}
Required parameters
parameter description
idID ID of the CTA from which to remove the webhook
Return values
parameter description
id echo back of the id input parameter
info extended info of the webhook
notes notes for the webhook
type webhook type, see i1/ctas/webhooks/property for details
url URL of the webhook

/ctas/webhooks/property

access: [READ]

Return available webhook types and their parameters.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/ctas/webhooks/property?types=custom,zapier,mailerlite

Query parameters

types = custom,zapier,mailerlite

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "data": {
      "custom": {
        "name": "Custom webhook",
        "private": 0,
        "url_required": 1,
        "info": {
          "home": "https://joturl.zendesk.com/hc/en-us/articles/360012882199",
          "logo": "data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPHN2ZyB2ZXJzaW9uPSIxLjEiIHZpZXdCb3g9IjAgMCA1MTIgNTEyIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPgo8cGF0aCBkPSJtMjU2IDcuMzZjLTY1LjI1OSAwLTExOC40IDUzLjE0MS0xMTguNCAxMTguNCAwIDM4Ljk0MyAxOS4zMzMgNzMuMTIxIDQ4LjQ3IDk0LjcybC01OC40NiA5Ni41N2MtMC40NjItMC4xMzktMC45NzEtMC4yMzEtMS40OC0wLjM3LTEyLjIxLTMuMjg0LTI0LjkyOS0xLjQ4LTM1Ljg5IDQuODEtMjIuNjE2IDEzLjA4OS0zMC40MzIgNDIuMTM0LTE3LjM5IDY0Ljc1IDguNzQxIDE1LjE3IDI0LjY5NyAyMy42OCA0MS4wNyAyMy42OCA4LjA0NyAwIDE2LjIzNC0xLjk4OSAyMy42OC02LjI5IDEwLjk2MS02LjMzNiAxOC45MTYtMTYuNjUgMjIuMi0yOC44NnMxLjUyNi0yNC45MjktNC44MS0zNS44OWMtMS45ODktMy40MjItNC43MTgtNi40NzUtNy40LTkuMjVsNzAuNjctMTE2LjE4LTEwLjM2LTUuOTJjLTI3Ljg4OS0xNi40NjUtNDYuNjItNDYuOTQ0LTQ2LjYyLTgxLjc3IDAtNTIuNDQ4IDQyLjI3My05NC43MiA5NC43Mi05NC43MnM5NC43MiA0Mi4yNzIgOTQuNzIgOTQuNzJjMCA5Ljc1OS0xLjM0MSAxOC45MTYtNC4wNyAyNy43NWwyMi41NyA3LjAzYzMuNDIyLTExLjA1NCA1LjE4LTIyLjY2MiA1LjE4LTM0Ljc4IDAtNjUuMjU5LTUzLjE0MS0xMTguNC0xMTguNC0xMTguNHptMCA3MS4wNGMtMjYuMTMxIDAtNDcuMzYgMjEuMjI5LTQ3LjM2IDQ3LjM2czIxLjIyOSA0Ny4zNiA0Ny4zNiA0Ny4zNmMzLjkzMSAwIDcuODE2LTAuNTU1IDExLjQ3LTEuNDhsNTYuOTggMTAzLjIzIDUuNTUgMTAuMzYgMTAuNzMtNS41NWMxMy41NTEtNy40OTMgMjguOTA2LTExLjg0IDQ1LjUxLTExLjg0IDUyLjQ0OCAwIDk0LjcyIDQyLjI3MiA5NC43MiA5NC43MnMtNDIuMjczIDk0LjcyLTk0LjcyIDk0LjcyYy0yNS41NzYgMC00OC43OTQtMTAuMjIxLTY1Ljg2LTI2LjY0bC0xNi4yOCAxNy4wMmMyMS4yNzUgMjAuNDg5IDUwLjMyIDMzLjMgODIuMTQgMzMuMyA2NS4yNTkgMCAxMTguNC01My4xNDEgMTE4LjQtMTE4LjRzLTUzLjE0MS0xMTguNC0xMTguNC0xMTguNGMtMTYuNDE5IDAtMzEuNjM1IDQuMzAxLTQ1Ljg4IDEwLjM2bC01Mi4xNy05NC4zNWM5LjI1LTguNjQ5IDE1LjE3LTIwLjc2NiAxNS4xNy0zNC40MSAwLTI2LjEzMS0yMS4yMjktNDcuMzYtNDcuMzYtNDcuMzZ6bS0xNzAuOTQgMTY5LjA5Yy01MS41NjkgMTIuODU3LTg5LjU0IDU5LjcwOS04OS41NCAxMTUuMDcgMCA2NS4yNTkgNTMuMTQxIDExOC40IDExOC40IDExOC40IDYxLjA1IDAgMTA5Ljk0LTQ3LjEyOSAxMTYuMTgtMTA2LjU2aDExMC42M2M1LjI3MiAyMC4zOTYgMjMuNDk1IDM1LjUyIDQ1LjUxIDM1LjUyIDI2LjEzMSAwIDQ3LjM2LTIxLjIyOSA0Ny4zNi00Ny4zNnMtMjEuMjI5LTQ3LjM2LTQ3LjM2LTQ3LjM2Yy0yMi4wMTUgMC00MC4yMzggMTUuMTI0LTQ1LjUxIDM1LjUyaC0xMzIuMDl2MTEuODRjMCA1Mi40NDgtNDIuMjczIDk0LjcyLTk0LjcyIDk0Ljcycy05NC43Mi00Mi4yNzItOTQuNzItOTQuNzJjMC00NC40OTIgMzAuNjE4LTgxLjQ5MiA3MS43OC05MS43NnoiLz4KPC9zdmc+Cg=="
        },
        "parameters": [
          {
            "name": "fields",
            "type": "json",
            "maxlength": 2000,
            "description": "couples key/values",
            "mandatory": 0,
            "example": "{"source":"joturl","test":1}"
          }
        ]
      },
      "mailerlite": {
        "name": "MailerLite",
        "private": 0,
        "url_required": 0,
        "info": {
          "home": "https://www.mailerlite.com/",
          "logo": "https://www.mailerlite.com/assets/logo-color.png"
        },
        "parameters": [
          {
            "name": "apikey",
            "type": "string",
            "maxlength": 500,
            "description": "MailerLite API key",
            "documentation": "https://help.mailerlite.com/article/show/35040-where-can-i-find-the-api-key",
            "mandatory": 1,
            "example": "882af536be63b46d9971479b3bc48ea9"
          },
          {
            "name": "group",
            "type": "string",
            "maxlength": 500,
            "description": "GroupID of the MailerLite group",
            "documentation": "https://app.mailerlite.com/subscribe/api",
            "mandatory": 1,
            "example": "679115065"
          },
          {
            "name": "fields",
            "type": "json",
            "maxlength": 2000,
            "description": "couples key/values",
            "mandatory": 0,
            "example": "{"source":"joturl","test":1}"
          }
        ]
      },
      "zapier": {
        "name": "Zapier",
        "private": 1,
        "url_required": 0,
        "info": {
          "home": "https://zapier.com/",
          "logo": "https://cdn.zapier.com/zapier/images/logos/zapier-logo.png"
        },
        "parameters": []
      }
    }
  }
}
Optional parameters
parameter description
typesSTRING comma-separated list of webhook types to be returned, if empty all types are returned, available types: activecampaign, custom, drift, getresponse, hubspot, mailchimp, mailerlite, mailjet, mautic, moosend, sendinblue, zapier
Return values
parameter description
data array containing information on webhook parameters by type

/ctas/webhooks/subscribe

access: [WRITE]

This method add a webhook subscription to a CTA.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/ctas/webhooks/subscribe?id=790ca0bc7d08cb077126a08688755b3b&url=https%3A%2F%2Fjoturl.com%2F

Query parameters

 id = 790ca0bc7d08cb077126a08688755b3b
url = https://joturl.com/

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "added": 1
  }
}
Required parameters
parameter description
idID ID of the CTA to which to add the webhook
typeSTRING webhook type, allowed types: activecampaign, custom, drift, getresponse, hubspot, mailchimp, mailerlite, mailjet, mautic, moosend, sendinblue, zapier
Optional parameters
parameter description max length
infoJSON info to be used with the webhook (e.g., an API key), see below for details
notesSTRING notes for the webhook 4000
unsubscribeBOOLEAN 1 to unsubscribe from the current webhook (if any) and subscribe to the new one
urlSTRING URL of the webhook, required for types: custom, zapier 4000
Return values
parameter description
added 1 on success, 0 otherwise

/ctas/webhooks/test

access: [WRITE]

This endpoint sends test data to a CTA webhook.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/ctas/webhooks/test?id=6db60bbd928b3b35db462cec5f29e12a

Query parameters

id = 6db60bbd928b3b35db462cec5f29e12a

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "ok": 1
  }
}
Required parameters
parameter description
idID ID of the CTA associated with the webhook
Return values
parameter description
ok 1 on success, otherwise an error is returned

/ctas/webhooks/unsubscribe

access: [WRITE]

This method removes a webhook subscription to a CTA.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/ctas/webhooks/unsubscribe?id=1455891358cc25145562db3d4fe2970d

Query parameters

id = 1455891358cc25145562db3d4fe2970d

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "removed": 1
  }
}
Required parameters
parameter description
idID ID of the CTA from which to remove the webhook
Return values
parameter description
removed 1 on success, 0 otherwise

/currencies

/currencies/info

access: [READ]

This method returns a list of available currencies.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/currencies/info?id=8269b4fcdca3838dcf4b2d77701f70e9

Query parameters

id = 8269b4fcdca3838dcf4b2d77701f70e9

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "data": [
      {
        "id": "8269b4fcdca3838dcf4b2d77701f70e9",
        "code": "EUR",
        "sign": "€"
      }
    ]
  }
}
Required parameters
parameter description
idID ID of the currency
Return values
parameter description
data information on the specified currency

/currencies/list

access: [READ]

This method returns a list of available currencies.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/currencies/list

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "data": [
      {
        "id": "2408bf07af9bf2cd5a90a156eadc460a",
        "code": "EUR",
        "sign": "€"
      },
      {
        "id": "7a64f1e6272b7a509f9cda02b5fc80ba",
        "code": "USD",
        "sign": "$"
      },
      {
        "id": "6ec9e00036da7f38d352e434b6df936b",
        "code": "GBP",
        "sign": "£"
      }
    ]
  }
}
Return values
parameter description
data information on the specified currency

/domains

/domains/add

access: [WRITE]

Add a domain for the logged user.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/domains/add?id=1234567890abcdef&force_https=0&host=domain.ext&nickname=my+domain+nickname&redirect_url=https%3A%2F%2Fredirect.users.to%2F&favicon_url=https%3A%2F%2Fpath.to%2Ffav%2Ficon&deeplink_id=&domain_domains_deeplink_name=&input=name_of_the_form_field_that_contains_image_data

Query parameters

                          id = 1234567890abcdef
                 force_https = 0
                        host = domain.ext
                    nickname = my domain nickname
                redirect_url = https://redirect.users.to/
                 favicon_url = https://path.to/fav/icon
                 deeplink_id = 
domain_domains_deeplink_name = 
                       input = name_of_the_form_field_that_contains_image_data

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "id": "1234567890abcdef",
    "force_https": "0",
    "host": "domain.ext",
    "nickname": "my domain nickname",
    "redirect_url": "https://redirect.users.to/",
    "favicon_url": "https://path.to/fav/icon",
    "logo": "data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7",
    "deeplink_id": "",
    "domain_domains_deeplink_name": ""
  }
}
Required parameters
parameter description max length
hostSTRING domain to add (e.g., domain.ext) 850
Optional parameters
parameter description max length
deeplink_idID ID of the deep link configuration
favicon_urlSTRING the default favicon URL for the branded domain (to avoid securiy issues it must be HTTPS) 4000
forceBOOLEAN 1 to disable security checks, 0 otherwise. This parameter is ignored if force_https = 1
force_httpsBOOLEAN 1 to force HTTPS on HTTP requests, 0 otherwise (this flag takes effect only if a valid SSL certificate is associated with the domain)
inputSTRING name of the HTML form field that contains image data for the logo (max dimensions 120px x 50px, max size 150kB), see notes for details 255
nicknameSTRING the domain nickname 50
redirect_urlSTRING the default destination URL where to redirect when a user types the domain without any alias (or an invalid alias) 4000
robots_txtSTRING the robots.txt content to serve for the domain, when robots_txt = :NONE: requests to robots.txt will return a 404 error, if empty the following robots.txt will be served:
user-agent: *
disallow: /
 4000

NOTES: The parameter input contains the name of the field of the HTML form that is used to send logo data to this method. Form must have enctype = "multipart/form-data" and method = "post".

<form 
    action="/a/i1/domains/add" 
    method="post" 
    enctype="multipart/form-data">

    <input name="input" value="logo" type="hidden"/>

    [other form fields]

    <input name="logo" type="file"/>    

</form>
Return values
parameter description
deeplink_id ID of the deep link configuration
deeplink_name NA
favicon_url default favicon URL
force_https 1 if the HTTPS is forced for the domain, 0 otherwise (this flag takes effect only if a valid SSL certificate is associated with the domain)
host the domain that was just added
id ID of the added domain
logo default logo for the domain (base64 encoded)
nickname the domain nickname
redirect_url default redirect URL
robots_txt the robots.txt content to serve for the domain

/domains/certificates

/domains/certificates/acmes

/domains/certificates/acmes/domains/cert

access: [WRITE]

This method creates or renews an SSL certificate for a domain.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/domains/certificates/acmes/domains/cert?domain_id=5301501493d715c3d566763992a7d66d

Query parameters

domain_id = 5301501493d715c3d566763992a7d66d

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "created": 1,
    "private_key": "-----BEGIN PRIVATE KEY-----[BASE64-ENCODED INFO]-----END PRIVATE KEY-----",
    "csr": "-----BEGIN CERTIFICATE REQUEST-----[BASE64-ENCODED INFO]-----END CERTIFICATE REQUEST-----",
    "cert": "-----BEGIN CERTIFICATE-----[BASE64-ENCODED INFO]-----END CERTIFICATE-----",
    "cert_fingerprint": "9B5BDE73B0B3604B66688BB1092B0BB0DE2FD264",
    "cert_valid_from": "2023-11-11T13:52:51",
    "cert_valid_to": "2024-02-09T13:52:51",
    "intermediate": "-----BEGIN CERTIFICATE-----[BASE64-ENCODED INFO]-----END CERTIFICATE-----"
  }
}
Required parameters
parameter description
domain_idID ID of the domain for which the SSL certificate is asked
Return values
parameter description
cert domain SSL certificate (PEM format)
cert_fingerprint fingerprint of the SSL certificate
cert_valid_from SSL certificate is valid from this date
cert_valid_to SSL certificate is valid up to this date, usually the certificate expires 90 days after the cert_valid_from date; see <a href="https://letsencrypt.org/docs/faq/">the Let's Encrypt FAQ</a> for details
created 1 on success, 0 otherwise
csr certificate signing request (CSR) for the doamin (PEM format)
intermediate domain intermediate certificate(s) (PEM format)
private_key domain private key (PEM format)
/domains/certificates/acmes/domains/install

access: [WRITE]

This method installs an SSL certificate for a domain.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/domains/certificates/acmes/domains/install?domain_id=9cd08cad5c65998d0b1ef68d707d78b1

Query parameters

domain_id = 9cd08cad5c65998d0b1ef68d707d78b1

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "installed": 1,
    "host": "jo.my",
    "cn": "jo.my",
    "certificate_domain_id": "6e666877484257716e798888484252472b645a4a49518d8d",
    "domains": "jo.my, www.jo.my",
    "fingerprint": "6A5ACE78B0B5604B66688AA5092B0BA0CE2FD265",
    "id": "69785a4b2f7676744c5a4759642f67524561584b58778d8d",
    "valid_from": "2018-01-23 14:58:37",
    "valid_to": "2018-04-23 14:58:37",
    "issuer": "JotUrl S.r.l."
  }
}
Required parameters
parameter description
domain_idID ID of the domain for which the SSL certificate has to be installed
Return values
parameter description
certificate_domain_id ID of the domain the certificate belongs to
cn common name of the certificate
domains comma separated list of domains covered by the certificate (e.g., "domain.ext, www.domain.ext")
fingerprint fingerprint of the certificate
host domain the certificate belongs to
id ID of the certificate
installed 1 on success, 0 otherwise
issuer the certificate issuer
valid_from the certificate is valid from this dat, can be in the future (e.g., 2018-05-30 13:38:04)
valid_to the certificate is valid up to this date, can be in the past (e.g., 2020-05-29 13:38:04)
/domains/certificates/acmes/domains/revoke

access: [WRITE]

This method revokes an SSL certificate for a domain.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/domains/certificates/acmes/domains/revoke?domain_id=2a8b2bfa235885432f5e27d5f2ffb1ad

Query parameters

domain_id = 2a8b2bfa235885432f5e27d5f2ffb1ad

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "revoked": 1
  }
}
Required parameters
parameter description
domain_idID ID of the domain for which the SSL certificate should be revoked
Return values
parameter description
revoked 1 on success, 0 otherwise
/domains/certificates/acmes/domains/validate

access: [WRITE]

This method validates a domain. You have to validate a domain before creating an SSL certificate.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/domains/certificates/acmes/domains/validate?domain_id=0cb756e48417726e38346eba0b1976f1

Query parameters

domain_id = 0cb756e48417726e38346eba0b1976f1

Response

{
  "status": "valid"
}
Required parameters
parameter description
domain_idID ID of the domain to validate
Optional parameters
parameter description
include_www_subdomainBOOLEAN 1 if the WWW subdomain should be asked, 0 otherwise
Return values
parameter description
domains list of available domains in the certificate
status status of the validation request; call this method until a valid status is returned or a timeout of 30 seconds occurs. If the validation fails, you have to wait at least 30 minutes before retrying [unknown|pending|valid]
/domains/certificates/acmes/users/deactivate

access: [WRITE]

This method deactivates a user on the Let's Encrypt ACME server.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/domains/certificates/acmes/users/deactivate

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "deactivated": 0
  }
}
Return values
parameter description
deactivated 1 on success, 0 otherwise
/domains/certificates/acmes/users/generatekey

access: [WRITE]

This method generates an RSA key for the user, this key have to be used with all operations on the Let's Encrypt ACME server.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/domains/certificates/acmes/users/generatekey

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "generated": 1
  }
}
Return values
parameter description
generated 1 on success, 0 otherwise
/domains/certificates/acmes/users/register

access: [WRITE]

This method registers a user on the Let's Encrypt ACME server.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/domains/certificates/acmes/users/register

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "registered": 0
  }
}
Optional parameters
parameter description
agreementSTRING links to the Let's Encrypt agreement. Registration on Let's Encrypt ACME server requires two steps; in the first one you have to call this method without parameters, it will return an agreement link and the security parameter nonce, that the user must explicitely approve the agreement; in the second step, you have to call this method with parameters agreement and nonce set to the values returned by the previous call
forceBOOLEAN 1 if the registration process have to be forced (overwriting old values), 0 otherwise
nonceID a random security string to be used during the registration process
Return values
parameter description
agreement [OPTIONAL] returned only if agreement is needed (agreement is only in English)
nonce [OPTIONAL] returned only if agreement is needed
registered 1 on success, 0 otherwise

/domains/certificates/add

access: [WRITE]

This method allows to upload a certificate for a specific domain.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/domains/certificates/add?domain_id=6e666877484257716e798888484252472b645a4a49518d8d&cert_files_type=pfx&input_pfx_archive=%5Bpfx_file%5D

Query parameters

        domain_id = 6e666877484257716e798888484252472b645a4a49518d8d
  cert_files_type = pfx
input_pfx_archive = [pfx_file]

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "host": "jo.my",
    "id": "69785a4b2f7676744c5a4759642f67524561584b58778d8d",
    "fingerprint": "6A5ACE78B0B5604B66688AA5092B0BA0CE2FD265",
    "valid_from": "2018-01-23 14:58:37",
    "valid_to": "2018-04-23 14:58:37",
    "cn": "jo.my",
    "domains": "jo.my, www.jo.my"
  }
}
Required parameters
parameter description
cert_files_typeSTRING this parameter must be pfx or cert_files, according to the certificate files
domain_idID ID of the domain the certificate belongs to
Optional parameters
parameter description
input_ca_certificate1STRING name of the HTML form field that is used to transfer the ca certificate #1 data, see notes for details
input_ca_certificate2STRING name of the HTML form field that is used to transfer the ca certificate #2 data, see notes for details
input_ca_certificate3STRING name of the HTML form field that is used to transfer the ca certificate #2 data, see notes for details
input_certificateSTRING name of the HTML form field that is used to transfer the certificate data, mandatory if cert_files_type = cert_files , see notes for details
input_pfx_archiveSTRING name of the HTML form field that is used to transfer the PFX data, mandatory if cert_files_type = pfx , see notes for details
input_private_keySTRING name of the HTML form field that is used to transfer the private key data, mandatory if cert_files_type = cert_files , see notes for details
pfx_passwordHTML password of the PFX archive, mandatory if cert_files_type = pfx and the PFX archive is protected by a password

NOTES: Parameters starting with input_ are the names of the field of the HTML form used to send data to this method. Form must have enctype = "multipart/form-data" and method = "post".

<form 
    action="/a/i1/domains/certificates/add" 
    method="post" 
    enctype="multipart/form-data">

    <input name="input_pfx_archive" value="pfx_file" type="hidden"/>
    <input name="input_private_key" value="private_key_file" type="hidden"/>
    <input name="input_certificate" value="certificate_file" type="hidden"/>

    <input name="input_ca_certificate1" value="certificate1_file" type="hidden"/>
    <input name="input_ca_certificate2" value="certificate2_file" type="hidden"/>
    <input name="input_ca_certificate3" value="certificate3_file" type="hidden"/>

    [other form fields]

    <input name="pfx_file" type="file"/>
    <input name="private_key_file" type="file"/>    
    <input name="certificate_file" type="file"/> 

    <input name="certificate1_file" type="file"/>
    <input name="certificate2_file" type="file"/>    
    <input name="certificate3_file" type="file"/>     

</form>
Return values
parameter description
cn common name of the certificate
domain_id ID of the domain the certificate belongs to
domains comma separated list of domains covered by the certificate (e.g., "domain.ext, www.domain.ext")
fingerprint fingerprint of the certificate
host domain the certificate belongs to
id ID of the certificate
valid_from the certificate is valid from this dat, can be in the future (e.g., 2018-05-30 13:38:04)
valid_to the certificate is valid up to this date, can be in the past (e.g., 2020-05-29 13:38:04)

/domains/certificates/count

access: [READ]

This method returns number of certificates associated to a specific domain.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/domains/certificates/count

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "count": 3
  }
}
Optional parameters
parameter description
domain_idID filters certificates for this domain ID
searchSTRING count items by searching them
Return values
parameter description
count number of (filtered) certificates

/domains/certificates/csr

/domains/certificates/csr/create

access: [WRITE]

This method allows to create a Certificate Signing Request (CSR).

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/domains/certificates/csr/create?commonName=domain.ext&organizationName=My+Company&organizationalUnitName=accounting&localityName=Los+Angeles&stateOrProvinceName=California&countryName=US

Query parameters

            commonName = domain.ext
      organizationName = My Company
organizationalUnitName = accounting
          localityName = Los Angeles
   stateOrProvinceName = California
           countryName = US

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "private_key": "-----BEGIN PRIVATE KEY-----
MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQDb8gTFlUVgqoPq
0/vm/oUo0k9wW2vBpUp3chITNgjMXki05yGMNYCJR7uHCfd0XzVWOi4D7DJMIMml
HMOCVgjnei8FgniH82QCCh7LxHEAscCts32XWjQ9d4datLOrMGwDopj7W62vE+rh
nZNOCM2+NeKvZxN0ZUXTRn2Ed/CT6tGDUuCsXIBoRwz8p47phewY4ge3xWmoaykE
PP2yVpd1oe5dlliGPT9kY3WuQYHiZ+TakmcC/TyDZT2J8Q+w5SEMVylehHNd/8b5
l3f7NhIW50eIZsmY0xgfpV1wsHUp/oRvyNgRog+B6CnmRuAb96zmXf8HrmnzKQEV
TqdTl05/AgMBAAECggEBAIF2g7iJlLzBocSn4q6lQlw07u2D4nmpgZutWVZVh/hD
xyg0pFqTY4Vq48co5q9pG0wWEt/cN/73jbnSpIIjgjo+gU8M7UWYzlUk/9uRVbLC
7ldQP6zHO9iycsnBc8BgUDQTkVjjLejQIIGM7xgPtosvzK7STXFF60PhSiCfOMzX
ZAJguRmHXWeXHhRLNdXknKrPdRwRz6ra8+K0DHwVjTvqHugO2QYZIZQ7fxaf+RGL
AGjkfMdErAHGK2k/3KZKipXqMCrGgCNn1X4sonfQH1Bjx9PyTL+VD6OAeMUw1HDZ
sGo6MI4oH7GsIf0LkDXPqI0NjwYO93PR7qTzpAcqBwECgYEA7fPrDzrh8V01xEOm
YPhI5RZiXgQ7l2BR1zFOzlxhNbrJZrheX6pgP9otPk4DTDtHJP4DGkC1D3x62b3Q
4sbPq4qDPp3pdlyNNXNbOSjPtFTxKrZB5e8ShVIj9ZfVBgJ1j3N2u97ru1tRGD3y
tbfUo4bIGXgJDDmBSerwi9vw5LcCgYEA7KB4F/wlkZk2aNHKATu1GZhYKhpGUbhC
vPmiKlgsvvI5FPTeWVf5MO5b41+ctjoN1iIubRDYc+mYcAMNV6oCcmzFwTP6lYVF
K6hpQu7x8hZ1yuehpW3azhm98/eV7bW48SMcvHl6CGEffGnpQrJ/ou52mYMhS3Ga
UglUmQGybHkCgYEAm5OsL1P/YBDiU4UrpiEPgADnpbK8x5dpSvppHRFXWYrbnXaT
9ZZuwbDDfgYBr/jd5jjSDHscJpjrtauehHcaVn0EnI8gkoumo7jdfvzI+I3E9Hkf
kteB03tGGZAA7qHy/SywB9uTYvcsiV4Pb3JW6+f2snhB6iU6+/pI9hiCYvcCgYBf
9V9eUqmllt1iupjR0TXK8GXohQk5QKEH47AoveM/eBk/72FwF+X9OtxWo8J4f6h2
yxvKrQcqUnO4EPTLNS2S25uCkyKumgIIB17Qfvfs9cDFDRQXcypFZFkM472QTZ53
Y4bWw+iCF2jeWlD29E4gc9XywSOyZZpwZEpDVlXV+QKBgAqhOA5YI3WpVJga/hpw
qGoJ8bl5gab0U/1u9sXdbMKqeyyaFjXo/RaLdSOG9y4UFJP/2JMeTh1FRCWaN7rK
6xTT2rrdExqjIXZTtXXFqo9A6wYQ3EWxVBWfmyG7JY08Lwuoc/zK1OZfUZmOLV+3
yZDE4U3/Zkgx7gSM/Ffxw/62
-----END PRIVATE KEY-----
",
    "csr": "-----BEGIN CERTIFICATE REQUEST-----
MIICvDCCAaQCAQAwdzELMAkGA1UEBhMCVVMxEzARBgNVBAgMCkNhbGlmb3JuaWEx
FDASBgNVBAcMC0xvcyBBbmdlbGVzMRMwEQYDVQQKDApNeSBDb21wYW55MRMwEQYD
VQQLDAphY2NvdW50aW5nMRMwEQYDVQQDDApkb21haW4uZXh0MIIBIjANBgkqhkiG
9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2/IExZVFYKqD6tP75v6FKNJPcFtrwaVKd3IS
EzYIzF5ItOchjDWAiUe7hwn3dF81VjouA+wyTCDJpRzDglYI53ovBYJ4h/NkAgoe
y8RxALHArbN9l1o0PXeHWrSzqzBsA6KY+1utrxPq4Z2TTgjNvjXir2cTdGVF00Z9
hHfwk+rRg1LgrFyAaEcM/KeO6YXsGOIHt8VpqGspBDz9slaXdaHuXZZYhj0/ZGN1
rkGB4mfk2pJnAv08g2U9ifEPsOUhDFcpXoRzXf/G+Zd3+zYSFudHiGbJmNMYH6Vd
cLB1Kf6Eb8jYEaIPgegp5kbgG/es5l3/B65p8ykBFU6nU5dOfwIDAQABoAAwDQYJ
KoZIhvcNAQELBQADggEBACTnkScHIA5aZ4vgrIFsrETfT5/Qa+kCFzsVDpEaJOuc
2GujOYydNTwFpsQCcVdW/LR1mbsiS2CVTMTP+VrppiC/XIJ0btlXeRNzLZdQ9UaX
xBgj46J79oYxXkIpnskcms3SsrKGnK/Q1bnus0jpvTlji9DnZglQt9QvzePF15As
QCERgitEUTRKzxvYjozq/LChtBbNsg5R3uXZyAVGSgn3X+ZF4P4FCd1cEfLfnHq7
XM9eWSo8pWz0VPd9rF4D9kbZ4A9gGHGoZ+abghqFULmJ3iLcQkp+NkmMTncsCvW9
S+WspMDNbVzLxWeBZQ5gMHDgSBdBLFlnHhCT0kYes+s=
-----END CERTIFICATE REQUEST-----
"
  }
}
Required parameters
parameter description
commonNameSTRING the Fully Qualified Domain Name (FQDN) for which you are requesting the SSL Certificate, it must contain domain you are requesting a certifacate for (e.g., domain.ext, *.domain.ext)
countryNameSTRING 2-digit code of the country (ISO Alpha-2) the company is based on (e.g., US)
localityNameSTRING the full name of the locality the company is based on (e.g., Los Angeles)
organizationNameSTRING the full legal company or personal name, as legally registered, that is requesting the certificate (e.g., My Company)
organizationalUnitNameSTRING whichever branch of the company is ordering the certificate (e.g., accounting, marketing)
stateOrProvinceNameSTRING the full name of the state or province the company is based on (e.g., California)
Return values
parameter description
csr Certificate request (CSR)
private_key Private key

/domains/certificates/delete

access: [WRITE]

This method deletes a certificate.

Example 1 (json)Example 2 (xml)Example 3 (txt)Example 4 (plain)Example 5 (json)Example 6 (xml)Example 7 (txt)Example 8 (plain)

Example 1 (json)

Request

https://joturl.com/a/i1/domains/certificates/delete?id=3000

Query parameters

id = 3000

Response

{
  "status": {
    "code": 200,
    "text": "OK",
    "error": "",
    "rate": 0
  },
  "result": {
    "deleted": 1
  }
}