The contractors method searches the Elance database of service providers. It obsoletes the search/providers method in Version 1 of the Elance Developer API.

Keyword searches are performed against all text fields of an Elance provider record. Only records that contain all of the specified keywords will be returned.

The response for each provider includes their basic personal information, their rate, and their earnings and ratings within their category of service. If a provider belongs to more than one category, the method will return one provider object per category. For example, if a provider named ProviderUno belongs to both the "Web & Programming" category and the "Design & Multimedia" category, the contractors method will return two records for ProviderUno. Each record will have different values of the category property, and different roll-up information for properties such as earnings6Months, feedback6Months, and elanceLevel.

Results are returned in fixed pages of 25 records each. By default, the first page of results is returned with an initial request; additional pages are requested by issuing subsequent requests on the same search with the page query string parameter. Results must be presented to end users in the same order as returned by the Search methods. Re-ordering the results is considered a violation of the Elance Developer API Terms of Service.

This method must be called using an HTTPS GET request. All responses are returned in the JSON format.

tableofcontents_number_textPreconditions

This method requires that the calling application has authenticated a user with the OAuth 2.0 protocol, as described on the Getting Started page.

tableofcontents_number_textRequired URL Parameters

There are no required URL parameters for this method.

tableofcontents_number_textOptional Query String Parameters

Parameter Description
keywords A space-delimited list of keywords to search. If omitted, this method returns a list of all active providers.
sortCol

The property by which to sort results. Valid values are:

earnings
feedback
level

The default is level.

sortOrder Sort the results in ascending or descending order. If this parameter is specified without the sortCol parameter, it is ignored. Valid values are:

asc
desc

The default is desc.

page The requested page of result sets, in sort order, numbered beginning from 1. Default is 1. If this number exceeds the value of the totalPages response property, the response contains zero results.
catFilter A positive integer representing a category ID that restricts search results to providers who belong to the specified category. A list of valid category IDs and associated names is available through the categories method. If this does not correspond to an existing category ID, the method returns an empty result set.
subcatFilter A positive integer representing a subcategory ID that restricts search results to providers who belong to the specified subcategory. A list of valid subcategory IDs and associated names is available through the categories method. If this value does not correspond to an existing category ID, the method returns an empty result set.

tableofcontents_number_textResponse Data Description

Property Name Data Type Description
totalResults integer The number of AgentInformation objects available for this Workroom, across all pages.
totalPages integer The total number of pages of data available.
page integer The page number for this request.
numResults integer The total number of AgentInformation objects returned in this request.
pageResults Array of ContractorData objects
facets FacetsData object A summary of the characteristics of all of the contractors returned by the search query.

tableofcontents_number_textContractorData Object Description

Property Name Data Type Description
userId integer The unique ID, assigned by Elance, that designates the user to whom this profile belongs.
userName string The unique text string, chosen by the user, that the employer or contractor uses to log in to Elance.
businessName string The name of the contractor's company, if applicable.
tagLine string A brief description of the contractor's services, supplied by the contractor.
overview string The contractor's description of her expertise and services.
hourlyRate decimal The average price the contractor charges per hour for hourly jobs.
isIndividual boolean True if this contractor is a personal contractor with no business or corporate identity; otherwise, false.
isWatched boolean True if the contractor is one the currently logged in user's Watch list; otherwise, false.
skills SkillsData object A zero-based array describing the contractor's technical and professional proficiencies.
city string The city in which the contractor resides.
state string The state or province in which the contractor resides.
country string The country in which the contractor resides.
countryCode string The alpha-2 country code for the contractor's country of residence, as specified by ISO 3166-1.
profileType ProfileTypeData object Designates whether this is an individual or business account. Includes identifying information for the particular entity, such as a personal photo or company logo.
skillsCount integer The number of competencies and specialties the contractor or business possesses. Corresponds to the number of entries returned in the skills property.
portfolioCount integer The number of documents, code projects, or other work products uploaded by the contractor to showcase his or her work. Corresponds to the number of objects returned in the portfolio property.
privateEarnings boolean True if the total amount earned on Elance by this contractor is kept hidden; otherwise, false.
earnings6Months integer (JSON string) The total amount, in US dollars, that the contractor has received in payment during the past six months.
feedback6Months integer (JSON string) The number of ratings left for this contractor over the past six months.
posFeedback6Months integer (JSON string) The number of positive ratings received by this contractor over the past six months.
avgFeedbackScore6Months integer (JSON string) The average employer rating of this contractor over the past six months.
earnings12Months integer (JSON string) The total amount, in US dollars, that the contractor has received in payment during the past 12 months.
feedback12Months integer (JSON string) The number of ratings left for this contractor over the past 12 months.
jobs12Months integer (JSON string) The number of bids this contractor has been awarded in the past 12 months.
posFeedback12Months integer (JSON string) The number of positive ratings received by this contractor over the past 12 months.
avgFeedbackScore12Months integer (JSON string) The average employer rating of this contractor over the past 12 months.
elanceLevel integer (JSON string) The contractor's level rating on Elance.
category string The primary category of service to which the contractor belongs.
category_id integer The unique ID, assigned by Elance, of the primary category of service to which the contractor belongs.
logo string The URL to the contractor's business image or personal picture.
providerProfileURL string The full URL to the contractor's profile on Elance.
providerJobHistoryURL string The full URL to the contractor's list of in-progress and completed jobs on Elance.

