NAV
API v1.0
PHP

API Documentation v2.5

You can reach the API v1.0 documentation at: https://docs.eggup.co/v1.

Changelog

API Reference

API v2.5 Production Endpoint:

https://api.v2.eggup.co/

API v2.5 Development Endpoint:

https://api.v2.dev.eggup.co/

Welcome to the Eggup API documentation.

Our API is organized around REST. You can use our API to access endpoints, which can get and post information to get soft skills analysis integrated in your platform!

You can view code examples in the dark area to the right, at this moment we only have PHP, more will come.

Environments

We provide a Sandbox environment to be used while developing your integration with Eggup. You can reach the development server from the following endpoint: https://api.v2.dev.eggup.co/

Response formats

Example request URL for JSON response format:

https://api.v2.eggup.co/json/

Example request URL for XML response format:

https://api.v2.eggup.co/xml/

The Eggup API provides three different response formats: XML, JSON, and serialized PHP.

You can request the different formats by substituting JSON, PHP or XML in the request URLs.

Postman

Example JSON configuration file of Postman environment for Eggup API v2.2, containing params for endpoint and private/public key-pairs.

{
    "name": "Eggup.co v2.5",
    "values": [
        {
            "key": "endpoint",
            "value": "https://api.v2.eggup.co/json",
            "enabled": true
        },
        {
            "key": "keyPublic",
            "value": "yourKeyPublic",
            "enabled": true
        },
        {
            "key": "keyPrivate",
            "value": "yourKeyPrivate",
            "enabled": true
        }
    ],
    "_postman_variable_scope": "environment",
    "_postman_exported_using": "Postman/7.9.0"
}

Postman is a collaborative platform for API development and testing. We provide a full collection of our API v2.2 methods to be consumed on Postman. Remember to configure the Sandbox and production environments, you can download this configuration JSON from Eggup, once you are logged in, section API -> Postman.

Server replies

Example response in JSON format for method user.get:

{
    "status": 0,
    "result": {
        "success": true,
        "user": {
            "name": "API user",
            "username": "apiuser",
            "email": "apiuser@eggup.co",
            "metadata": {
                "metadata1": 1,
                "key": "meta2"
            }
        }
    }
}

Example response error in JSON format for method user.create:

{
    "status": 0,
    "result": {
        "success": false,
        "message": "Error 104: This user is not associated with the company."
    }
}

Server will respond with a result packet containing a number of fields.

The format of this reply depends on the format requested:

The server result will be returned, serialised in the requested format (XML, PHP or JSON).

HMAC Authentication

The Eggup API use HMAC authentication to ensure data integrity, this involves both the public and private key.

Examlpe of functions to build an API call:

<?php
/**
 * Send a raw API call to an eggup api endpoint.
 *
 * @param array  $keys         The api keys.
 * @param string $url          URL of the endpoint.
 * @param array  $call         Associated array of "variable" => "value"
 * @param string $method       GET or POST
 * @param string $post_data    The post data
 * @param string $content_type The content type
 *
 * @return string
 */
function eggup_send_api_call(array $keys, $url, array $call, $method = 'GET',
        $post_data = '', $content_type = 'application/octet-stream') {

    $headers = array();
    $encoded_params = array();

    $method = strtoupper($method);
    switch (strtoupper($method)) {
      case 'GET' :
      case 'POST' :
        break;
      default:
        //throw exception
    }
    // Time
    $time = time();
    // Nonce
    $nonce = uniqid('');
    // URL encode all the parameters
    foreach ($call as $k => $v) {
        if (is_null($v)) {
            continue;
        }

        if (is_array($v)) {
            $encoded_params[] = encode_array($v, $k, true);
        } else {
            $encoded_params[] = urlencode($k) . '=' . urlencode($v);
        }
    }

    $params = implode('&', $encoded_params);

    // Put together the query string
    $url = $url . "?" . $params;
    // Construct headers
    $posthash = "";
    if ($method == 'POST') {
      $posthash = calculate_posthash($post_data, 'md5');
    }

    if ((isset($keys['public'])) && (isset($keys['private']))) {
      $headers['X-eggup-apikey'] = $keys['public'];
      $headers['X-eggup-time'] = $time;
      $headers['X-eggup-nonce'] = $nonce;
      $headers['X-eggup-hmac-algo'] = 'sha1';
      $headers['X-eggup-hmac'] = calculate_hmac('sha1',
        $time,
        $nonce,
        $keys['public'],
        $keys['private'],
        $params,
        $posthash
      );
    }
    if ($method == 'POST') {
      $headers['X-eggup-posthash'] = $posthash;
      $headers['X-eggup-posthash-algo'] = 'md5';

      $headers['Content-type'] = $content_type;
      $headers['Content-Length'] = strlen($post_data);
    }

    // Opt array
    $http_opts = array(
      'method' => $method,
      'header' => serialise_api_headers($headers)
    );
    if ($method == 'POST') {
      $http_opts['content'] = $post_data;
    }

    $opts = array('http' => $http_opts);
    // Send context
    $context = stream_context_create($opts);
    // Send the query and get the result and decode.
    $results = file_get_contents($url, false, $context);

    return $results;
}

/**
 * Calculate the HMAC for the http request.
 * This function signs an api request using the information provided. The signature returned
 * has been base64 encoded and then url encoded.
 *
 * @param string $algo          The HMAC algorithm used
 * @param string $time          String representation of unix time
 * @param string $nonce         Nonce
 * @param string $api_key       Your api key
 * @param string $secret_key    Your private key
 * @param string $get_variables URLEncoded string representation of the get variable parameters,
 *                              eg "method=user&guid=2"
 * @param string $post_hash     Optional sha1 hash of the post data.
 *
 * @return string The HMAC signature
 * @access private
 */
function calculate_hmac($algo, $time, $nonce, $api_key, $secret_key,
    $get_variables, $post_hash = "") {

    $ctx = hash_init($algo, HASH_HMAC, $secret_key);

    hash_update($ctx, trim($time));
    hash_update($ctx, trim($nonce));
    hash_update($ctx, trim($api_key));
    hash_update($ctx, trim($get_variables));
    if (trim($post_hash) != "") {
      hash_update($ctx, trim($post_hash));
    }

    return urlencode(base64_encode(hash_final($ctx, true)));
}

/**
 * Calculate a hash for some post data.
 *
 * @todo Work out how to handle really large bits of data.
 *
 * @param string $postdata The post data.
 * @param string $algo     The algorithm used.
 *
 * @return string The hash.
 * @access private
 */
function calculate_posthash($postdata, $algo) {

    $ctx = hash_init($algo);

    hash_update($ctx, $postdata);

    return hash_final($ctx);
}

/**
 * Encode an array as string to be sended as URLs parameter
 *
 * @param array  $arr          The array to be encoded
 * @param string $perfix       Optional prefix to be used
 *
 * @return string
 */
function encode_array($arr, $prefix = null){
    if (!is_array($arr)) {
        return $arr;
    }
    $r = array();
    foreach ($arr as $k => $v) {
        if (is_null($v)) {
            continue;
        }

        if ($prefix && $k && !is_int($k)) {
            $k = $prefix."[".$k."]";
        } elseif ($prefix) {
            $k = $prefix."[]";
        }

        if (is_array($v)) {
            $r[] = encode_array($v, $k, true);
        } else {
            $r[] = urlencode($k)."=".urlencode($v);
        }
    }

    return implode("&", $r);
}

/**
 * Utility function to serialise a header array into its text representation.
 *
 * @param array $headers The array of headers "key" => "value"
 *
 * @return string
 * @access private
 */
