The Elance Developer API enables programmatic access to objects stored on Elance's servers, including user profiles, job listings, job Workrooms, messages, groups, Work View™ data, and payment information. Third party developers are encouraged to use this API to create applications that enhance and extend the Elance user experience.

The API is designed so that application developers may access the non-public data of Elance users, so long as the user grants an application permission to access her data. Elance uses the OAuth 2.0 authentication standard so that users may grant such permission to applications without supplying their Elance login information directly to third parties.

I. Technical Overview

The Elance Developer API is a REST API that accepts HTTPS requests. It currently returns data formatted in Javascript Object Notation (JSON). Other response formats may be supported in future releases.

All Elance Developer API calls require authentication using the OAuth 2.0 authentication protocol, described below. All method calls must be made over HTTPS.

All methods require an API key, which requires registering for an account with Elance. You may have multiple API keys per account, and must request a new API key whenever you develop a new application that consumes the Elance API. Note: API keys for Version 1 of the Elance Developer API will not work with Version 2. Developers who wish to access Version 2 (the API documented in these pages) must request a new API key.

Applications that consume the Elance Developer API may optionally register themselves as canvas applications, which are hosted within a frame on elance.com.

II. Structure of the API Methods

The Elance Developer API consists of a number of methods grouped into categories according to their function. For a full list of available categories and methods, see the Overview page.

The method calls that comprise the Elance Developer API are designed to enable stateless operations on server-side objects. Objects within the system, such as a job or a workroom, can be uniquely identified through URLs. For example, the format of URLs for accessing jobs using the jobs/{jobId} method is https://api.elance.com/api2/jobs/{id}, where {id}represents the unique ID assigned to the job. To reference the job with the ID 29182928, developers would use the URL https://api.elance.com/api2/jobs/29182928.

In some cases, commands can be placed after object IDs to obtain information specific to that object. The group method supports two such commands: jobs and members. For a group with an ID of 10298394, then, developers could obtain a list of all jobs associated with that group by using the groups/{groupId}/jobs method using the command https://api.elance.com/api2/groups/10298394/jobs. Similarly, developers could obtain a list of all of the group's members using the method with the command https://api.elance.com/api2/groups/10298394/members.

For some objects, developers can access data attached to the current user using the possessive "my". For example, the profiles/my method returns profile information for the currently authenticated user.

III. What is OAuth 2.0?

To access another user's data, an Elance Developer API client must request authorization from the user. Users determine whether to grant or deny access to your application. For application authentication, the Elance Developer API uses the OAuth 2.0 (draft 21) authentication protocol, which enables an Elance user to grant an application limited access to their account without sharing their username and password information.

While OAuth can be daunting at first, the protocol provides both developers and end users with the greatest security and ease of use. With OAuth2, third party developers never need store an Elance user's username and password information; this keeps users more secure, and limits developers' liability. OAuth2 also gives users more finely scoped control over their data, as well as the ability to revoke a third party's access to their data at any time.

The basic steps in OAuth authentication are:

  1. You (the application developer or development team) obtain a client key and a client secret from Elance.
  2. Your application contacts Elance, and requests a particular scope of access to a specific users' account.
  3. Elance displays an OAuth2 dialog to the user, asking the user to grant your application access to her data.
  4. If the user approves, Elance will provide your application with a short-lived authorization code.
  5. Your application exchanges the authorization code for an access token, which it can use to call the Elance API.

This workflow is known as an authorization code grant. It is used for web applications with servers that can securely store persistent information.

IV. Using OAuth 2.0

The authorization code grant has two parts. In the first part, your application asks the user for permission to access his data. If the user approves, Elance will send your application an authorization code. In the second part, your application will submit that code to Elance in an HTTPS POST request, along with its client secret, in order to obtain two tokens: an access token, which is valid for a specific time period, and a long-lived refresh token, which can be used to obtain a new access token after the original access token expires.

(Note: Access tokens are currently valid for 24 hours. This time period is subject to change, however, and developers should not rely upon it.)

You'll need to register your application with Elance to obtain a client key (client_id) and client secret. Elance requires three pieces of information before granting API2 access:

  1. The name of your application;
  2. A short description; and
  3. The redirect_uri to use for authorization.

1. Obtaining an Authorization Code

Let's assume a user with a valid Elance account has accessed your application for the first time. Your first step is to ask the user to grant permission for your application to access her data. To do this, your application redirects the user to the URL https://api.elance.com/api2/oauth/authorize with the following query string parameters:

  • client_id (required; the unique ID assigned to your application by Elance)
  • redirect_uri (optional; if omitted, Elance will display a page to your users displaying the authorization code)
  • scope (optional; a delimited list of the type of information to which your application is requesting access. Currently, the only valid value is basicInfo)
  • response_type=code

The following query is an example of an authorization request:

https://api.elance.com/api2/oauth/authorize?client_id=4e50c14db61c419527000001&redirect_uri=https://www.example.com/back&scope=basicInfo&response_type=code

After the user approves access or chooses not to, Elance redirects to the redirect_uri, and appends one of two query string parameters: a code parameter if the user granted access, or an error parameter if the user denied access. For the example above, if a user denies access, Elance will call:

