API Documentation v1.0

You can reach the API v2.2 documentation at: https://docs.eggup.co/.

API Reference

API v1.0 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:

{
    "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:

{
    "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:

status: the status code, 0 for success or a non-zero error code.
message: if the status code is non-zero this contains a human readable explanation.
result: the mixed result of the execution, an array of elements or even an object, depending on the API method being called.
runtime_errors: if there have been any runtime errors picked up by the internal error handler during the execution of the command, these are given here in an array.

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($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:

The public API key identifying you to the Eggup API server.
The private API Key that is companion to the public key.
The current unix time in seconds.
A nonce to guarantee two requests the same second have different signatures.
URL encoded string representation of any GET variable parameters - eg method=user.post&foo=bar.
If you are sending post data, the hash of this 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:

<?php
$url = "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.
test.reset	POST	Reset answers and scores for a given userID.
report	POST	Get the PDF report for a given userID and testID.

Remember that the argument language is available for each method to force the language of the output response.

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

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 should 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 8 characters.
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 company account default (en, it, hr).

To avoid receiving an error due to an existing username, it is recommended to use a prefix.

It is important to use a full name associated with the user account as it will be used as a title in the PDF.

The username cannot be changed after the user account creation.

The user_guid is always mandatory, set to 0 on new user creation.

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,
    "language" => "en"
);

$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:

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

Param	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 company account default (en, it, hr).

If the user has complete a test, the [scores] array will be included under the [user] array.

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,
    "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 over API, the following table explains the required and optional arguments.

Param	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 company account default (en, it, hr).

Remember that there's no undo for user.delete, all the associated data will be lost.

Test methods

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

This process can be completed in two ways:

by asking and sending a list of all the questions for a specific testID, with test.get and test.post methods;
proceeding question by question with the functions test.question and test.answer.

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",
    "language" => "en"
);

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

Example response:

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

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.eggup.co/json";

$call = array(
    "method" => "test.get",
    "test_id" => "big5_20",
    "language" => "en"
);

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

Example response:

{
    "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. Each element contains a key question with the text of the question and [answers] as array of available answers.

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

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),
    "language" => "en"
);

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

Example response:

{
    "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. It returns a [scores] array containing the results for this testID, ordered high to low.

Param	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 company account default (en, it, hr).

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,
    "language" => "en"
);

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

Example response:

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

Param	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 company account 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,
    "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 testID and userID.

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

test.reset

POST

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

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

$call = array(
    "method" => "test.reset",
    "user_guid" => 26660,
    "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 answers and scores for a given user ID.

Param	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 company account default (en, it, hr).

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",
    "language" => "en"
);

$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:

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

Param	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 company account default (en, it, hr).

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