function serialise_api_headers(array $headers) {
    $headers_str = "";

    foreach ($headers as $k => $v) {
        $headers_str .= trim($k) . ": " . trim($v) . "\r\n";
    }

    return trim($headers_str);
}
?>

With a HMAC signature scheme for API authentication, the client must send the HMAC signature together with a set of special HTTP headers when making a call that requires API authentication. This ensures that the API call is being made from the stated client and that the data has not been tampered with.

The HMAC must be constructed over the following data:

Some extra information must be added to the HTTP header in order for this data to be correctly processed:

Parameter Description
X-eggup-apikey The public API key.
X-eggup-time Unix time used in the HMAC calculation.
X-eggup-nonce A random string.
X-eggup-hmac The HMAC as base64 encoded.
X-eggup-hmac-algo The algorithm used in the HMAC calculation - eg, sha1, md5 etc.

If you are sending POST data you must also send:

Parameter Description
X-eggup-posthash The hash of the POST data.
X-eggup-posthash-algo The algorithm used to produce the POST data hash - eg, md5.
Content-type The content type of the data you are sending (if in doubt use application/octet-stream).
Content-Length The length in bytes of your POST data.

Eggup provides a sample API client that implements this HMAC signature:

eggup_send_api_call().

It serves as a good reference on how to implement it, see the code area on the right.

Sequence Diagrams

Hybrid integration (API + WebApp)

The sequence diagram for delivering a soft assessment in hybrid implementations is shown in the following figure:

alt Sequence Diagram for hybrid implementation.

Open Diagram in a new window

Exposed methods

Use the param method to specify the function you are going to call:

https://api.v2.eggup.co/json/?method=user.create

Eggup API provides a set of low level methods to complete a end-to-end process for soft skills analysis.

In order to call a function you have to use the param method, the following table shows the list of available methods with their purpose.

Method Mode Description
user.create POST Create a new user account.
user.update POST Update a user account, change name, email, password or metadata.
user.get GET Retrive a user account with the associated data and scores, if available.
user.delete POST Delete a user account.
user.login (NEW in v2.3) POST Get a token for a user to log into the eggup WebApp.
traits.list (UPDATED in v2.4) GET Get the list of analysable personality traits.
test.build (UPDATED in v2.2) POST Send a creation request specifying the list of traits that compose the new test.
traits.macro (NEW in v2.1) POST Create a new macro-trait for a given hash-ID to be used as output variable.
test.delete POST Delete a created custom test from your list.
test.list (UPDATED in v2.5) GET Get the list of the created custom test with their hash-ID.
test.get (UPDATED in v2.4) GET Get an array of elements containing all the questions for a given hash-ID.
test.post POST Send a set of answers for a given hash-ID and user-ID.
test.question GET Get the last question to be answered for a given user-ID and hash-ID.
test.answer POST Send the answer for a given question, hash-ID and user-ID.
test.image (NEW in v2.4) POST Equivalent of test.question to deliver a questionnaire through images.
test.session (UPDATED in v2.5) POST Instantiate a test session for a specific user and questionnaire.
test.score (NEW in v2.3) GET Get a set of scores for a specific user.
test.stats (NEW in v2.5) GET Get a set of scores using custom filtering with one-level attribute metadata over session test.
report (UPDATED in v2.2) POST Get the PDF report for a given user-ID and hash-ID.
smartcoach.seeds (NEW in v2.2) GET Get a list of learning-seeds to enable a self development path with SmartCoach.

User methods

In this section we are going to explain the exposed functions to create and manage user entities.

user.create

POST

The above example shows how to implement the user.create method using the function eggup_send_api_call() over JSON:

<?php
$keys = array(
    "public"  => "yourPublicKey",
    "private" => "yourPrivateKey");

$url = "https://api.v2.eggup.co/json";

$call = array(
    "method"   => "user.create",
    "name"     => "API user",
    "email"    => "apiuser@eggup.co",
    "username" => "apiuser",
    "password" => "userpassword",
    "metadata" => array(
        "metadata1" => 1,
        "key2"      => "meta2"
    ),
    "language" => "en"
);

$json_string = eggup_send_api_call($keys, $url, $call, 'POST');
?>

Make sure to replace yourPublicKey and yourPrivateKey with your API keys.

Example response:

{
    "status": 0,
    "result": {
        "success": true,
        "user_guid": 26600
    }
}

This method is used to create (register) a user account over API, the following table explains the required and optional params.

Param Description
name String - required
The complete name of the user (name and lastname), it will be used as title inside the PDF report.
email String - required
The email to be associated to the user account.
username String - required
The username of the new account.
It must be between 4 and 128 characters long.
\ ' / \ \" * & ? # % ^ ( ) { } [ ] ~ ? < > ; | ¬ @ - + = ` chars are not allowed.
password String - required
The password of the new account.
It must be at least 6 characters.
metadata Array - (optional)
Optional metadata to be associated with the user account.
language String - (optional)
Set the user default language. (en, it)

user.update

POST

The above example shows how to implement the user.update method using the function eggup_send_api_call() over JSON:

<?php
$keys = array(
    "public"  => "yourPublicKey",
    "private" => "yourPrivateKey");

$url = "https://api.v2.eggup.co/json";

$call = array(
    "method"    => "user.update",
    "user_guid" => 26600,
    "name"      => "API user",
    "email"     => "apiuser@eggup.co",
    "password"  => "userpassword",
    "metadata"  => array(
        "metadata1" => "metadata1",
        "key2"      => "metadata2"
    ),
    "language"  => "en"
);

$json_string = eggup_send_api_call($keys, $url, $call, 'POST');
?>

When using eggup_send_api_call() remember to change the fourth param according to the type of call: GET/POST.

Example response:

{
    "status": 0,
    "result": {
        "success": true,
        "user": {
            "user_guid": 26600,
            "name": "API user",
            "username": "apiuser",
            "email": "apiuser@eggup.co",
            "metadata": {
                "metadata1": "metadata1",
                "key2": "metadata2"
            },
            "language": "it"
        }
    }
}

This method is used to update a user account, the following table explains the required and optional params.

Param Description
user_guid Integer - required
The user GUID of the account to be updated.
name String - (optional)
The complete name of the user (name and lastname), it will be used as title inside the PDF report.
email String - (optional)
The email to be associated to the user account.
password String - (optional)
The password of the new account.
metadata Array - (optional)
Optional metadata to be associated with the user account.
language String - (optional)
Set the user default language. (en, it)

user.get

GET

The above example shows an implementation of the user.get method using the function eggup_send_api_call() over JSON:

<?php

$keys = array(
    "public"  => "yourPublicKey",
    "private" => "yourPrivateKey");

$url = "https://api.v2.eggup.co/json";

$call = array(
    "method"    => "user.get",
    "user_guid" => 26600,
    "language"  => "en"
);

$json_string = eggup_send_api_call($keys, $url, $call, 'GET');
?>

Example response:

{
    "status": 0,
    "result": {
        "success": true,
        "user": {
            "user_guid": 26600,
            "name": "API user",
            "username": "apiuser",
            "email": "apiuser@eggup.co",
            "metadata": {
                "metadata1": "metadata1",
                "key2": "metadata2"
            },
            "language": "it"
        },
        "scores": {

            ...
            ...

        }
    }
}

This method is used to retrive user account data over API, the following table explains the required and optional params.

Param Description
user_guid Integer - required
The user-ID of the account.
language String - (optional)
It forces the response to be in the chosen language instead of company account default (en, it, hr).

user.delete

