Introduction

This API allow our paying customers to integrate AWKN app with their own IT stack

This documentation aims to provide all the information you need to work with the AWKN app's API. You'll need your personal customer API key in order to use this API. To get your key, please login as a user, go to 'settings', and you will see your API key. Then, in the headers of your API call, add an Authorization key with your value. AWKN institutes per-minute, per-user and per-IP rate limits for each API method. The current limit is set at 100 calls per minute.

Base URL

https://app.awkn.fr

Authenticating requests

Authenticate requests to this API's endpoints by sending a Authorization header with the value "{YOUR_AUTH_KEY}".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

You can retrieve your API Key by visiting your settings, in the External Account tab

Journeys

A Journey is a sequence of interactions (also called steps) created by the user in order to interact with a list of (human) recipients. The Journey is the main element in AWKN, everything else revolves around it. In order to follow-up on and interact with at least one recipient, you will need to create (or duplicate) a Journey.

With this API you can easily get details about journeys attached to your account, duplicates existing ones and programmatically launch them, add new recipients or even get recipients analytics.

Get the list of all journeys

This call will return the list of all journeys for user with several basic fields for easy filtering.

Example request:

curl --request GET \
    --get "https://app.awkn.fr/api/trainings" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://app.awkn.fr/api/trainings"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://app.awkn.fr/api/trainings',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

import requests
import json

url = 'https://app.awkn.fr/api/trainings'
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.json()

Example response (200):


[{
 "id": 526,
 "training_name": "From Zero To Hero",
 "group_name": "DC Comics",
 "start_date": "2021-10-11",
 "logo": "https://app.awkn.fr/storage/logos/batman_logo.png",
 "lang": "en",
 "created_at": "2020-02-07 12:04:02",
 "active_status": 0,
 "template_status": false,
 "archive_status": false,
 "signature": "Bruce Wayne"
 "open_rate": 0.87,
 "click_rate": 0.56,
 "analytics_shared_url": "https://app.awkn.fr/share-training/d5tnjj7rPwTW2jOmVU3uUhg0OdH1ARa6goalM8oR",
 "anonymized_analytics_shared_url": "https://app.awkn.fr/anonimized/eyJpdiIE11RZWENkdW09eVJDaWZYZitxQ24vTVE9PSIsInZhbHVlIjoicUdOaDd5Q1dYREtSOEx3aUJlNVhkTkdJTCtOTXdCZU9OM3ZibDhyZWRQYmdieWJtektSVCtFbStYK3VPNFdDdSIsIm1hYyI6ImJjMjEyOGEwNmFiZjdjMDliMWU1NzZjMDM5NWYyMzcyZWVhYWJmOGFmZDQ4MzIzNjM5MjdkZDEzMzQ2ZGM5YWQiLCJ0YWciOiIifQ=="
},
{
 "id": 550,
 "training_name": "Communication non violente",
 "group_name": "FOX",
 "start_date": "2021-10-11",
 "logo": null,
 "lang": "fr",
 "created_at": "2020-03-03 12:32:36",
 "active_status": 0,
 "template_status": false,
 "archive_status": false,
 "signature": "Donald T."
 "open_rate": 0.81,
 "click_rate": 0.78,
 "analytics_shared_url": "https://app.awkn.fr/share-training/d9tnjj7rPwTW2jOmVU3uUhg0OdH1ARa6qoalM8oR",
 "anonymized_analytics_shared_url": "https://app.awkn.fr/anonimized/erJpdiIE11RZWENkdW04eVJDaWZYZitxQ24vTVE9PSIsInZhbHVlIjoicUdOaDd5Q1dYREtSOEx3aUJlNVhkTkdJTCtOTXdCZU9OM3ZibDhyZWRQYmdieWJtektSVCtFbStYK3VPNFdDdSIsIm1hYyI6ImJjMjEyOGEwNmFiZjdjMDliMWU1NzZjMDM5NWYyMzcyZWVhYWJmOGFmZDQ4MzIzNjM5MjdkZDEzMzQ2ZGM5YWQiLCJ0YWciOiIifQ=="
}]

Received response:

Request failed with error:

Get details for a specific journey

