NOTE: In this page and all subsequent Elance Developer API documentation, the term "provider" refers to an Elance contractor.

I. Technical Overview

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

The API consists of several sets of methods for retrieving information stored by Elance:

Profile Methods
Search Methods
Group Methods
Manage Methods
Workroom Methods

The objects that can be accessed using these API methods (such as provider, jobs, and bids) are described in Data and Method Overview.

All methods require the use of 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.

II. Request Endpoint

The base URL for all Elance API requests is one of the following, depending upon whether the individual method requires HTTP or HTTPS. Both entry points use the default HTTP and HTTPS ports of 80 and 443, respectively.

http://api.elance.com/api
https://api.elance.com/api

III. Structure of an API Call

All Elance API method calls conform to the following structure:

<endpoint>/<method-group>/<method-name>?<query-string>

 URL Part  Description
endpoint The URL of the Elance Developer API service.
method-group The group to which the method belongs.
method-name The name of the method, which is unique to a method group.
query-string The query string parameters supplied to the command.

IV. Required Query String Parameters

Most API calls are HTTP GET requests in which all of the information required from the client application is sent in the form of HTTP query string parameters. Every public API call requires the following parameters:

Parameter Description
oauth_consumer_key An API key issued by Elance. API keys are UUIDs, as specified by RFC4122, and are included in query strings without hyphens separating the groups. If a client application submits a request with an invalid or missing key, the API returns an HTTP 401 (Unauthorized) status response.

Most individual API methods have additional required parameters. See the documentation on individual methods for more details.

V. Additional Query String Parameters

 All API calls take the following optional query string parameters. If these parameters are not included, the API will use the specified default value.

Parameter Description
v Which version of the API to execute. Defaults to 1. Currently, 1 is the only allowable value.
fmt The format of the HTTP response body. fmt dictates both the return format of success and error responses. Currently, this defaults to json for all API methods. JSON is the only response format fully supported at this time.
debug Causes the API to generate additional debugging information, which is embedded inside the response body. See below for more information on the format of debugging output.
jsonp Indicates that the JSON output is to be formatted as a Javascript callback function, which allows HTML clients to load Elance data directly from a Web page. The value of this parameter is a string specifying the name of the callback. Only valid for methods that return a value of Yes for JSONPAvailable in a debug response. For more information and an example of JSONP in action, see Using Jason with Padding (JSONP).

VI. Response Success Format

1. General Format of a JSON Response

When an Elance Developer API call succeeds, it returns an HTTP 200 status code with the Content-Type response header set by default to application/json.  The HTTP body of the response contains the response object, formatted by default in JSON syntax.

The basic structure of a JSON response is as follows:

{   
     "api": "search\/providers",  
     "apiVersion": 1,   
	 "rcode": 1,   
	 "data": {     
		// The data returned by the response.
	} 
}

The response consists of the following properties and objects:

Property Name Description
api The API method that was called, formatted as <method-group>/<method-name>.
apiVersion The version of the Elance Developer API that was invoked for this method call.
rcode Whether the request succeeded. This is set to 1 for success responses.
data A container for the data objects and properties returned by the method. If the response contains one or more arrays of objects, they are represented as JSON arrays indexed by number, beginning from 0.

2. Response Property Data Types

Response properties are always one of the following data types.

Data Type Description
integer A positive or negative whole number.
string Unicode text.
URL A string that conforms to RFC 1738.
date A combination of day, month and year, expressed in the format DD-MON-YY<code>, where <code>MON is the three-letter representation of the month.
timestamp A date expressed as seconds elapsed since January 1st, 1970.
array A numbered list of objects or properties. 

VII. Response Error Format

Sometimes, the Elance Developer API will be unable to fulfill a request, and will return an error. If the error resulted from an incorrect API key, the API will return an HTTP 401 (Unauthorized) status error. If the error resulted from some other cause, the API will return an HTTP 400 (Bad Request) status error. The body of the HTTP request will contain an error code object formatted according to the value of the fmt query string parameter.

Attempting to invoke a method that is not defined by the Elance Developer API results in an HTTP 404 error with no response body.

1. Format of a JSON Error Response

Below is an example of a JSON error object returned when the profile/getProviderProfile method is called without a userId or userName parameter.