POST

The above example shows an implementation of the user.delete method using the function eggup_send_api_call() over JSON:

<?php
$keys = array(
    "public"  => "yourPublicKey",
    "private" => "yourPrivateKey");

$url = "https://api.v2.eggup.co/json";

$call = array(
    "method"    => "user.delete",
    "user_guid" => 26600,
    "language"  => "en"
);

$json_string = eggup_send_api_call($keys, $url, $call, 'POST');
?>

Example response:

{
    "status": 0,
    "result": {
        "success": true
    }
}

This method is used to delete a user account and all the associated data, the following table explains the required and optional params.

Param Description
user_guid Integer - required
The user-ID of the account to be deleted.
language String - (optional)
It forces the response to be in the chosen language instead of company account default (en, it, hr).

user.login (NEW IN v2.3)

POST

The above example shows an implementation of the user.login method using the function eggup_send_api_call() over JSON:

<?php
$keys = array(
    "public"  => "yourPublicKey",
    "private" => "yourPrivateKey");

$url = "https://api.v2.eggup.co/json";

$call = array(
    "method"    => "user.login",
    "user"      => "apiuser",
    "password"  => "userpassword",
    "language"  => "en"
);

$json_string = eggup_send_api_call($keys, $url, $call, 'POST');
?>

Example response:

{
    "status": 0,
    "result": {
        "success": true,
        "token_login": "4gff2g5d154qz315715d949r5ha58f1n"
    }
}

This method is used to log in a end-user to the eggup WebApp in a transparent way. By indicating the user credentials, username and password, it is possible to request the access token for autologin. This token must be added to the URL as GET param with name token_login.

Param Description
user String - required
The username of the user to be logged.
password String - required
The user account password.
language String - (optional)
It forces the response to be in the chosen language instead of company account default (en, it, hr).

Test methods

The methods below are used for the creation and completion of a test by a user. As first step the test must be created on your company profile, starting from the list of personality traits to be analyzed. The method traits.list return the list of all the traits available for the analysis, each one associated with its questionnaire and theory. With the function test.build you can send back a collection of traits ID to build your custom test, will be returned an ID, that from this moment on you can use to identify this custom questionnaire.

The completion of the questionnaire can be done in two ways:

Let's see all these methods in details.

traits.list (UPDATED in v2.4)

GET

The above example shows an implementation of the traits.list method using the function eggup_send_api_call() over JSON:

<?php
$keys = array(
    "public"  => "yourPublicKey",
    "private" => "yourPrivateKey");

$url = "https://api.v2.eggup.co/json";

$call = array(
    "method"   => "traits.list",
    "sort"     => "test",
    "language" => "en"
);

$json_string = eggup_send_api_call($keys, $url, $call, 'GET');
?>

Example response with default sort "sort" => "trait":

{
    "status": 0,
    "result": {
        "success": true,
        "traits_count": 424,
        "traits": {
            "ACH": {
                "6FPQ": {
                    "test_id": "6FPQ",
                    "test_name": "Six Factor Personality Questionnaire",
                    "trait_id": "ACH",
                    "trait_name": "Achievement Striving",
                    "description": " ... ",
                    "alpha": 82,
                    "items_count": 10,
                    "portrait": false
                },
                "NEO-PI-R-F": {
                    "test_id": "NEO-PI-R-F",
                    "test_name": "NEO-PI-R Facets",
                    "trait_id": "ACH",
                    "trait_name": "Achievement Striving",
                    "description": " ... ",
                    "alpha": 78,
                    "items_count": 10,
                    "portrait": false
                },
                "NEO-PI-R-J": {
                    "test_id": "NEO-PI-R-J",
                    "test_name": "120-item IPIP NEO-PI-R",
                    "trait_id": "ACH",
                    "trait_name": "Achievement Striving",
                    "description": " ... ",
                    "alpha": 79,
                    "items_count": 4,
                    "portrait": true
                },
                "TCI": {
                    "test_id": "TCI",
                    "test_name": "Temperament and Character Inventory",
                    "trait_id": "ACH",
                    "trait_name": "Achievement Striving",
                    "description": " ... ",
                    "alpha": 78,
                    "items_count": 10,
                    "portrait": true
                }
            },
            "ACS": {
                "MPQ": {
                    "test_id": "MPQ",
                    "test_name": "Multidimensional Personality Questionnaire",
                    "trait_id": "ACS",
                    "trait_name": "Achievement Seeking",
                    "description": " ... ",
                    "alpha": 79,
                    "items_count": 10,
                    "portrait": false
                }
            }

            ...
            ...

        }
    }
}

Example response with "sort" => "test":

{
    "status": 0,
    "result": {
        "success": true,
        "traits_count": 424,
        "traits": {
            "6FPQ": {
                "ACH": {
                    "test_id": "6FPQ",
                    "test_name": "Six Factor Personality Questionnaire",
                    "trait_id": "ACH",
                    "trait_name": "tratto ITA",
                    "description": "Descrizione ITA",
                    "alpha": 82,
                    "items_count": 10,
                    "portrait": false
                },
                "ADA": {
                    "test_id": "6FPQ",
                    "test_name": "Six Factor Personality Questionnaire",
                    "trait_id": "ADA",
                    "trait_name": "tratto ITA",
                    "description": "Descrizione ITA",
                    "alpha": 67,
                    "items_count": 8,
                    "portrait": false
                },

                ...
                ...

                "SSU": {
                    "test_id": "6FPQ",
                    "test_name": "Six Factor Personality Questionnaire",
                    "trait_id": "SSU",
                    "trait_name": "tratto ITA",
                    "description": "Descrizione ITA",
                    "alpha": 59,
                    "items_count": 10,
                    "portrait": false
                },
                "UNP": {
                    "test_id": "6FPQ",
                    "test_name": "Six Factor Personality Questionnaire",
                    "trait_id": "UNP",
                    "trait_name": "tratto ITA",
                    "description": "Descrizione ITA",
                    "alpha": 74,
                    "items_count": 9,
                    "portrait": false
                }
            },
            "7-FACTOR": {
                "AGR": {
                    "test_id": "7-FACTOR",
                    "test_name": "7-factor ranges",
                    "trait_id": "AGR",
                    "trait_name": "tratto ITA",
                    "description": "Descrizione ITA",
                    "alpha": 77,
                    "items_count": 10,
                    "portrait": false
                },
                "ATT": {
                    "test_id": "7-FACTOR",
                    "test_name": "7-factor ranges",
                    "trait_id": "ATT",
                    "trait_name": "tratto ITA",
                    "description": "Descrizione ITA",
                    "alpha": 66,
                    "items_count": 10,
                    "portrait": true
                }

                ...
                ...

            },
            "AB5C": {
                "AST": {
                    "test_id": "AB5C",
                    "test_name": "45 AB5C facets",
                    "trait_id": "AST",
                    "trait_name": "tratto ITA",
                    "description": "Descrizione ITA",
                    "alpha": 75,
                    "items_count": 12,
                    "portrait": false
                },
                "CAL": {
                    "test_id": "AB5C",
                    "test_name": "45 AB5C facets",
                    "trait_id": "CAL",
                    "trait_name": "tratto ITA",
                    "description": "Descrizione ITA",
                    "alpha": 83,
                    "items_count": 10,
                    "portrait": false
                }

            ...
            ...

            }
        }
    }
}

This function return the list of all available traits from different questionnaire and theory. The returned [traits] array contains the list of the available traits, with their trait_id to be used to build a custom test with test.build method. With the sort param you can change the hierarchy of the response array, from test_id => [traits] to trait_id => [tests].