This call will return details for a provided Journey id. If the journey has recipients attached to it, the call returns will list all recipients as well.

Example request:

curl --request GET \
    --get "https://app.awkn.fr/api/trainings/2" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://app.awkn.fr/api/trainings/2"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://app.awkn.fr/api/trainings/2',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

import requests
import json

url = 'https://app.awkn.fr/api/trainings/2'
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.json()

Example response (200):


{
    "id": 526,
    "training_name": "From Zero To Hero",
    "group_name": "DC Comics",
    "start_date": "2021-10-11",
    "logo": "https://app.awkn.fr/storage/logos/batman_logo.png",
    "lang": "en",
    "created_at": "2020-02-07 12:04:02",
    "active_status": 0,
    "template_status": false,
    "archive_status": false,
    "signature": "Bruce Wayne",
    "open_rate": 0.87,
    "click_rate": 0.56,
    "analytics_shared_url": "https://app.awkn.fr/share-training/d5tnjj7rPwTW2jOmVU3uUhg0OdH1ARa6qoalM8oZ",
    "anonymized_analytics_shared_url": "https://app.awkn.fr/anonimized/eyJpdiIE11RZWENkdW04eVJDaWZYZitxQ24vTVE9PSIsInZhbHVlIjoicUdOaDd5Q1dYREtSOEx3aUJlNVhkTkdJTCtOTXdCZU9OM3ZibDhyZWRQYmdieWJtektSVCtFbStYK3VPNFdDdSIsIm1hYyI6ImJjMjEyOGEwNmFiZjdjMDliMWU1NzZjMDM5NWYyMzcyZWVhYWJmOGFmZDQ4MzIzNjM5MjdkZDEzMzQ2ZGM5YWQiLCJ0YWciOiIifZ=="
}

Received response:

Request failed with error:

Create a new journey

This call will create a new journey in the name of the auth user. The new journey will be blank, i.e. there will be with no recipients, no step and the journey will not be active by default. Please find below the parameter you should provide in the Body.

Example request:

curl --request POST \
    "https://app.awkn.fr/api/trainings" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"training_name\": \"Market Yourself 101\",
    \"group_name\": \"Session 2\",
    \"signature\": \"Bruce\",
    \"lang\": \"en\",
    \"start_date\": \"2021-10-11\"
}"