{
	"api":"profile\/getProviderProfile",
	"apiVersion":1,
	"rcode":0,
	"errors":[
		{
			"type":"validation",
			"code":"E_API_VALIDATION_PARAM_REQUIRED",
			"description":"This parameter is required.",
			"param":"userId or userName"
		}
	]
}

An error response contains the following properties and objects.

Property Name Description
api The API method call that failed, formatted as <method-group>/<method-name>.
rcode Whether the request succeeded. This is set to 0 for error responses.
errors An array of Error objects, as defined below.

Error Object

Property Name Description
type The category to which this error belongs.
code A text string that uniquely identifies the error that occurred. For a list and definition of error codes that can be thrown by any API, see Common API Error Codes. Additional method-specific errors are documented as part of the method.
description A human-readable explanation of why the error occurred.
param A descriptive string of the parameter or parameters that caused the error to occur.  

VIII. Debug Output Response Format

1. Format of a JSON Debug Response

When the debug parameter is included in a request, the request is transformed in two ways. First, the response code (e.g., JSON) is returned with line breaks and indents to make it human-readable. Second, a debug object is added at the same level as the data object that provides additional information about the request, including a full description of the method call, and a list of all parameter values received by the method call.

Below is an example of a JSON debug object returned when the profile/getProviderProfile method is called with the debug parameter set to true.

{
  "api": "profile\/getProviderProfile",
  "apiVersion": 1,
  "rcode": 1,
  "data": {
	// Record omitted
  },
  "debug": {
    "serverTimestamp": 1281831737,
    "apiInfo": {
      "httpMethod": "GET",
      "httpProtocol": "HTTP",
      "authorizationRequired": "No",
      "signatureRequired": "No",
      "defaultVersion": 1,
      "currentVersion": 1,
      "defaultResponseFormat": "json",
      "JSONPAvailable": "Yes",
      "params": [
        "userId",
        "userName",
        "catId"
      ],
      "requiredParams": null
    },
    "requestParams": {
      "catId": "10184",
      "userId": "1308301",
      "oauth_consumer_key": "xxxxxxxxxxxxxxx",
      "debug": "true"
    }
  }
}

A debug object consists of the following properties and objects.

Property Name Description
serverTimestamp The time at which this method was executed on the server, expressed in seconds since January 1st, 1970.
apiInfo An ApiInfo object, as described below.
requestParams An object whose property names correspond to the parameters supplied to the method call. The values of these properties are the values that were supplied by the client application. This can be used to verify that the request parameters are being understood properly by the server.
A. ApiInfo Object
Property Name Description
httpMethod The HTTP protocol method (GET, POST, HEAD) that is used to execute this API call.
httpProtocol Whether this method can be called using HTTP, or must be called using HTTPS. If HTTP is returned, the method can be called over either protocol.
authorizationRequired Whether the method requires the use of OAuth. Valid values are Yes and No.
signatureRequired Whether the method requires an OAuth signature with every method call. Valid values are Yes and No.
defaultVersion The version of this method that is called if the v parameter is not specified.
currentVersion The latest available version of the method.
deprecatedVersion The last version of this API that is no longer supported.
defaultResponseFormat The format of the HTTP body response if the fmt parameter is not specified.
hasHTMLResponseFormat Whether this method accepts a fmt value of html, and can return tabular data formatted as HTML code.
JSONPAvailable Whether this method can use JSON with Padding (JSONP) to return a Javascript function callback as its JSON output. The name of the function is specified using the jsonp input parameter. Values for this response property are Yes and No.
params An array containing the named parameters accepted by this method call.
requiredParams The parameters that must be supplied for this method to execute successfully. This is null if either the method has no required parameters, or if more than one parameter may fulfill a method's requirements. In the above example, either userId or userName is acceptable for identifying a provider, so the value of the requiredParams property is null.

IX. Utility Methods

1. service/getStatus

The service/getStatus method is a utility method that reports on whether the Elance API is currently available for use.

A. Required Query String Parameters

None, except for oauth_consumer_key.

B. Optional Query String Parameters
Parameter Description
format The encoding of the response. Valid values for this method are json and html.
C. Response Data Description
Property Data Type Description
status string The current operational state of the Elance API, expressed as a fixed string. The possible return values are OK and Service Temporarily Unavailable.
message string A free-form, human readable description of the current operation state. This message is suitable for displaying to end users, and may change without notice.
serverTimestamp timestamp The time this response was returned by the server.