Param Description
sort String - (optional)
Change the output structure hierarchy (default:"trait", "test").
language String - (optional)
It forces the response to be in the chosen language instead of company account default (en, it, hr).

See the example for a detailed view of the response data structure.

test.build (UPDATED IN v2.2)

POST

The above example shows an implementation of the test.build method using the function eggup_send_api_call() over JSON:

<?php
$keys = array(
    "public"  => "yourPublicKey",
    "private" => "yourPrivateKey");

$url = "https://api.v2.eggup.co/json";

$call = array(
    "method"      => "test.build",
    "traits"      => array(
        "6FPQ"      => "SSU,RES",
        "AB5C"      => "COO,WAR,QUI,EFF,CRE,LEA",
        "BFA"       => "INT",
        "CPI"       => "HAP,AST,INS,SEF,FOR",
        "HEXACO"    => "SBO,FLE",
        "HPI"       => "SCI",
        "JPI"       => "EMP,SCN,ING,RIT,INB",
        "MPQ"       => "PLA",
        "TCI"       => "CPT,INI,ACH",
        "VIA"       => "SCL,CIT,KIN,IND,LEA,LOV,VAL,ZES",
        "BIG5-20"   => "EMO,ENE,FRI,INT,RSP"
    ),
    "name"        => "My custom test",
    "description" => "Test Description",
    "language"    => "en"
);

$json_string = eggup_send_api_call($keys, $url, $call, 'POST');
?>

With ideal scores defined (v2.2 update):

<?php
$keys = array(
    "public"  => "yourPublicKey",
    "private" => "yourPrivateKey");

$url = "https://api.v2.eggup.co/json";

$call = array(
    "method"      => "test.build",
    "traits"      => array(
        "6FPQ"      => "SSU:76,RES:82",
        "AB5C"      => "COO:78,WAR:79,QUI:72,EFF:69,CRE:75,LEA:69",
        "BFA"       => "INT:75",
        "CPI"       => "HAP:78,AST:76,INS:83,SEF:66,FOR:78",
        "HEXACO"    => "SBO:82,FLE:76",
        "HPI"       => "SCI:65",
        "JPI"       => "EMP:62,SCN:69,ING:68,RIT:83,INB:82",
        "MPQ"       => "PLA:72",
        "TCI"       => "CPT:74,INI:85,ACH:73",
        "VIA"       => "SCL:59,CIT:79,KIN:72,IND:76,LEA:78,LOV:90,VAL:89,ZES:83",
        "BIG5-20"   => "EMO:65,ENE:56,FRI:65,INT:81,RSP:78"
    ),
    "name"        => "My custom test",
    "description" => "Test Description",
    "language"    => "en"
);

$json_string = eggup_send_api_call($keys, $url, $call, 'POST');
?>

Example response:

{
    "status": 0,
    "result": {
        "success": true,
        "hash_id": "1B7F2A5D15643315715D949E59A5801B",
        "name": "My scustom test",
        "description": "Test description"
    }
}

This method is used to build a custom test from a list of trait ids. Select each trait_id as a comma separated list, use the test_id as array key which the traits referes to.

You will receive a unique hash_id which will identify this test from now on. Use name and description attribute to better identify the custom test in the future.

Param Description
traits Array - required
The list of traits to be used to build this custom test, as "test_id" => "trait1,trait2,.."
name String - (optional)
A name to identify this custom test.
description String - (optional)
A description of this custom test.
language String - (optional)
It forces the response to be in the chosen language instead of company account default (en, it, hr).

See the example for a detailed view of the response data structure.

test.delete

POST

The above example shows an implementation of the test.delete method using the function eggup_send_api_call() over JSON:

<?php
$keys = array(
    "public"  => "yourPublicKey",
    "private" => "yourPrivateKey");

$url = "https://api.v2.eggup.co/json";

$call = array(
    "method"   => "test.delete",
    "hash_id"  => "1B7F2A5D15643315715D949E59A5801B",
    "language" => "en"
);

$json_string = eggup_send_api_call($keys, $url, $call, 'POST');
?>

Example response:

{
    "status": 0,
    "result": {
        "success": true
    }
}

This function delete a custom test from company list.

Param Description
hash_id String - required
The hash-ID to be deleted.
language String - (optional)
It forces the response to be in the chosen language instead of company account default (en, it, hr).

See the example for a detailed view of the response data structure.

test.list (UPDATED in v2.5)

GET

The above example shows an implementation of the test.list method using the function eggup_send_api_call() over JSON:

<?php
$keys = array(
    "public"  => "yourPublicKey",
    "private" => "yourPrivateKey");

$url = "https://api.v2.eggup.co/json";

$call = array(
    "method"    => "test.list",
    "view"      => "default",
    "language"  => "en"
);

$json_string = eggup_send_api_call($keys, $url, $call, 'GET');
?>

Example response:

{
    "status": 0,
    "result": {
        "success": true,
        "test": {
            "1B7F2A5D15643315715D949E59A5801B": {
                "hash_id": "1B7F2A5D15643315715D949E59A5801B",
                "name": "My custom test",
                "description": "Custom test description",
                "item_count": 285,
                "traits_count": 38,
                "mid_alpha": 77,
                "portrait": false,
                "traits": {
                    "6FPQ": {
                        "RES": "Resourcefulness",
                        "SSU": "Self Sufficiency"
                    },
                    "AB5C": {
                        "COO": "Cooperation",
                        "CRE": "Creativity",
                        "LEA": "Leadership",
                        "QUI": "Quickness",
                        "WAR": "Warmth"
                    },
                    "BFA": {
                        "INT": "Intellect"
                    },
                    "BIG5-20": {
                        "EMO": "Emotional Stability",
                        "ENE": "Energy",
                        "FRI": "Friendliness",
                        "INT": "Intellect",
                        "RSP": "Responsibility"
                    },
                    "CPI": {
                        "AST": "Assertiveness",
                        "FOR": "Forcefulness",
                        "HAP": "Happiness",
                        "INS": "Insight",
                        "SEF": "Self Efficacy"
                    },
                    "HEXACO": {
                        "FLE": "Flexibility",
                        "SBO": "Social Boldness"
                    },
                    "HPI": {
                        "SCI": "Science Ability"
                    },
                    "JPI": {
                        "EMP": "Empathy",
                        "INB": "Intellectual Breadth",
                        "ING": "Ingenuity",
                        "RIT": "Risk Taking",
                        "SCN": "Social Confidence"
                    },
                    "MPQ": {
                        "PLA": "Planfulness"
                    },
                    "TCI": {
                        "ACH": "Achievement Striving",
                        "CPT": "Competence",
                        "INI": "Initiative"
                    },
                    "VIA": {
                        "CIT": "Citizenship",
                        "IND": "Industry",
                        "KIN": "Kindness",
                        "LEA": "Leadership",
                        "LOV": "Love Of Learning",
                        "SCL": "Social",
                        "VAL": "Valor",
                        "ZES": "Zest"
                    }
                }
            },
            "1835E5EB1DA8630CB551A0E03B3C8A65": {

                ...
                ...

            }

            ...
            ...

        }
    }
}

This function return the list of all available custom test that you previously created with the test.build method. For each test is specified the item count, medium alpha, traits count and [traits] array with the list of traits involved.

Param Description
view String - (optional)
Get a light version of the output or a complete one (default, summary).
language String - (optional)
It forces the response to be in the chosen language instead of company account default (en, it, hr).

See the example for a detailed view of the response data structure.

test.get

GET