tableofcontents_number_textSkillsData Object Description

Property Name Data Type Description
skillId integer The unique ID, assigned by Elance, that identifies a standard skill. If the value of the proficiencyType property is SELF-RATED, this property will be null.
name string The human-readable label that identifies the skill.
proficiencyType string Specifies how the contractor's skill was assessed. Valid values are SELF-RATED and TESTED.
proficiency integer (JSON string) The provider's proficiency score, on a scale from 1 to 10.
testAverage integer (JSON string) The average score for this test obtained across all test takers. If the value of the proficiencyType property is SELF-RATED, this property will be null.
testPercentile integer (JSON string) The provider's test score ranking compared to all other test takers. If the value of the proficiencyType property is SELF-RATED, this property will be null.

tableofcontents_number_textFacetsData Object Description

Property Name Data Type Description
is_agent Associative array of integer values An associative array containing two values. The true property of the array contains a count of all of the contractors returned by the query who are agents; the false property of the array contains a count of the remaining contractors who are not.
feedback Associative array of integer values An associative array where the keys are average feedback scores, and the values of the keys are the count of the contractors returned by the query who have those average scores.
reviews Associative array of integer values An associative array where the keys represent a number of reviews, and the values of the keys are the count of the contractors returned by the query who have received at least that many reviews from employers.
category Associative array of integer values An associative array where each key corresponds to the unique integer assigned to an Elance category, and the values are the count of the contractors returned by the query who belong to that category.
isIndividual Associative array of integer values An associative array containing two values. The true key indexes a count of all of the contractors returned by the query who do not belong to or own a business; the false key indexes a count of the remaining contractors who do belong to a business.

tableofcontents_number_textRequest/Response Examples in JSON

tableofcontents_number_textSearching for Contractors with "PHP" in Their Profiles

tableofcontents_number_textRequest

The following URL requests a list of all contractors who have "PHP" listed as a skill, or who mention "PHP" somewhere in their profiles.

https://elance.com/api2/contractors?keywords=php&access_token=4eb1de8bf06b10210e000005|3784257|N6ClKuHzDi9KkKm1-x1rxg

tableofcontents_number_textResponse

{
   "data": {
      "totalResults": 545848,
      "totalPages": 21834,
      "page": 1,
      "numResults": 25,
      "pageResults": {
         "0": {
            "userId": "300723",
            "userName": "synapseindia",
            "businessName": "SynapseIndia",
            "tagLine": "I.T. Outsourcing @ Peace of Mind (R)",
            "overview": null,
            "hourlyRate": 20,
            "isIndividual": false,
            "isWatched": null,
            "skills": {
               "0": {
                  "skillId": "1",
                  "name": "PHP5",
                  "proficiencyType": "SELF_ASSESSED",
                  "proficiency": "",
                  "testAverage": null,
                  "testPercentile": null
               },
               "1": {
                  "skillId": "1",
                  "name": "ASP.NET with SQL Server",
                  "proficiencyType": "SELF_ASSESSED",
                  "proficiency": "",
                  "testAverage": null,
                  "testPercentile": null
               },
               "2": {
                  "skillId": "1",
                  "name": "HTML5",
                  "proficiencyType": "SELF_ASSESSED",
                  "proficiency": "",
                  "testAverage": null,
                  "testPercentile": null
               },
               "3": {
                  "skillId": "1",
                  "name": "Microsoft SharePoint Designer 2007",
                  "proficiencyType": "SELF_ASSESSED",
                  "proficiency": "",
                  "testAverage": null,
                  "testPercentile": null
               },
               "4": {
                  "skillId": "1",
                  "name": "Facebook Open Platform Development",
                  "proficiencyType": "SELF_ASSESSED",
                  "proficiency": "",
                  "testAverage": null,
                  "testPercentile": null
               }
            },
            "city": "New Delhi",
            "state": "New Delhi",
            "country": "India",
            "countryCode": "IN",
            "profileType": null,
            "skillsCount": null,
            "portfolioCount": null,
            "privateEarnings": null,
            "earnings6Months": 931007,
            "feedback6Months": 92,
            "posFeedback6Months": 95,
            "avgFeedbackScore6Months": "4.8",
            "earnings12Months": 1774615,
            "feedback12Months": 154,
            "jobs12Months": 356,
            "posFeedback12Months": 96,
            "avgFeedbackScore12Months": "4.8",
            "elanceLevel": 18,
            "category": "IT & Programming",
            "category_id": 10183,
            "userCategories": null,
            "logo": "https://elance.com/file/thumb64-80-194783192-logo_elance_4.jpg?crypted=Y3R4JTNEc2VhcmNoX3RodW1ibmFpbCUyNmZpZCUzRDM3ODQwNzkzJTI2cmlkJTNELTElMjZwaWQlM0QzMDA3MjM=",
            "providerProfileURL": "https://elance.com/s/synapseindia/10183/",
            "providerJobHistoryURL": null
         }, [...]
         "24": {
            "userId": "2356782",
            "userName": "aexsoft",
            "businessName": "AEX Soft",
            "tagLine": "High Quality IT Services On-time and Within Budget",
            "overview": null,
            "hourlyRate": 25,
            "isIndividual": false,
            "isWatched": null,
            "skills": {
               "0": {
                  "skillId": "1",
                  "name": "ASP.Net 3.5 using C#",
                  "proficiencyType": "SELF_ASSESSED",
                  "proficiency": "",
                  "testAverage": null,
                  "testPercentile": null
               },
               "1": {
                  "skillId": "1",
                  "name": "ASP.Net 2.0 using C#",
                  "proficiencyType": "SELF_ASSESSED",
                  "proficiency": "",
                  "testAverage": null,
                  "testPercentile": null
               },
               "2": {
                  "skillId": "1",
                  "name": "ASP.NET with SQL Server",
                  "proficiencyType": "SELF_ASSESSED",
                  "proficiency": "",
                  "testAverage": null,
                  "testPercentile": null
               },
               "3": {
                  "skillId": "1",
                  "name": "C#",
                  "proficiencyType": "SELF_ASSESSED",
                  "proficiency": "",
                  "testAverage": null,
                  "testPercentile": null
               },
               "4": {
                  "skillId": "1",
                  "name": "Microsoft Silverlight",
                  "proficiencyType": "SELF_ASSESSED",
                  "proficiency": "",
                  "testAverage": null,
                  "testPercentile": null
               },
               "5": {
                  "skillId": "1",
                  "name": "DotNet 3.5 using C#",
                  "proficiencyType": "SELF_ASSESSED",
                  "proficiency": "",
                  "testAverage": null,
                  "testPercentile": null
                }
            },
            "city": "Novosibirsk",
            "state": "Novosibirsk",
            "country": "Russia",
            "countryCode": "RU",
            "profileType": null,
            "skillsCount": null,
            "portfolioCount": null,
            "privateEarnings": 1,
            "earnings6Months": 125286,
            "feedback6Months": 2,
            "posFeedback6Months": 100,
            "avgFeedbackScore6Months": "5.0",
            "earnings12Months": 226136,
            "feedback12Months": 11,
            "jobs12Months": 18,
            "posFeedback12Months": 100,
            "avgFeedbackScore12Months": "5.0",
            "elanceLevel": 13,
            "category": "IT & Programming",
            "category_id": 10183,
            "userCategories": null,
            "logo": "https://elance.com/file/for_elance.gif?crypted=Y3R4JTNEc2VhcmNoX3RodW1ibmFpbCUyNmZpZCUzRDI1MDYyMzI0JTI2cmlkJTNELTElMjZwaWQlM0QyMzU2Nzgy",
            "providerProfileURL": "https://elance.com/s/aexsoft/10183/",
            "providerJobHistoryURL": null
         }
      },
      "facets": {
         "is_agent": {
            "false": 543714,
            "true": 2134
         },
         "feedback": {
            "0": 545848,
            "2.95": 33257,
            "3.95": 32185,
            "4.95": 18868
         },
         "reviews": {
            "0": 545848,
            "5": 8627,
            "10": 4537,
            "15": 2881
         },
         "category": {
            "10183": 134590,
            "10180": 131662,
            "10179": 103699,
            "10184": 101910,
            "10178": 32819,
            "10186": 20127,
            "14000": 16463,
            "10187": 4578
         },
         "isIndividual": {
            "true": 475776,
            "false": 70072
         }
      }
   }
}

tableofcontents_number_textError Codes

For a list of error codes that can be thrown by this method, see Common API Error Codes.