NAV Navbar
PHP
  • API Documentation v2.2
  • API Reference
  • Response formats
  • Postman
  • Server replies
  • HMAC Authentication
  • Exposed methods
  • User methods
  • Test methods
  • Report methods
  • SmartCoach methods
  • API Documentation v2.2

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

    API Reference

    API v2.2 Production Endpoint:

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

    API v2.2 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.2",
        "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);
    }
    ?>
    

    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-none 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.

    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.
    traits.list GET Get the list of analysable personality traits.
    test.build POST Send a creation request specifying the list of traits that compose the new test.
    traits.macro 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 GET Get the list of the created custom test with their hash-ID.
    test.get 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.
    report POST Get the PDF report for a given user-ID and hash-ID.
    smartcoach.seeds GET Get a list of learning-seeds to enable a self development path.

    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).

    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

    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
                    },
                    "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
                    },
                    "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
                    },
                    "TCI": {
                        "test_id": "TCI",
                        "test_name": "Temperament and Character Inventory",
                        "trait_id": "ACH",
                        "trait_name": "Achievement Striving",
                        "description": " ... ",
                        "alpha": 78,
                        "items_count": 10
                    }
                },
                "ACS": {
                    "MPQ": {
                        "test_id": "MPQ",
                        "test_name": "Multidimensional Personality Questionnaire",
                        "trait_id": "ACS",
                        "trait_name": "Achievement Seeking",
                        "description": " ... ",
                        "alpha": 79,
                        "items_count": 10
                    }
                }
    
                ...
                ...
    
            }
        }
    }
    

    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
                    },
                    "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
                    },
    
                    ...
                    ...
    
                    "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
                    },
                    "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
                    }
                },
                "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
                    },
                    "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
                    }
    
                    ...
                    ...
    
                },
                "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
                    },
                    "CAL": {
                        "test_id": "AB5C",
                        "test_name": "45 AB5C facets",
                        "trait_id": "CAL",
                        "trait_name": "tratto ITA",
                        "description": "Descrizione ITA",
                        "alpha": 83,
                        "items_count": 10
                    }
    
                ...
                ...
    
                }
            }
        }
    }
    

    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

    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",
        "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,
                    "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
    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.

    Report methods

    report (new in v2.2)

    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",
        "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",
        "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.

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