The above example shows an implementation of the test.get method using the function eggup_send_api_call() over JSON:

<?php
$keys = array(
    "public"  => "yourPublicKey",
    "private" => "yourPrivateKey");

$url = "https://api.v2.eggup.co/json";

$call = array(
    "method"    => "test.get",
    "hash_id"   => "1B7F2A5D15643315715D949E59A5801B",
    "user_guid" => 26660,
    "language"  => "en"
);
$json_string = eggup_send_api_call($keys, $url, $call, 'GET');
?>

Example response:

{
    "status": 0,
    "result": {
        "success": true,
        "name": "My custom test",
        "description": "Custom test description",
        "hash_id": "1B7F2A5D15643315715D949E59A5801B",
        "item_count": 285,
        "traits_count": 38,
        "list": {
            "JWPAB": {
                "question_id": "JWPAB",
                "question": "I have difficulty understanding abstract ideas.",
                "answers": {
                    "1": "Strongly disagree",
                    "2": "Disagree",
                    "3": "Neither agree nor disagree",
                    "4": "Agree",
                    "5": "Strongly agree"
                }
            },
            "BM3YV": {
                "question_id": "BM3YV",
                "question": "I planned a party.",
                "answers": {
                    "1": "Never in my life",
                    "2": "Not in the past year",
                    "3": "One or two times in the past year",
                    "4": "Three to ten times in the past year",
                    "5": "More than ten times in the past year"
                }
            },
            "BOAVK": {
                "question_id": "BOAVK",
                "question": "Be the chief executive of a large company.",
                "answers": {
                    "1": "Strongly dislike",
                    "2": "Dislike",
                    "3": "Neutral",
                    "4": "Like",
                    "5": "Strongly like"
                }
            }

            ...
            ...

        }
    }
}

This method return the [list] of all the questions for a test, for each question the array of eligible answers is specified: numeric to be sent back as answer and text to be shown to the final user.

Each element key is used as question ID, to be used when sending back the answers.

Param Description
hash_id String - required
The hash-ID of the custom test to be requested.
user_guid Integer - required
The user-ID of the account.
language String - (optional)
It forces the response to be in the chosen language instead of company account default (en, it, hr).

See the example for a detailed view of the response data structure.

test.post

POST

The above example shows an implementation of the test.post method using the function eggup_send_api_call() over JSON:

<?php
$keys = array(
    "public"  => "yourPublicKey",
    "private" => "yourPrivateKey");

$url = "https://api.v2.eggup.co/json";

$call = array(
    "method"    => "test.post",
    "hash_id"   => "1B7F2A5D15643315715D949E59A5801B",
    "user_guid" => 26600,
    "answers"   => array(
        "JWPAB"  => 2,
        "BM3YV"  => 1,
        "BOAVK"  => 4,

        ...
        ...

    ),
    "language"  => "en"
);

$json_string = eggup_send_api_call($keys, $url, $call, 'POST');
?>

Example response:

{
    "status": 0,
    "result": {
        "success": true,
        "scores": {
            "1B7F2A5D15643315715D949E59A5801B": {
                "20191016": {
                    "6FPQ": {
                        "RES": {
                            "test_name": "Six Factor Personality Questionnaire",
                            "test_descr": " ... ",
                            "trait_name": "Resourcefulness",
                            "trait_description": " ... ",
                            "value": 85,
                            "range": 100
                        },
                        "SSU": {
                            "test_name": "Six Factor Personality Questionnaire",
                            "test_descr": " ... ",
                            "trait_name": "Self Sufficiency",
                            "trait_description": " ... ",
                            "value": 65,
                            "range": 100
                        }
                    },
                    "AB5C": {
                        "COO": {
                            "test_name": "45 AB5C facets",
                            "test_descr": " ... ",
                            "trait_name": "Cooperation",
                            "trait_description": " ... ",
                            "value": 67,
                            "range": 100
                        },
                        "CRE": {
                            "test_name": "45 AB5C facets",
                            "test_descr": " ... ",
                            "trait_name": "Creativity",
                            "trait_description": " ... ",
                            "value": 77,
                            "range": 100
                        }
                    }

                    ...
                    ...

                }
            }
        }
    }
}

This method is used to post the list of all the answers for a single hash-ID and user-ID. It returns a [scores] array containing the results for each trait included inside this custom test.

Param Description
hash_id String - required
The hash-ID of the custom test to be requested.
user_guid Integer - required
The user-ID of the account.
answers Array - required
The array containing the list of all the answers for this test.
language String - (optional)
It forces the response to be in the chosen language instead of company account default (en, it, hr).

See the example for a detailed view of the response data structure.

test.question

GET

The above example shows an implementation of the test.question method using the function eggup_send_api_call() over JSON:

<?php
$keys = array(
    "public"  => "yourPublicKey",
    "private" => "yourPrivateKey");

$url = "https://api.v2.eggup.co/json";

$call = array(
    "method"    => "test.question",
    "hash_id"   => "1B7F2A5D15643315715D949E59A5801B",
    "user_guid" => 26600,
    "language"  => "en"
);

$json_string = eggup_send_api_call($keys, $url, $call, 'GET');
?>

Example response:

{
    "status": 0,
    "result": {
        "success": true,
        "question": {
            "number": 1,
            "range": 283,
            "question_id": "BG4XM",
            "text": "I want to see things for myself.",
            "answers": {
                "1": "Strongly disagree",
                "2": "Disagree",
                "3": "Neither agree nor disagree",
                "4": "Agree",
                "5": "Strongly agree"
            }
        }
    }
}

This method return the last question for a given hash_id and user_guid.

Param Description
hash_id String - required
The ID of the custom test to be requested.
user_guid Integer - required
The user-ID of the account.
language String - (optional)
It forces the response to be in the chosen language instead of company account default (en, it, hr).

It returns a [question] array containing the current number of the question and the test range, a key text with the text of the question and [answers] as array of available answers.

See the example for a detailed view of the response data structure.

test.answer

POST

The above example shows an implementation of the test.answer method using the function eggup_send_api_call() over JSON:

<?php
$keys = array(
    "public"  => "yourPublicKey",
    "private" => "yourPrivateKey");

$url = "https://api.v2.eggup.co/json";

$call = array(
    "method"      => "test.answer",
    "hash_id"     => "1B7F2A5D15643315715D949E59A5801B",
    "user_guid"   => 26600,
    "question_id" => "BG4XM",
    "answer"      => 3,
    "language"    => "en"
);

$json_string = eggup_send_api_call($keys, $url, $call, 'POST');
?>

Example response:

{
    "status": 0,
    "result": {
        "success": true
    }
}

This method is used to send an answer of a single question for a specific hash-ID and user-ID.

Param Description
hash_id String - required
The ID of the custom test to be requested.
user_guid Integer - required
The user-ID of the account.
question_id String - required
The ID of the question to be answered, as receveid in test.question method.
answer Integer - required
The integer that identifies the answer for the current question.
language String - (optional)
It forces the response to be in the chosen language instead of company account default (en, it, hr).

This function return just a success: true except for the last answer of the current test, in this case the result array contains also the [scores] array, has already described in the test.post function.

traits.macro (NEW IN v2.1)

POST

The above example shows an implementation of the traits.macro method using the function eggup_send_api_call() over JSON:

<?php
$keys = array(
    "public"  => "yourPublicKey",
    "private" => "yourPrivateKey");

$url = "https://api.v2.eggup.co/json";

$call = array(
    "method"         => "traits.macro",
    "name"           => "Change Agent",
    "description"    => "Make balanced yet brave decisions that change the status quo and enhance the business.",
    "hash_id"        => "1B7F2A5D15643315715D949E59A5801B",
    "traits"         => array(
        "TCI"   => "ACH:33.33",
        "CPI"   => "SEF:33.33,FOR:33.33",
    ),
    "input_language" => "en",
    "category"       => "",
    "langugage"      => "en"
);

$json_string = eggup_send_api_call($keys, $url, $call, 'POST');
?>

Example response:

{
    "status": 0,
    "result": {
        "success": true
    }
}

Example response of a test.post method, the macro_traits array is included:

{
    "status": 0,
    "result": {
        "success": true,
        "scores": {
            "1B7F2A5D15643315715D949E59A5801B": {
                "20191016": {
                    "6FPQ": {
                        "RES": {
                            "test_name": "Six Factor Personality Questionnaire",
                            "test_descr": " ... ",
                            "trait_name": "Resourcefulness",
                            "trait_description": " ... ",
                            "value": 85,
                            "range": 100
                        },
                        "SSU": {
                            "test_name": "Six Factor Personality Questionnaire",
                            "test_descr": " ... ",
                            "trait_name": "Self Sufficiency",
                            "trait_description": " ... ",
                            "value": 65,
                            "range": 100
                        }
                    },
                    "AB5C": {
                        "COO": {
                            "test_name": "45 AB5C facets",
                            "test_descr": " ... ",
                            "trait_name": "Cooperation",
                            "trait_description": " ... ",
                            "value": 67,
                            "range": 100
                        },
                        "CRE": {
                            "test_name": "45 AB5C facets",
                            "test_descr": " ... ",
                            "trait_name": "Creativity",
                            "trait_description": " ... ",
                            "value": 77,
                            "range": 100
                        }
                    },

                    ...

                    "macro_traits": [
                        {
                            "macro_name": "Change Agent",
                            "macro_descr": "Make balanced yet brave decisions that change the status quo and enhance the business.",
                            "macro_category": "",
                            "traits_weights": {
                                "TCI": {
                                    "ACH": 33.33
                                },
                                "CPI": {
                                    "FOR": 33.33,
                                    "SEF": 33.33
                                }
                            },
                            "value": 45,
                            "range": 100
                        },
                        {
                            "macro_name": "",
                            "macro_descr": "Strength of Character",
                            "macro_category": "Straightforward, authentic and resilient, use self awareness and empathy to respond to people and situations effectively.",
                            "traits_weights": {
                                "BIG5-20": {
                                    "RSP": 50,
                                    "INT": 50
                                }
                            },
                            "value": 54.2,
                            "range": 100
                        },

                        ...

                    ]
                }
            }
        }
    }
}

This method is used to create a macro trait starting from a list of base traits with a given weight for each one. This new macro trait will be included as output within the array macro_traits inside the scores array.

Param Description
name String - required
The custom name to be used to identify the new macro trait within the output.
description String - required
A description of the new macro trait.
hash_id String - required
The hash-ID of the test where the macro trait has to be used.
traits Array - required
The list of test-ID and trait-ID with their weights to build the macro trait.
input_language String - required
The language which the input refers to (en, it).
category String - (optional)
A custom category for this macro trait, to be used as a filter over the user base.
language String - (optional)
It forces the response to be in the chosen language instead of company account default (en, it, hr).

See the example for a detailed view of the response data structure.

test.session (UPDATED IN v2.5)

POST

The above example shows an implementation of the test.session method using the function eggup_send_api_call() over JSON:

<?php
$keys = array(
    "public"  => "yourPublicKey",
    "private" => "yourPrivateKey");

$url = "https://api.v2.eggup.co/json";

$call = array(
    "method"        => "test.session",
    "user_guid"     => 26600,
    "hash_id"       => "1B7F2A5D15643315715D949E59A5801B",
    "callback_url"  => "https://www.mycallback.com/?getparams=myparam",
    "callback_type" => "server",
    "session_name"  => "Custom session name",
    "portrait"      => true,
    "json_metadata" => '{"key1": "value1","key2": "value2","key3": "value3"}',
    "language"      => "en"
);

$json_string = eggup_send_api_call($keys, $url, $call, 'POST');
?>

Example response:

{
    "status": 0,
    "result": {
        "success": true,
        "token_session": "d160a34041b9d0b38ba44be81c18fb8d",
        "redirect_url" : "https://www.eggup.co/wle/1231/d160a34041b9d0b38ba44be81c18fb8d"
    }
}

This method is used to instantiate a test session for a specific user (user_guid) and questionnaire (hash_id). It returns a token_session to be used to identify the session, it can be used to restore the user session over the WebApp, or to be used with other methods.

Param Description
user_guid Integer - required
The user-ID of the account.
hash_id String - required
The hash-ID of the custom test to be requested.
callback_url String - (optional)
The URL to be called when the user end the questionnaire.
callback_type String - (optional)
The type of call to be used: (server, client), the first is a transparent call for the end-user, the second is a browser redirect.
session_name String - (optional)
The custom name to be used to identify this session on the eggup WebApp.
portrait Bool - (optional)
If set to true the assessment will be delivered using PORTRAIT images (check availability).
json_metadata String - (optional)
JSON metadata object with single-level attributes to cluster and filter results using the test.stats method (E.g. {"key1": "value1","key2": "value2","key3": "value3"} ).
language String - (optional)
It forces the response to be in the chosen language instead of company account default (en, it, hr).

test.score (NEW IN v2.3)

GET

The above example shows an implementation of the test.score method using the function eggup_send_api_call() over JSON:

<?php
$keys = array(
    "public"  => "yourPublicKey",
    "private" => "yourPrivateKey");

$url = "https://api.v2.eggup.co/json";

$call = array(
    "method"        => "test.score",
    "user_guid"     => 26600,
    "hash_id"       => "1B7F2A5D15643315715D949E59A5801B",
    "date_from"     => "",
    "date_to"       => "",
    "token_session" => "d160a34041b9d0b38ba44be81c18fb8d",
    "coverage_index"=> true, 
    "language"      => "en"
);

$json_string = eggup_send_api_call($keys, $url, $call, 'GET');
?>

Example response:

{
    "status": 0,
    "result": {
        "success": true,
        "scores": {
            "1B7F2A5D15643315715D949E59A5801B": {       // hash-id
                "d160a34041b9d0b38ba44be81c18fb8d": {   // session-token
                    "coverage_index": 33,               // if requested
                    "BIG5-20": {
                        "ENE": {
                            "test_name": "BIG5 Theory 20 items",
                            "test_descr": "description … ",
                            "trait_name": "Espansività",
                            "trait_description": "description … ",
                            "value": 50,
                            "range": 100,
                            "date": "20210421",
                            "token_session": "d160a34041b9d0b38ba44be81c18fb8d"
                        },
                        "FRI": {
                            "test_name": "BIG5 Theory 20 items",
                            "test_descr": "description … ",
                            "trait_name": "Amichevolezza",
                            "trait_description": "description … ",
                            "value": 69,
                            "range": 100,
                            "date": "20210421",
                            "token_session": "d160a34041b9d0b38ba44be81c18fb8d"
                        },
                        "INT": {
                            "test_name": "BIG5 Theory 20 items",
                            "test_descr": "description … ",
                            "trait_name": "Intellettualità",
                            "trait_description": "description … ",
                            "value": 31,
                            "range": 100,
                            "date": "20210421",
                            "token_session": "d160a34041b9d0b38ba44be81c18fb8d"
                        }
                    }
                }
            }
        }
    }
}

This method is used to get a set of scores for a specific user.