const url = new URL(
    "https://app.awkn.fr/api/trainings"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "training_name": "Market Yourself 101",
    "group_name": "Session 2",
    "signature": "Bruce",
    "lang": "en",
    "start_date": "2021-10-11"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$response = $client->post(
    'https://app.awkn.fr/api/trainings',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'training_name' => 'Market Yourself 101',
            'group_name' => 'Session 2',
            'signature' => 'Bruce',
            'lang' => 'en',
            'start_date' => '2021-10-11',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

import requests
import json

url = 'https://app.awkn.fr/api/trainings'
payload = {
    "training_name": "Market Yourself 101",
    "group_name": "Session 2",
    "signature": "Bruce",
    "lang": "en",
    "start_date": "2021-10-11"
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.json()

Example response (200):


{
    "id": 2053,
    "training_name": "From Zero to Hero",
    "group_name": "Session 2",
    "start_date": "2021-10-11",
    "logo": null,
    "lang": "en",
    "created_at": "2021-10-11 17:56:01",
    "active_status": 0,
    "template_status": false,
    "archive_status": false,
    "signature": "Bruce Wayne"
}

Received response:

Request failed with error:

Request

POST api/trainings

Body Parameters

training_name string

Title of the journey.

group_name string

Group name of the journey.

signature string optional

nullable Set the default signature.

lang string

Set language for the recipients. At the moment, can be "fr" for French or "en" for English.

start_date date

The expected start date for the new journey, format YYYY-MM-DD.

Duplicate an existing journey

This call will duplicate an existing journey (that belongs to the user) with a new given start date and a new name. Duplication will copy all steps and all contents linked to the original journey and will recompute all sending dates for each step. Duplication will not copy the recipients attached to the former journey.

Example request:

curl --request POST \
    "https://app.awkn.fr/api/trainings/occaecati/duplicate" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"training_name\": \"Market Yourself in 2022\",
    \"group_name\": \"Session 5\",
    \"start_date\": \"2022-10-11\"
}"

const url = new URL(
    "https://app.awkn.fr/api/trainings/occaecati/duplicate"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "training_name": "Market Yourself in 2022",
    "group_name": "Session 5",
    "start_date": "2022-10-11"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$response = $client->post(
    'https://app.awkn.fr/api/trainings/occaecati/duplicate',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'training_name' => 'Market Yourself in 2022',
            'group_name' => 'Session 5',
            'start_date' => '2022-10-11',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

import requests
import json

url = 'https://app.awkn.fr/api/trainings/occaecati/duplicate'
payload = {
    "training_name": "Market Yourself in 2022",
    "group_name": "Session 5",
    "start_date": "2022-10-11"
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.json()

Example response (200):


{
    "id": 2054,
    "training_name": "From Zero to Hero",
    "group_name": "Session 5",
    "logo": null,
    "lang": "en",
    "created_at": "2022-10-11 17:56:01",
    "active_status": 0,
    "template_status": null,
    "archive_status": null,
    "signature": "Bruce Wayne"
}

Received response:

Request failed with error:

Update an existing journey

This call updates an existing journey. This is especially useful if you want to launch the given journey (active_status parameter) via the API.

Example request:

curl --request PUT \
    "https://app.awkn.fr/api/trainings/20" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"training_name\": \"Market Yourself in 2022\",
    \"group_name\": \"Session 5\",
    \"signature\": \"Bruce\",
    \"lang\": \"en\",
    \"active_status\": 0
}"

const url = new URL(
    "https://app.awkn.fr/api/trainings/20"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "training_name": "Market Yourself in 2022",
    "group_name": "Session 5",
    "signature": "Bruce",
    "lang": "en",
    "active_status": 0
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$response = $client->put(
    'https://app.awkn.fr/api/trainings/20',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'training_name' => 'Market Yourself in 2022',
            'group_name' => 'Session 5',
            'signature' => 'Bruce',
            'lang' => 'en',
            'active_status' => 0,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

import requests
import json

url = 'https://app.awkn.fr/api/trainings/20'
payload = {
    "training_name": "Market Yourself in 2022",
    "group_name": "Session 5",
    "signature": "Bruce",
    "lang": "en",
    "active_status": 0
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('PUT', url, headers=headers, json=payload)
response.json()

Example response (200):


{
    "id": 526,
    "training_name": "From Zero To Hero",
    "group_name": "DC Comics",
    "start_date": "2021-10-11",
    "logo": "https://app.awkn.fr/storage/logos/batman_logo.png",
    "lang": "en",
    "created_at": "2020-02-07 12:04:02",
    "active_status": 0,
    "template_status": false,
    "archive_status": false,
    "signature": "Bruce Wayne"
}

Received response:

Request failed with error:

Request

PUT api/trainings/{id}

URL Parameters

id integer

This is the ID of the Journey you want to update.

Body Parameters

training_name string optional

The name of the new journey.

group_name string optional

The group name for the new journey.

signature string optional

nullable Set the default signature.

lang string optional

Set language for the recipients. At the moment, can be "fr" for French or "en" for English.

active_status integer optional

Set active status for the journey. Can be 0 (not active, deafult via the API) or 1 (active).

Get all recipients details including analytics for a specific journey

This call will return all analytics for all recipients still in database linked for a provided Journey id. Analytics are computed on the fly so this call can be power hungry. Please be responsible and smart. In most use cases, you should not need more than one call per day.

Example request:

curl --request GET \
    --get "https://app.awkn.fr/api/trainings/2/analytics" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://app.awkn.fr/api/trainings/2/analytics"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://app.awkn.fr/api/trainings/2/analytics',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

import requests
import json

url = 'https://app.awkn.fr/api/trainings/2/analytics'
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.json()

Example response (200):


{
    "id": 526,
    "first_name": "Adrien",
    "last_name": "MAUREL",
    "email": "adrien.m@email.com",
    "journey_steps_count": 15,
    "sent_steps_count": 9,
    "open_rate": 0.95,
    "click_rate": 0.87,
    "completion_rate": 0.67,
    "mcq_avg_rate": 1,
    "time_spent_in_seconds": 1821,
    "first_login": "2020-12-11 11:01:53",
    "last_login": "2021-03-07 12:51:43"
}

Received response:

Request failed with error:

Add a new recipient to a Journey

This call will create and add a new recipient (aka a contact) to the provided journey. You must provide an email, a First Name and a Last Name. Please note that you cannot create a new recipient if there is already a recipient with the same email attached to the same journey. All recipients added via this method will have a 'follow mode' set to 'pace', ie they will not receive the steps based on the calendar dates used for the steps, but rather based on the interval in working days between each step.

Example request:

curl --request POST \
    "https://app.awkn.fr/api/trainings/unde/contacts" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"email\": \"brucewayne@gotham.com\",
    \"first_name\": \"Bruce\",
    \"last_name\": \"Wayne\"
}"

const url = new URL(
    "https://app.awkn.fr/api/trainings/unde/contacts"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "email": "brucewayne@gotham.com",
    "first_name": "Bruce",
    "last_name": "Wayne"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$response = $client->post(
    'https://app.awkn.fr/api/trainings/unde/contacts',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'email' => 'brucewayne@gotham.com',
            'first_name' => 'Bruce',
            'last_name' => 'Wayne',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

import requests
import json

url = 'https://app.awkn.fr/api/trainings/unde/contacts'
payload = {
    "email": "brucewayne@gotham.com",
    "first_name": "Bruce",
    "last_name": "Wayne"
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.json()

Example response (200):


{
    "id": 42,
    "first_name": "Bruce",
    "last_name": "Wayne",
    "email": "brucewayne@gotham.com",
    "blocked_status": 0,
    "created_at": "2021-10-11 18:13:16"
}

Received response:

Request failed with error:

Update an existing recipient

This call will update an existing recipient/contact of a given journey.

Example request:

curl --request PUT \
    "https://app.awkn.fr/api/trainings/est/contacts/aspernatur" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"email\": \"batman@gotham.com\",
    \"first_name\": \"Bruce\",
    \"last_name\": \"Wayne\",
    \"blocked_status\": 0
}"

const url = new URL(
    "https://app.awkn.fr/api/trainings/est/contacts/aspernatur"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "email": "batman@gotham.com",
    "first_name": "Bruce",
    "last_name": "Wayne",
    "blocked_status": 0
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$response = $client->put(
    'https://app.awkn.fr/api/trainings/est/contacts/aspernatur',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'email' => 'batman@gotham.com',
            'first_name' => 'Bruce',
            'last_name' => 'Wayne',
            'blocked_status' => 0,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

import requests
import json

url = 'https://app.awkn.fr/api/trainings/est/contacts/aspernatur'
payload = {
    "email": "batman@gotham.com",
    "first_name": "Bruce",
    "last_name": "Wayne",
    "blocked_status": 0
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('PUT', url, headers=headers, json=payload)
response.json()

Example response (200):


{
    "id": 42,
    "first_name": "Bruce",
    "last_name": "Wayne",
    "email": "batman@gotham.com",
    "blocked_status": 0,
    "created_at": "2021-10-11 18:13:16"
}

Received response:

Request failed with error:

Request

PUT api/trainings/{id}/contacts/{contact_id}

URL Parameters

id string

The ID of the journey.

contact_id string

The ID of the recipient.

Body Parameters

email string optional

The email of the recipient.

first_name string optional

The first name of the recipient.

last_name string optional

The last name of the recipient.

blocked_status integer optional

Whether the recipient is blocked (value 1) from receiving emails or not (value 0). Default is 0.

Delete an existing recipient

This call will delete an existing recipient/contact of a given journey. Be careful as the operation is definitive and will delete all related analytics.

Example request:

curl --request DELETE \
    "https://app.awkn.fr/api/trainings/quo/contacts/molestiae" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://app.awkn.fr/api/trainings/quo/contacts/molestiae"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$response = $client->delete(
    'https://app.awkn.fr/api/trainings/quo/contacts/molestiae',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

import requests
import json

url = 'https://app.awkn.fr/api/trainings/quo/contacts/molestiae'
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('DELETE', url, headers=headers)
response.json()

Received response:

Request failed with error: