Docs

Use the navigation links to find quick starts, guides, and technical documentation.

Quick Starts
Guides
Concepts
Endpoints

Tabular API Quick Start

In this guide we'll use the Nyckel Api to create, train, and invoke a tabular function which predicts whether a customer is likely to purchase a premium subscription based on their demographic and usage behavior.

Authenticate Your App

  1. Sign up / sign in

    If you haven't already, sign up or log in to Nyckel by clicking 'Get Started' in the upper right corner.

  2. Get client credentials for your application

    Navigate to the Api Keys page and store the credentials in your application's config. Note that in production you should take care to ensure that at the Client Secret is stored securely.

  3. Create an access token

    Using your credentials, call the connect/token endpoint to create an access token: 

    curl -X POST \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'client_id=<clientId>&client_secret=<clientSecret>&grant_type=client_credentials' \
  '<authority>/connect/token'

    import requests

token_url = '<authority>/connect/token'
data = {'client_id': '<clientId>', 'client_secret': '<clientSecret>', 'grant_type': 'client_credentials'}

result = requests.post(token_url, data = data)
print(result.text)
    fetch('<authority>/connect/token', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: 'client_id=<clientId>&client_secret=<clientSecret>&grant_type=client_credentials'
})
.then(response => response.json())
.then(data => console.log(data));
    $clientId = '<clientId>';
$clientSecret = '<clientSecret>';

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, '<authority>/connect/token');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, 'client_id=' . $clientId . '&client_secret=' . $clientSecret . '&grant_type=client_credentials');

$headers = array();
$headers[] = 'Content-Type: application/x-www-form-urlencoded';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
curl_close($ch);
echo $result;

Set Up Your Function

  1. Create the function

    First we need to create a function which we'll train using our usage data. Use the accessToken you created in the previous step. 

    curl -X POST \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Likelihood to go Premium","input":"Tabular","output":"Classification"}' \
  'https://www.nyckel.com/v1/functions'

    import requests

url = 'https://www.nyckel.com/v1/functions'
headers = {
    'Authorization': 'Bearer ' + '<accessToken>',
}

result = requests.post(url, headers=headers, json={"name":"Likelihood to go Premium","input":"Tabular","output":"Classification"})
print(result.text)

    fetch('https://www.nyckel.com/v1/functions', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer ' + '<accessToken>',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify(
        {"name":"Likelihood to go Premium","input":"Tabular","output":"Classification"}
    )
})
.then(response => response.json())
.then(data => console.log(data));

    $ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"name":"Likelihood to go Premium","input":"Tabular","output":"Classification"}');

$headers = array();
$headers[] = 'Authorization: Bearer ' . '<accessToken>';
$headers[] = 'Content-Type: application/json';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
curl_close($ch);
echo $result;

  2. Create the fields

    For tabular data, we must specify which fields we'll be sending to Nyckel along with their data types. For this example, we'll create three fields: country, loginType, and avgTimeOnSite

    curl -X POST \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'Content-Type: application/json' \
  -d '{"name":"country","type":"Text"}' \
  'https://www.nyckel.com/v1/functions/<functionId>/fields'

    import requests

url = 'https://www.nyckel.com/v1/functions/<functionId>/fields'
headers = {
    'Authorization': 'Bearer ' + '<accessToken>',
}

result = requests.post(url, headers=headers, json={"name":"country","type":"Text"})
print(result.text)

    fetch('https://www.nyckel.com/v1/functions/<functionId>/fields', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer ' + '<accessToken>',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify(
        {"name":"country","type":"Text"}
    )
})
.then(response => response.json())
.then(data => console.log(data));

    $ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/fields');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"name":"country","type":"Text"}');

$headers = array();
$headers[] = 'Authorization: Bearer ' . '<accessToken>';
$headers[] = 'Content-Type: application/json';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
curl_close($ch);
echo $result;

    curl -X POST \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'Content-Type: application/json' \
  -d '{"name":"loginType","type":"Text"}' \
  'https://www.nyckel.com/v1/functions/<functionId>/fields'

    import requests

url = 'https://www.nyckel.com/v1/functions/<functionId>/fields'
headers = {
    'Authorization': 'Bearer ' + '<accessToken>',
}

result = requests.post(url, headers=headers, json={"name":"loginType","type":"Text"})
print(result.text)

    fetch('https://www.nyckel.com/v1/functions/<functionId>/fields', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer ' + '<accessToken>',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify(
        {"name":"loginType","type":"Text"}
    )
})
.then(response => response.json())
.then(data => console.log(data));

    $ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/fields');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"name":"loginType","type":"Text"}');

$headers = array();
$headers[] = 'Authorization: Bearer ' . '<accessToken>';
$headers[] = 'Content-Type: application/json';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
curl_close($ch);
echo $result;

    curl -X POST \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'Content-Type: application/json' \
  -d '{"name":"avgTimeOnSite","type":"Text"}' \
  'https://www.nyckel.com/v1/functions/<functionId>/fields'

    import requests

url = 'https://www.nyckel.com/v1/functions/<functionId>/fields'
headers = {
    'Authorization': 'Bearer ' + '<accessToken>',
}