Param Description
user_guid Integer - required
The user-ID of the account.
hash_id String - (optional)
The hash-ID of the custom test to be requested.
date_from Integer - (optional)
The start date (YYYYMMDD) which you need to get scores from.
date_to Integer - (optional)
The end date (YYYYMMDD) which you need to get scores.
token_session String - (optional)
The token that identify the an assessment session (user and questionnaire).
coverage_index Bool - (optional)
If set to true the output will include the coverage_index value.
language String - (optional)
It forces the response to be in the chosen language instead of company account default (en, it, hr).

This function returns a single or multiple sets of scores for given input configuration.
When using the token_session param, it returns the single set of scores associated to the session questionnaire.

test.image (NEW IN v2.4)

GET

The above example shows an implementation of the test.image method using the function eggup_send_api_call() over JSON:

<?php
$keys = array(
    "public"  => "yourPublicKey",
    "private" => "yourPrivateKey");

$url = "https://api.v2.eggup.co/json";

$call = array(
    "method"    => "test.image",
    "hash_id"   => "0408A6951C2FD69018DB9F42CF546B02",
    "user_guid" => 26600,
    "language"  => "en"
);

$json_string = eggup_send_api_call($keys, $url, $call, 'GET');
?>

Example response:

{
    "status": 0,
    "result": {
        "success": true,
        "question": {
            "number": 1,
            "range": 50,
            "question_id": "VDPNK",
            "text": "How well does this picture describe you?",
            "answers": {
                "1": "Not at all",
                "2": "Not so much",
                "3": "So-so",
                "4": "Enough",
                "5": "A lot"
            },
            "image": "/9j/4AAQSkZJRgABAQAASABIAAD/4QCARXhpZgAATU0AKgAAAAgABAEaAAUAAAABAAAAP ... "
        }
    }
}

This method return the last question for a given hash_id and user_guid using PORTRAIT, which deliver an assessmnent using images.

Param Description
hash_id String - required
The ID of the custom test to be requested.
user_guid Integer - required
The user-ID of the account.
language String - (optional)
It forces the response to be in the chosen language instead of company account default (en, it, hr).

It returns a [question] array containing the current number of the question and the test range, a key text with the text of the question and [answers] as array of available answers.


image contains the image jpeg encoded in base64.
See the example for a detailed view of the response data structure.

test.stats (NEW IN v2.5)

GET

The above example shows an implementation of the test.stats method using the function eggup_send_api_call() over JSON:

<?php
$keys = array(
    "public"  => "yourPublicKey",
    "private" => "yourPrivateKey");

$url = "https://api.v2.eggup.co/json";

$call = array(
    "method"        => "test.stats",
    "user_guid"     => 26600,
    "hash_id"       => "0408A6951C2FD69018DB9F42CF546B02",
    "date_from"     => "20230922",
    "date_to"       => "20230923",
    "session_name"  => "Custom session name",
    "json_metadata" => "",
    "order_by"      => "user_guid:DESC",
    "language"      => "en"
);

$json_string = eggup_send_api_call($keys, $url, $call, 'GET');
?>

Example response:

{
    "status": 0,
    "result": {
        "success": true,
        "scores": [
            {
                "user_guid": "26600",
                "user_email": "info@eggup.co",
                "hash_id": "0408A6951C2FD69018DB9F42CF546B02",
                "session_token": "aacce648530d28d53841daff52649373",
                "date": "1695398324",
                "test_name": "Big5 50 Items",
                "session_name": "Custom session name",
                "json_metadata": null,
                "duration": "1771",
                "coverage_index": "47",
                "data": [
                    {
                        "trait_id": "EMO",
                        "trait_name": "Emotionality",
                        "score": 50
                    },
                    {
                        "trait_id": "INT",
                        "trait_name": "Open Mindedness",
                        "score": 58
                    },
                    {
                        "trait_id": "ENE",
                        "trait_name": "Energy",
                        "score": 50
                    },
                    {
                        "trait_id": "FRI",
                        "trait_name": "Friendliness",
                        "score": 58
                    },
                    {
                        "trait_id": "RSP",
                        "trait_name": "Responsibility",
                        "score": 45
                    }
                ]
            },
        ]
    }
}

This method is used to get a set of scores for a specific set of input filters and order by an attribute.

Param Description
user_guid Integer - required
The user-ID of the account.
hash_id String - (optional)
The hash-ID of the custom test to be requested.
date_from Integer - (optional)
The start date (YYYYMMDD) which you need to get scores from.
date_to Integer - (optional)
The end date (YYYYMMDD) which you need to get scores.
session_name String - (optional)
This param let you filter results based on a custom session name assigned during session creation. This attribute will be used as well on the front-end of Eggup WebApp.
json_metadata String - (optional)
This param let you filter results based on a json object assigned during session creation.
order_by String - (optional)
Order results based on user_guid, hash_id, date, session_name, test_name (Eg: user_guid:DESC).
language String - (optional)
It forces the response to be in the chosen language instead of company account default (en, it, hr).

This function returns an array of scores for given input configuration.

Report methods

report (UPDATED IN v2.5)

POST

The report method can be called in two ways, sending the image logo as string URL:

<?php
$keys = array(
    "public"  => "yourPublicKey",
    "private" => "yourPrivateKey");

$url = "https://api.eggup.co/json";

$call = array(
    "method"        => "report",
    "hash_id"       => "5AB6056D647A152AA5CCD96A4D3169B7",
    "user_guid"     => 26600,
    "name"          => "John Doe",
    "smart_coach"   => "gg",
    "date"          => "20200611",
    "image_url"     => "https://www.eggup.co/eggup_logo.svg",
    "color_hex"     => "#FF7800",
    "token_session" => "d160a34041b9d0b38ba44be81c18fb8d",
    "report_type"   => "hr",
    "language"      => "en"
);

$json_string = eggup_send_api_call($keys, $url, $call, 'POST');
?>

Or sending the image logo as postdata with fifth (and sixth for MIME-type) argument of eggup_send_api_call().

<?php
$keys = array(
    "public"  => "yourPublicKey",
    "private" => "yourPrivateKey");

$url = "https://api.eggup.co/json";

$call = array(
    "method"      => "report",
    "hash_id"     => "5AB6056D647A152AA5CCD96A4D3169B7",
    "user_guid"   => 26600,
    "name"        => "John Doe",
    "smart_coach" => "sg",
    "color_hex"   => "#FF7800",
    "report_type" => "default",
    "language"    => "en"
);

$filename = "mylogo.jpg";

$logo = file_get_contents($filename);

$json_string = eggup_send_api_call($keys, $url, $call, 'POST', $logo, "image/jpg");
?>

Example response:

{
    "status": 0,
    "result": {
        "success": true,
        "md5_checksum": "d63f4072fa72d30b339230bf0a2a22ed",
        "content_length": 128457,
        "mime_type": "application/pdf",
        "pdf_base64": "JVBERi0xLjQKMyAwIG9iago8P ... "
    }
}

This method generate a PDF report for the given hash-ID and user-ID.

The image logo to be included inside the report, can be sent as external URL with the param image_url or as postdata, if both are available, postadata has precedence.
See the eggup_send_api_call() as good reference about how to send post data with http header over HMAC.

v2.3 Update:

