NAV Navbar
php
  • API Reference
  • Response formats
  • Server replies
  • Authentication
  • Exposed methods
  • User methods
  • Test methods
  • Report methods
  • API Reference

    API Endpoint:

    
    https://api.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.

    Response formats

    Example request URL for JSON:

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

    Example request URL for XML:

    
    https://api.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.

    Server replies

    Example response in JSON format for method user.get:

    JSON: {
        "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.post:

    JSON: {
        "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).

    Authentication

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

    HMAC Authentication

    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(map_api_hash($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(map_api_hash($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[] = self::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 argument method to specify the function you are going to call:

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

    Eggup API provides a set of low level methods to complete a end-to-end process for soft skills analysis, from user account registration to the analysis PDF report generation.

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

    Method Mode Description
    user.post POST Register a user account.
    user.get GET Retrive a user account and the associated data and scores.
    user.delete POST Delete a user account.
    test.list GET Get the list of the available test with their IDs.
    test.get GET Get an array of elements containing all the questions for a given testID.
    test.post POST Send a set of answers for a given testID and userID.
    test.question GET Get the last question to be answered for a given userID and testID.
    test.answer POST Send the answer for a given question, testID and userID.
    report POST Get the PDF report for a given userID and testID.

    User methods

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

    user.post (POST)

    The above example shows how to implement the user.post 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" => "user.post",
        "name" => "API user",
        "email" => "apiuser@eggup.co",
        "username" => "apiuser",
        "password" => "apipassword",
        "user_guid" => 0,
        "metadata" => array(
            "metadata1" => "1",
            "key" => "meta2"),
    );
    
    $json_string = eggup_send_api_call($keys, $url, $call, 'POST');
    
    ?>
    
    

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

    Example response:

    JSON: {
        "status": 0,
        "result": {
            "success": true,
            "id": 26600
        }
    }
    

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

    The userID user_guid is optional, but required to update an existing user account.

    Argument Type Mode 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.
    password String (required) The password of the new account.
    user_guid Integer (required) The userID of the account, used to update a user account. (0 for new account)
    metadata Array (optional) Optional metadata to be associated with the user account.
    language String (optional) It forces the response to be in the chosen language instead of the user default. (en, it, hr)

    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.eggup.co/json;
    
    $call = array(
        "method" => "user.get",
        "user_guid" => 26600,
    );
    
    $json_string = eggup_send_api_call($keys, $url, $call, 'GET');
    
    ?>
    
    

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

    Example response:

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

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

    Argument Type Mode Description
    user_guid Integer (required) The userID of the account.
    language String (optional) It forces the response to be in the chosen language instead of the user 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.eggup.co/json;
    
    $call = array(
        "method" => "user.delete",
        "user_guid" => 26600,
    );
    
    $json_string = eggup_send_api_call($keys, $url, $call, 'POST');
    
    ?>
    
    

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

    Example response:

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

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

    Argument Type Mode Description
    user_guid Integer (required) The userID of the account to be deleted.
    language String (optional) It forces the response to be in the chosen language instead of the user default. (en, it, hr)

    Test methods

    The methods below are used for the completion of a test by the user.

    This process can be completed in two ways:

    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.eggup.co/json;
    
    $call = array(
        "method" => "test.list",
    );
    
    $json_string = eggup_send_api_call($keys, $url, $call, 'GET');
    
    ?>
    

    Example response:

    JSON: {
        "status": 0,
        "result": {
            "success": true,
            "test": [
                {
                    "test_id": "big5_20",
                    "description": "Big5 20 items (estimated time 3 min)."
                },
                {
                    "test_id": "big5_50",
                    "description": "Big5 50 items (estimated time 8 min)."
                },
                {
                    "test_id": "big5_100",
                    "description": "Big5 100 items (estimated time 15 min)."
                }
            ]
        }
    }
    
    

    This function return the list of all available test IDs.

    Argument Type Mode 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.eggup.co/json;
    
    $call = array(
        "method" => "test.get",
        "test_id" => "big5_20",
    );
    
    $json_string = eggup_send_api_call($keys, $url, $call, 'GET');
    
    ?>
    

    Example response:

    JSON: {
        "status": 0,
        "result": {
            "success": true,
            "list": {
                "1": {
                    "question": "I'm the life of the party.",
                    "answers": [
                        1,
                        2,
                        3,
                        4,
                        5
                    ]
                },
                "2": {
                    "question": "I sympathize with others' feelings.",
                    "answers": [
                        1,
                        2,
                        3,
                        4,
                        5
                    ]
                }
    
                ...
                ...
    
            }
        }
    }
    
    

    This method return the [list] of all the questions for a single test, for each question the array of eligible answers is specified.

    Argument Type Mode Description
    test_id String (required) The ID of the test to be requested.
    language String (optional) It forces the response to be in the chosen language instead of company account default. (en, it, hr)

    It returns a [list] array containing all the elements, each element contains a key question 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.post (POST)

    <?php
    
    $keys = array(
        "public" => "yourPublicKey",
        "private" => "yourPrivateKey");
    
    $url = https://api.eggup.co/json;
    
    $call = array(
        "method" => "test.post",
        "test_id" => "big5_20",
        "user_guid" => 26600,
        "answers" => array(2,5,3,4,1,2,4,2,4,2,3,1,5,1,3,2,5,1,2,5),
    );
    
    $json_string = eggup_send_api_call($keys, $url, $call, 'POST');
    
    ?>
    

    Example response:

    JSON: {
        "status": 0,
        "result": {
            "scores": {
                "big5_20": {
                    "traits": {
                        "es": {
                            "name": "Emotional Stability",
                            "value": 64,
                            "scale": 100
                        },
                        "e": {
                            "name": "Energy",
                            "value": 64,
                            "scale": 100
                        },
                        "c": {
                            "name": "Conscientiousness",
                            "value": 62,
                            "scale": 100
                        },
                        "a": {
                            "name": "Agreeableness",
                            "value": 60,
                            "scale": 100
                        },
                        "o": {
                            "name": "Openness to experience",
                            "value": 56,
                            "scale": 100
                        }
                    },
                    "roles": {
                        "realizer": {
                            "name": "Achiever",
                            "value": 4,
                            "scale": 5,
                            "description": "This is a person who ..."
                        },
                        "coworker": {
                            "name": "Coworker",
                            "value": 3,
                            "scale": 5,
                            "description": "This is a person who ..."
                        }
                    }
                }
            },
            "success": true
        }
    }
    

    This method is used to post the list of all the answers for a single testID and userID.

    Argument Type Mode Description
    test_id String (required) The ID of the test to be requested.
    user_guid Integer (required) The userID of the account.
    answers Array (required) The array containing the list of all the answers for the test.
    language String (optional) It forces the response to be in the chosen language instead of the user default. (en, it, hr)

    It returns a [scores] array containing the results for this testID, ordered high to low.

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

    test.question (GET)

    <?php
    
    $keys = array(
        "public" => "yourPublicKey",
        "private" => "yourPrivateKey");
    
    $url = https://api.eggup.co/json;
    
    $call = array(
        "method" => "test.question",
        "test_id" => "big5_20",
        "user_guid" => 26600,
    );
    
    $json_string = eggup_send_api_call($keys, $url, $call, 'GET');
    
    ?>
    

    Example response:

    JSON: {
        "status": 0,
        "result": {
            "success": true,
            "question": {
                "number": 1,
                "scale": 20,
                "text": "I'm the life of the party.",
                "answers": [
                    1,
                    2,
                    3,
                    4,
                    5
                ]
            }
        }
    }
    

    This method return the last question for a given userID and testID.

    Argument Type Mode Description
    test_id String (required) The ID of the test to be requested.
    user_guid Integer (required) The userID of the account.
    language String (optional) It forces the response to be in the chosen language instead of the user default. (en, it, hr)

    It returns a [question] array containing the current number of the question and the test scale, 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)

    <?php
    
    $keys = array(
        "public" => "yourPublicKey",
        "private" => "yourPrivateKey");
    
    $url = https://api.eggup.co/json;
    
    $call = array(
        "method" => "test.answer",
        "test_id" => "big5_20",
        "user_guid" => 26660,
        "question" => 1,
        "answer" => 3,
    );
    
    $json_string = eggup_send_api_call($keys, $url, $call, 'POST');
    
    ?>
    

    Example response:

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

    This method is used to send an answer of a single question for a specific testID and userID.

    Argument Type Mode Description
    test_id String (required) The ID of the test to be requested.
    user_guid Integer (required) The userID of the account.
    question Integer (required) The progressive number of the question for the current test.
    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 the user 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.

    Report methods

    report (POST)

    <?php
    
    $keys = array(
        "public" => "yourPublicKey",
        "private" => "yourPrivateKey");
    
    $url = https://api.eggup.co/json;
    
    $call = array(
        "method" => "report",
        "test_id" => "big5_20",
        "user_guid" => 26600,
        "company_name" => "Your company name",
        "color_hex" => "#403d3d",
    );
    
    $logo = file_get_contents($filename);
    
    $json_string = eggup_send_api_call($keys, $url, $call, 'POST', $logo);
    
    ?>
    

    Remember to add the fifth argument to send the image logo as POST data with eggup_send_api_call().

    Example response:

    JSON: {
        "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 testID and userID.

    In addition to the arguments, it is necessary to send as postdata the logo image to be included in the report, see the eggup_send_api_call() as good reference about how to send post data with http header over HMAC.

    Argument Type Mode Description
    test_id String (required) The ID of the test to be requested.
    user_guid Integer (required) The userID of the account.
    company_name String (required) The company name.
    color_hex String (required) The color code in hexadecimal format - eg. #FF7800.
    language String (optional) It forces the response to be in the chosen language instead of the user default. (en, it, hr)

    The result array include:

    Name Type 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, usually application/pdf .
    pdf_base64 String The PDF file encoded in base64.
    php