result = requests.post(url, headers=headers, json={"name":"avgTimeOnSite","type":"Text"})
print(result.text)

    fetch('https://www.nyckel.com/v1/functions/<functionId>/fields', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer ' + '<accessToken>',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify(
        {"name":"avgTimeOnSite","type":"Text"}
    )
})
.then(response => response.json())
.then(data => console.log(data));

    $ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/fields');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"name":"avgTimeOnSite","type":"Text"}');

$headers = array();
$headers[] = 'Authorization: Bearer ' . '<accessToken>';
$headers[] = 'Content-Type: application/json';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
curl_close($ch);
echo $result;

  3. Create the labels

    We also need to provide the list of possible categories our function can return. For this example we'll use Will go Premium and Won't go Premium

    curl -X POST \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Will go Premium"}' \
  'https://www.nyckel.com/v1/functions/<functionId>/labels'

    import requests

url = 'https://www.nyckel.com/v1/functions/<functionId>/labels'
headers = {
    'Authorization': 'Bearer ' + '<accessToken>',
}

result = requests.post(url, headers=headers, json={"name":"Will go Premium"})
print(result.text)

    fetch('https://www.nyckel.com/v1/functions/<functionId>/labels', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer ' + '<accessToken>',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify(
        {"name":"Will go Premium"}
    )
})
.then(response => response.json())
.then(data => console.log(data));

    $ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/labels');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"name":"Will go Premium"}');

$headers = array();
$headers[] = 'Authorization: Bearer ' . '<accessToken>';
$headers[] = 'Content-Type: application/json';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
curl_close($ch);
echo $result;

    curl -X POST \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Won't go Premium"}' \
  'https://www.nyckel.com/v1/functions/<functionId>/labels'

    import requests

url = 'https://www.nyckel.com/v1/functions/<functionId>/labels'
headers = {
    'Authorization': 'Bearer ' + '<accessToken>',
}

result = requests.post(url, headers=headers, json={"name":"Won't go Premium"})
print(result.text)

    fetch('https://www.nyckel.com/v1/functions/<functionId>/labels', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer ' + '<accessToken>',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify(
        {"name":"Won't go Premium"}
    )
})
.then(response => response.json())
.then(data => console.log(data));

    $ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/labels');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"name":"Won't go Premium"}');

$headers = array();
$headers[] = 'Authorization: Bearer ' . '<accessToken>';
$headers[] = 'Content-Type: application/json';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
curl_close($ch);
echo $result;

  4. Upload some samples

    Finally, we need to upload example data where we already know whether the customer converted to Premium. To provide the tabular data, we can specify either the field name or the returned field Id. For annotating the category, however, we'll need to use the label Ids returned from the POST calls. 

    curl -X POST \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'Content-Type: application/json' \
  -d '{"data":{"country":"United States","loginType":"Google","avgTimeOnSite":"2h4m"},"annotation":{"labelId":"label_2n5a7za51n329v0l"}}' \
  'https://www.nyckel.com/v1/functions/<functionId>/samples'

    import requests

url = 'https://www.nyckel.com/v1/functions/<functionId>/samples'
headers = {
    'Authorization': 'Bearer ' + '<accessToken>',
}

result = requests.post(url, headers=headers, json={"data":{"country":"United States","loginType":"Google","avgTimeOnSite":"2h4m"},"annotation":{"labelId":"label_2n5a7za51n329v0l"}})
print(result.text)

    fetch('https://www.nyckel.com/v1/functions/<functionId>/samples', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer ' + '<accessToken>',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify(
        {"data":{"country":"United States","loginType":"Google","avgTimeOnSite":"2h4m"},"annotation":{"labelId":"label_2n5a7za51n329v0l"}}
    )
})
.then(response => response.json())
.then(data => console.log(data));

    $ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/samples');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"data":{"country":"United States","loginType":"Google","avgTimeOnSite":"2h4m"},"annotation":{"labelId":"label_2n5a7za51n329v0l"}}');

$headers = array();
$headers[] = 'Authorization: Bearer ' . '<accessToken>';
$headers[] = 'Content-Type: application/json';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
curl_close($ch);
echo $result;

    curl -X POST \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'Content-Type: application/json' \
  -d '{"data":{"country":"India","loginType":"Username / Password","avgTimeOnSite":"3h22m"},"annotation":{"labelId":"label_85osy5xwjcscc08o"}}' \
  'https://www.nyckel.com/v1/functions/<functionId>/samples'

    import requests

url = 'https://www.nyckel.com/v1/functions/<functionId>/samples'
headers = {
    'Authorization': 'Bearer ' + '<accessToken>',
}