https://www.example.com/back?error=access_denied

And if the user approves access:

https://www.example.com/back?code=12312333| P7q7W91aoMsCeLvIaQm6bTrgtp6

2. Obtaining an Access Token and a Refresh Token

Your application must now swap the authorization code for an access and refresh token by issuing an HTTP POST request to the Elance OAuth2 token endpoint (https://api.elance.com/api2/oauth/token). The required POST parameters are:

  • client_id (your unique client ID as assigned by Elance)
  • client_secret (your client secret as assigned by Elance)
  • grant_type=authorization_code

An unencrypted POST request might look like this:

POST https://api.elance.com/api2/oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
 
code=12312333|P7q7W91aoMsCeLvIaQm6bTrgtp6&client_id=4e50c14db61c419527000001&client_secret=XTHhXh1SlUNgvyWGwDk1EjXB&redirect_uri=https://www.example.com/back&grant_type=authorization_code

Alternatively, your application can pass the client_id and client_secret parameters as base64-encoded name/value pairs in the HTTP Authorization header:

POST /api2/oauth/token HTTP/1.1
Authorization: Basic NGU1MmUzNGRiNjFjNDE5NTI3MDAwMDExOm11Z3JLZO
Content-Type: application/x-www-form-urlencoded
Host: eoldev2.elance.com:17002
 
code=12312333|P7q7W91aoMsCeLvIaQm6bTrgtp6&grant_type=authorization_code

Per the OAuth 2.0 standard, the client_id and client_secret parameters should never be included in an HTTP query string.

You can execute this call using the curl command line application, substituting your own access code, client key and client secret in the following:

curl -k -v -X POST https://api.elance.com/api2/oauth/token -d "code=12312333|P7q7W91aoMsCeLvIaQm6bTrgtp6&grant_type=authorization_code&client_id=4e50c14db61c419527000001&client_secret=XTHhXh1SlUNgvyWGwDk1EjXB "

The server will return a refresh token and an access token in a JSON object:

{
    "data":
    {
        "access_token":"4e50c14db61c419527000001|1231232|fFAGRNJru1FTz70BzhT3Zg",
        "expires_in":1314141390,
         "token_type":"bearer",
         "refresh_token":"1231232|QYQVvo0eC1uC2ra-huEcRtNBmOt0nY4a",
         "scope":"basicInfo"
    }
}

3. Using the Access Token to Call API Methods

You can use your access token to call a protected API by including it in an access_token query parameter or the HTTP Authorization header. For example, you can use the curl command-line application to call the Contacts API with the access token you received from the token response above:

curl https://api.elance.com/api2/someApi/full?access_token=4e50c14db61c419527000001|1231232|fFAGRNJru1FTz70BzhT3Zg

4. Refreshing the Access Token

When your access token expires, any Elance API2 method your application calls will respond with a HTTP 401 error status. At any time, you can use the token endpoint with your refresh token, client credentials, and the HTTP POST parameter grant_type=refresh_token to obtain a new access token:

POST /api2/oauth/token HTTP/1.1
Authorization: Basic NGU1MmUzNGRiNjFjNDE5NTI3MDAwMDExOm11Z3JLZO
Content-Type: application/x-www-form-urlencoded
Host: eoldev2.elance.com:17002
 
refresh_token=1231232|QYQVvo0eC1uC2ra-huEcRtNBmOt0nY4a&grant_type=refresh_token

V. Additional Supported OAuth Grant Types

While the authorization code grant is the most common type of authorization flow in OAuth 2.0, it is not the only grant flow available. The Elance Developer API also provides support for two other types of authorizations flows documented by the OAuth 2.0 standard: implicit grants and client credentials grants.

1. Implicit Grant

Implicit grants deviate from authorization code grant flow in that the client uses a response_type parameter with a value of token in the request. Instead of returning an authorization code, the server responds by embedding the access token itself as a query string parameter supplied to the redirection URI. The implicit grant type simplifies the authorization grant flow for scripting clients.

For instance, a client might request an access token using the following script:

https://api.elance.com/api2/oauth/authorize?client_id=4e50c14db61c419527000001&redirect_uri=https://www.example.com/back&scope=basicInfo&response_type=token

The server would respond by calling the URL supplied to the redirect_uri parameter with the following parameters:

https://www.example.com/back?access_token=4eb1de8bf06b10210e000005|3916669|8Hr_-TBZvHC9mfMA8OJ4cA&expires_in=1332520922&token_type=bearer

Given that this method returns the access code directly as part of the URL query string, this grant type should only be used in contexts where the client is certain it can prevent exposing the access token to other third parties (for example, via the browser's URL history).

2. Client Credentials Grant

Client credentials grants are similar to the "one-legged" authorization model of OAuth 1.0, in which a client authenticates itself directly without obtaining resource permissions from an independent user. This authorization type is useful for accessing API calls that do not require specific user permissions, such as methods for searching public jobs, accessing group data, and retrieving public profile information.

To perform client credential authentication, the client bypasses the call to the /api2/oauth/authorize method and instead calls the /api2/oauth/token method directly. The client omits the code parameter, and sets the grant_type parameter to a value of client_credentials. An example of such a call using cUrl is provided below.

curl -k -v -X POST https://api.elance.com/api2/oauth/token -d "client_id=4eb1de8bf06b10210e000005&client_secret=M5IqdtQdZN8cX741OkBniA&grant_type=client_credentials" --compressed

This grant type should only be used by what the OAuth 2.0 standard terms confidential clients, which are clients that can guarantee the absolute privacy of any credentials they use. Typically, these are clients implemented on a secure Web server. Clients installed on computer desktops or mobile devices are termed public clients, and should use the authorization code grant.

VI. JSON Response Format and Error Codes

Valid API responses are returned in the JSON format, which is documented extensively at JSON.org. JSON can be parsed in a JavaScript application using either the ECMAScript standard JSON.parse() method, or the JavaScript eval() function. Other languages such as PHP also define APIs for parsing JSON code.

A successful API response resembles the following format (this example is taken from the profiles/my/icon method):

{
   "data": {
      "thumbnailURL": "https://elance.com/media/images/4.0/no-photo-64x80.jpg"
   }
}

The data property is an object that defines the list of response properties returned by the method, along with their associated values. These properties may be scalar values, zero-based arrays, associative arrays, or objects.

An error is returned as a JSON response inside of an HTTP error response with a response code of 400 or greater. Note that a single invalid call can return an array of two or more specific error codes. The following JSON example response demonstrates the error generated when an application attempts to call the workroom/{bidId}/workview/{userId} method without a valid userId parameter. The individual response properties are described below.

{
    "errors": [{
        "type": "validation",
        "code": "E_VALIDATION_INVALID_ID",
        "description": "Input not a valid ID."
    }, {
        "type": "validation",
        "code": "E_API_NOT_AUTHORIZED",
        "description": "You are not authorized to access this data."
    }]
}

Property Name Data Type Description
errors Array of ErrorData objects The list of errors returned by the API.
type string The category of error to which the error code belongs. Error code categories are defined on the Common API Error Codes page.
code string A unique, fixed label assigned to the type of error. Some common error codes are defined on the Common API Error Codes page.
description string A brief sentence describing the nature of the error that may be shown to the user. The values of these descriptions are not fixed, and are subject to change without notice. Developers who need to craft a more detailed error message should detect the type of error by examining the value of the code property.

 

If a valid API method is called using the HTTP method instead of HTTPS, Elance.com will respond with a 301 Moved Permanently HTTP response containing a secure (HTTPS) link to the method. Calling an API method that is not defined by Elance.com will result in a standard 404 File Not Found HTTP response. The server may also return a 503 Server Unavailable response in those rare cases where the Elance.com server is overwhelmed by requests, or has been taken down for regular maintenance.

Specific methods in the Elance Developer API can return error codes specific to those methods; these are documented in the individual documentation pages for each method. A list of general errors that can be returned by multiple APIs is given on the Common API Error Codes page.

VII. Platform Applications

While you can still host your Elance API application directly on your own Web site, you can also opt to create a Platform Application that runs within Elance.com. Building a Platform Application on Elance gives you the opportunity to deeply integrate into the core Elance.com experience, including deeper integration with the My Jobs page and Workrooms.

Platform Applications are Web applications that are loaded onto an Elance Canvas Page, an application area hosted within Elance.com. You can build your application using any language or tool chain that supports Web programming, such as PHP, Python, Java, or C#. A Canvas Page on Elance is populated by providing Elance with a URL to your application's main page. When a user requests the Canvas Page, Elance displays your application within the standard Elance user interface by loading the Canvas URL within an HTML IFRAME element.

The default Canvas Page width is 950px.

1. Obtaining the Access Token in Platform Applications

Elance will send your application a users' access token as part of its Canvas URL:

https://example.com/canvas?access_token=4e745c23b61c41001d000005|1776318|ierAeWWRY7r56T7gEzvt5w&expires_in=1316385177&refresh_token=1776318|knnReO6KiHSH2B6-4vBzwQ&token_type=bearer&signature=ba52fff7e795c2f5fc965ecd578854525364c7997a694322a58beda998dd1297

Your application can use the signature parameter to verify that the request came through Elance. signature is calculated as a hash value using the HMAC algorithm on an alphabetically sorted concatenation of all of the HTTP request's query string parameters (excluding the signature parameter). Since the algorithm uses the client secret as the key for encoding the signature, your application can safely assume that a valid signature means the request came from Elance, as you and Elance are the only two parties with access to the client secret.

Here is how a Platform Application written in PHP might verify the signature parameter:

        $tokenArr = $_REQUEST;
        $signature = $tokenArr['signature'];
        unset($tokenArr['signature']);
        ksort($tokenArr);
        $q = http_build_query($tokenArr);
        $calculatedSignature = hash_hmac('sha256', $q, $MY_CLIENT_SECRET);
        if ($calculatedSignature == $signature)
        {
            echo 'request is valid';
        }

(In the above code, the variable $MY_CLIENT_SECRET represents the client secret. For more information on HMAC signatures, consult the PHP documentation for the hash_hmac() function.)