Param Description
hash_id String - required
The hash-ID of the custom test of which you want to ask the report for.
user_guid Integer - required
The user-ID of the person who completed this test.
name String - (optional)
Override inside the PDF report, the user name and lastname with given string.
smart_coach String - (optional)
It enables the SmartCoach section inside the report with self-development suggestions over two traits. Possible values are "sg", "ss", "gg" which refer, respectively, to development paths related to strength and growth or to both strength or growth.
date Integer - (optional)
The date of the test completion to be used to build the report, if not specified will be used the last one. (format "yyyymmdd", as received in [scores] array, e.g. "20200611")
color_hex String - (optional)
The color code to be used inside the PDF, in hexadecimal format (default value: "#FF7800").
image_url String - (optional)
The URL of the image logo to be used inside the report PDF. If not present Eggup logo will be used, if set to "nologo", blank report will be generated.
token_session String - (optional)
The token that identify an assessment session (user and questionnaire).
report_type String - (optional)
The type of report you are asking for, "default" or "hr".
language String - (optional)
It forces the response to be in the chosen language instead of company account default (en, it).

The result array include:

Name Description
md5_checkusm String
The md5 checksum of the decoded PDF file.
content_length String
The length of the decoded PDF file.
mime_type String
The MIME type of the file, application/pdf.
pdf_base64 String
The PDF file encoded in base64.

SmartCoach methods

smartcoach.seeds (NEW IN v2.2)

GET

The above example shows an implementation of the smartcoach.seeds method using the function eggup_send_api_call() over JSON:

<?php
$keys = array(
    "public"  => "yourPublicKey",
    "private" => "yourPrivateKey");

$url = "https://api.eggup.co/json";

$call = array(
    "method"     => "smartcoach.seeds",
    "hash_id"    => "5AB6056D647A152AA5CCD96A4D3169B7",
    "user_guid"  => 26600,
    "date"       => "20200711",
    "traits"     => "sg",  //STRENGTH AND GROWTH
    "frequency"  => "2d",
    "seed_types" => "course, book, film",
    "group_by"   => "trait",
    "language"   => "en"
);

$json_string = eggup_send_api_call($keys, $url, $call, 'GET');
?>

Example response:

{
    "status": 0,
    "result": {
        "success": true,
        "seeds": [
            {
                "ref_id": "D71rF9ZkszUy-RIT-course-en-9QE02n",
                "trait_id": "RIT",
                "trait_name": "Risk Taking",
                "type": "course",
                "title": "Decision Making in a Complex and Uncertain World",
                "description": "We recommend this course as it is useful to ...",
                "url": "https://www.eggup.co/sc/RDcxckY5WmtzelV5LVJJVC1jb3Vyc2UtZW4tOVFFMDJu",
                "duration": "2100:00",
                "language": "en",
                "utc_timestamp": 1595939853
            },
            {
                "ref_id": "MpgJh9W7tahJ-RIT-book-en-4ry2o7",
                "trait_id": "RIT",
                "trait_name": "Risk Taking",
                "type": "book",
                "title": "A Spy's Guide To Taking Risks",
                "description": "How many times have you heard these words: ...",
                "url": "https://www.eggup.co/sc/TXBnSmg5Vzd0YWhKLVJJVC1ib29rLWVuLTRyeTJvNw==",
                "author": "John Braddock",
                "year": "2019",
                "language": "en",
                "utc_timestamp": 1595939853
            },
            {
                "ref_id": "7x3jTg8VCehn-RIT-film-en-kBWPno",
                "trait_id": "RIT",
                "trait_name": "Risk Taking",
                "type": "film",
                "title": "Money Heist",
                "description": "Each person's personality is made up of ...",
                "url": "https://www.eggup.co/sc/N3gzalRnOFZDZWhuLVJJVC1maWxtLWVuLWtCV1Bubw==",
                "duration": "50:00",
                "language": "en",
                "utc_timestamp": 1595939853
            },
            {
                "ref_id": "RdNDCX9YS2cW-SCL-course-en-1olE3v",
                "trait_id": "SCL",
                "trait_name": "Social / Emotional Intelligence",
                "type": "course",
                "title": "Influencing People",
                "description": "We recommend this course as it is useful for enhancing ...",
                "url": "https://www.eggup.co/sc/UmRORENYOVlTMmNXLVNDTC1jb3Vyc2UtZW4tMW9sRTN2",
                "duration": "780:00",
                "language": "en",
                "utc_timestamp": 1596112653
            },
            {
                "ref_id": "a3Vgh2JEtxUx-SCL-book-en-xaDNOR",
                "trait_id": "SCL",
                "trait_name": "Social / Emotional Intelligence",
                "type": "book",
                "title": "Emotional Intelligence Mastery: A Practical Guide To Improving Your EQ",
                "description": "How many times have you heard these words: ...",
                "url": "https://www.eggup.co/sc/YTNWZ2gySkV0eFV4LVNDTC1ib29rLWVuLXhhRE5PUg==",
                "author": "Eric Jordan",
                "year": "2016",
                "language": "en",
                "utc_timestamp": 1596112653
            },
            {
                "ref_id": "Yx49CJeniRTE-SCL-film-en-B53xnO",
                "trait_id": "SCL",
                "trait_name": "Social / Emotional Intelligence",
                "type": "film",
                "title": "Wonder",
                "description": "Each person's personality is made up of a set of traits ...",
                "url": "https://www.eggup.co/sc/WXg0OUNKZW5pUlRFLVNDTC1maWxtLWVuLUI1M3huTw==",
                "duration": "113:00",
                "language": "en",
                "utc_timestamp": 1596112653
            }
        ]
    }
}

This method gets a self-development path, after a custom test completition, using learning-seeds of different types. Input parameters may specify the focus of the path in terms of base traits, as well as the order and content usage frequency for the delivery to the final user.

Param Description
hash_id String - required
The hash-ID of the custom test of which you want to ask the learning-path.
user_guid Integer - required
The user-ID of the person who completed the custom test.
date Integer - (optional)
The date of the test completion to be used to build the report, if not specified will be used the last one. (format "yyyymmdd", as received in [scores] array, e.g. "20200611").
traits String - (optional)
The list of traits-ID to be included in this path, as comma separated values.
Special strings can be used for strength/strength, strength/growth, growth/growth or all test's traits ("ss", "sg", "gg", "all") paths.
Default: sg.
frequency String - (optional)
The frequency to be used to generate the utc_timestamp inside output array, as activation time for each learning-seed inside the path. Available chars: "m", "h", "d", "w".
Default: 2d.
seed_types String - (optional)
This param defines which seed types and the order to be used in the learning path. Available types are: "course", "book", "film", "song", "podcast", "tedtalks", "vip".
Default: course,book,film,song,podcast,tedtalks,vip.
group_by String - (optional)
How the path should be built, by grouping learning-seeds by "type", "trait" or "shuffle". Optional number can be added (e.g. "type:3"), to define how many learning-seeds should be included in a group, with same utc_timestamp.
Default: trait.
language String - (optional)
It forces the response to be in the chosen language instead of company account default (en, it).

The result array include:

Name Description
ref_id String
Unique ID that identify this seed for this user and test.
trait_id String
The trait ID which the seed is referred to.
trait_name String
The trait name in chosen language.
type String
The type of the learning-seed. ("course", "book", "film", "song", "podcast", "tedtalks", "vip")
title String
The title of the learning-seed element.
description String
Content text description of the learning-seed.
url String
The remote URL of the resource associated to the learning-seed.
duration String
The duration of the content, if applicable.
author String
The author name of this learning-seed.
year String
The publication year of the content.
tags String
List of text tags about this learning-seed.
language String
The language of the learning-seed's content.
utc_timestamp Integer
The timestamp to be used as activation time. UTC time zone.

See the example for a detailed view of the response data structure of [seeds] array.

PHP