result = requests.post(url, headers=headers, json={"data":{"country":"India","loginType":"Username / Password","avgTimeOnSite":"3h22m"},"annotation":{"labelId":"label_85osy5xwjcscc08o"}})
print(result.text)

    fetch('https://www.nyckel.com/v1/functions/<functionId>/samples', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer ' + '<accessToken>',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify(
        {"data":{"country":"India","loginType":"Username / Password","avgTimeOnSite":"3h22m"},"annotation":{"labelId":"label_85osy5xwjcscc08o"}}
    )
})
.then(response => response.json())
.then(data => console.log(data));

    $ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/samples');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"data":{"country":"India","loginType":"Username / Password","avgTimeOnSite":"3h22m"},"annotation":{"labelId":"label_85osy5xwjcscc08o"}}');

$headers = array();
$headers[] = 'Authorization: Bearer ' . '<accessToken>';
$headers[] = 'Content-Type: application/json';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
curl_close($ch);
echo $result;

    curl -X POST \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'Content-Type: application/json' \
  -d '{"data":{"country":"United States","loginType":"Username / Password","avgTimeOnSite":"41m"},"annotation":{"labelId":"label_85osy5xwjcscc08o"}}' \
  'https://www.nyckel.com/v1/functions/<functionId>/samples'

    import requests

url = 'https://www.nyckel.com/v1/functions/<functionId>/samples'
headers = {
    'Authorization': 'Bearer ' + '<accessToken>',
}

result = requests.post(url, headers=headers, json={"data":{"country":"United States","loginType":"Username / Password","avgTimeOnSite":"41m"},"annotation":{"labelId":"label_85osy5xwjcscc08o"}})
print(result.text)

    fetch('https://www.nyckel.com/v1/functions/<functionId>/samples', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer ' + '<accessToken>',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify(
        {"data":{"country":"United States","loginType":"Username / Password","avgTimeOnSite":"41m"},"annotation":{"labelId":"label_85osy5xwjcscc08o"}}
    )
})
.then(response => response.json())
.then(data => console.log(data));

    $ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/samples');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"data":{"country":"United States","loginType":"Username / Password","avgTimeOnSite":"41m"},"annotation":{"labelId":"label_85osy5xwjcscc08o"}}');

$headers = array();
$headers[] = 'Authorization: Bearer ' . '<accessToken>';
$headers[] = 'Content-Type: application/json';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
curl_close($ch);
echo $result;

    curl -X POST \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'Content-Type: application/json' \
  -d '{"data":{"country":"France","loginType":"Google","avgTimeOnSite":"1h53m"},"annotation":{"labelId":"label_2n5a7za51n329v0l"}}' \
  'https://www.nyckel.com/v1/functions/<functionId>/samples'

    import requests

url = 'https://www.nyckel.com/v1/functions/<functionId>/samples'
headers = {
    'Authorization': 'Bearer ' + '<accessToken>',
}

result = requests.post(url, headers=headers, json={"data":{"country":"France","loginType":"Google","avgTimeOnSite":"1h53m"},"annotation":{"labelId":"label_2n5a7za51n329v0l"}})
print(result.text)

    fetch('https://www.nyckel.com/v1/functions/<functionId>/samples', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer ' + '<accessToken>',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify(
        {"data":{"country":"France","loginType":"Google","avgTimeOnSite":"1h53m"},"annotation":{"labelId":"label_2n5a7za51n329v0l"}}
    )
})
.then(response => response.json())
.then(data => console.log(data));

    $ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/samples');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"data":{"country":"France","loginType":"Google","avgTimeOnSite":"1h53m"},"annotation":{"labelId":"label_2n5a7za51n329v0l"}}');

$headers = array();
$headers[] = 'Authorization: Bearer ' . '<accessToken>';
$headers[] = 'Content-Type: application/json';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
curl_close($ch);
echo $result;

  5. Wait for training to complete

    Wait ~20 seconds for Nyckel to finish training your function.

Use Your Function

  1. Call the invoke endpoint

    Now that you have a trained function, you can have it predict whether a new user will convert to premium: 

    curl -X POST \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'Content-Type: application/json' \
  -d '{"data":{"country":"United States","loginType":"Google","avgTimeOnSite":"1h25m"}}' \
  'https://www.nyckel.com/v1/functions/<functionId>/invoke'

    import requests

url = 'https://www.nyckel.com/v1/functions/<functionId>/invoke'
headers = {
    'Authorization': 'Bearer ' + '<accessToken>',
}

result = requests.post(url, headers=headers, json={"data":{"country":"United States","loginType":"Google","avgTimeOnSite":"1h25m"}})
print(result.text)

    fetch('https://www.nyckel.com/v1/functions/<functionId>/invoke', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer ' + '<accessToken>',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify(
        {"data":{"country":"United States","loginType":"Google","avgTimeOnSite":"1h25m"}}
    )
})
.then(response => response.json())
.then(data => console.log(data));

    $ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://www.nyckel.com/v1/functions/<functionId>/invoke');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"data":{"country":"United States","loginType":"Google","avgTimeOnSite":"1h25m"}}');

$headers = array();
$headers[] = 'Authorization: Bearer ' . '<accessToken>';
$headers[] = 'Content-Type: application/json';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
curl_close($ch);
echo $result;

Now Try It With Your Data

Congrats! You just trained a function that can predict the likelihood a customer will convert to Premium... for this data at least. Upload your own data to build a custom function that serves your needs!