The workroom/timesheets method requests a list of all timesheets that have been filed against the project by the contractor.

If a Workroom contains more than 20 timesheets, the results will be returned in pages, and obtaining the full data set will require multiple requests. Pages default to containing 20 records per page. Client applications can use the rpp query string parameter to increase or decrease the number of records per page. 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.

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

I. Preconditions

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

II. Required URL Parameters

Parameter Description
bidId The unique ID assigned by Elance to the Workroom.

III. Optional Query String Parameters

Parameter Description
page The page number of results to return, numbered beginning from 1. The default is 1. If this number is greater than the number of total pages (as expressed in the response by totalPages), the response contains zero results.
rpp The number of results requested per page. The default is 20. If more than 25 are requested, only 25 results are included in the response.

IV. Response Data Description

Property Name Data Type Description
totalResults integer The number of TimesheetData 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 TimesheetData objects returned in this request.
bidDetails BidData object Information on the associated Workroom identified by the bidId parameter.
timesheets Array of TimesheetData objects A zero-based array of objects (described below), each one containing the hours and other information associated with a timesheet filing.

1. BidData Object Data Description

Property Name Data Type Description
bidId integer The unique ID, assigned by Elance, associated with this bid. This ID is also the unique ID of the project's Workroom, which is created for each proposal as soon as a proposal is submitted.
jobId integer The unique ID of the associated job to which this Workroom is attached.
jobName string The name of the associated job, as chosen by the employer when the job was posted.
userType string Specifies the role occupied by the currently logged in user in this project.
clientUserId integer The unique integer ID assigned to the employer on Elance.
clientUserName string The unique text string chosen by the employer as her Elance login.
clientName string The individual or corporate name of the employer.
clientImageURL string The URL resource pointer to the picture representing the employer, such as a photograph or a logo.
clientCountry string The employer's country, returned as the full name of the nation.
clientCountryCode string The alpha-2 country code for the employer's country of residence, as specified by ISO 3166-1.
providerUserId integer The unique ID of the contractor, as assigned by Elance.
providerName string The legal name of the contractor.
providerCompany string The name of the contractor's business. If the contractor is a sole proprietor, this name will be equal to the value of the providerName property.
providerCompanyURL string The URL to the Web site of the contractor's business.
providerImageURL string The URL resource pointer to the picture representing the contractor, such as a photograph or a business logo.
providerProfileURL string The URL to the contractor's Elance profile.
providerJobHistoryURL string A URL linking to a page on Elance.com that displays the recent Elance jobs worked by the contractor.
providerImageURL string The URL resource pointer to the picture representing the contractor, such as a photograph or a business logo.
providerCountry string The contractor's country, returned as the full name of the nation.
providerCountryCode string The alpha-2 country code for the contractor's country of residence, as specified by ISO 3166-1.
providerCity string The contractor's city of residence.
providerState string The contractor's state or province of residence.
providerRegion string Region where the contractor resides. For example: North America or Europe.
providerHourlyRate string The average amount that the contractor charges on an hourly basis.
providerIdVerified boolean True if the contractor has verified her identity using Elance's identity verification service; otherwise, false.
providerIsBusiness boolean True if the contractor is a legal business entity; otherwise, false.
phase integer (Enumeration) A value indicating the current state of the project, such as whether it is open, in progress, or complete. See Phase Enumeration for valid values.
status string A textual representation of the current phase of the project. Used for display purposes only; the values returned for this property may change without notice.
secondaryStatus string A textual representation of the current phase of the project.
isHourly boolean True if the contractor charges the employer for every hour worked; false if the job is fixed price, and paid according to the fulfillment of milestones agreed upon by the employer and the contractor.
isSponsored boolean True if the contractor paid additional Connect points to promote this bid in the bid listings; otherwise, false.
isDelisted boolean True if this bid has been removed due to a violation of Elance policies; otherwise, false.
isPreBid boolean True if the bid represents a question from the contractor to the employer, and does not include a price quote; otherwise, false.
isAwarded boolean True if this bid was selected as the winning bid for the associated job; otherwise, false.
isCompleted boolean True if the associated project has been marked by both the employer and the contractor as finished; otherwise, false.
bidAmount decimal (JSON string) The total amount, in US dollars, that the contractor is proposing as the project cost.
hourlyRate decimal (JSON string) The amount per hour that the contractor proposes charging for this work. If the job is a fixed-price job, this property will be an empty string.
hoursPerWeek integer (JSON string) The number of hours the contractor proposes working each week until project completion.
duration integer The proposed time it will take to complete the project. This unit is either days, weeks, or months, and depends upon the desired timeframe initially selected by the employer.
submissionDate timestamp The time, expressed in seconds elapsed since January 1st, 1970, on which this proposal was submitted by the contractor to the employer.
awardedDate timestamp The time, expressed in seconds elapsed since January 1st, 1970, on which the employer selected this proposal as the winning bid.
contractEndDate string The day by which the contract should be completed. For hourly projects, this marks the final day on which billed hours will be auto-approved.
milestonesCount integer The number of status checkpoints associated with this project.
milestonesCompleted integer The number of project status checkpoints that have elapsed as of the current day.
deliveryCode integer (JSON string)

2. TimesheetData Object Description

Property Name Data Type Description
id integer The unique ID, assigned by Elance, that identifies this timesheet.
week string (Date format) A date in DD-MON-YY format that specifies the beginning of the work week to which this timesheet corresponds.
bidId integer The ID of the Workroom against which this timesheet was filed.
client string The username of the employer who created the project.
provider string The username of the contractor who filed this timesheet.
clientUserId integer The unique ID of the employer who created the project.
providerUserId integer The unique ID of the contractor who filed this timesheet.
projectStatus string The state of the project. Possible values are Ok, Problem, and Complete.
projectStatusChangedBy string A value that designates who last updated the state of the project. Possible values are PROVIDER (for the contractor) and CLIENT (for the employer).
planComment string A comment submitted by the Elance user who filed the timesheet.
startDate timestamp The date and time, measured in seconds from January 1st, 1970, on which the project began.
endDate timestamp The date and time, measured in seconds from January 1st, 1970, on which the project is projected to finish.
nextEndDate timestamp The date and time, measured in seconds from January 1st, 1970, on which the next timesheet is due.
autoPayDate timestamp The date and time, measured in seconds from January 1st, 1970, on which the timesheet will be billed automatically to the employer's preferred form of payment if it is not paid manually.
totalHours decimal The number of hours collected within this timesheet.
workedHours decimal The number of hours worked by the contractor this week.
authorizedHours decimal The number of hours for which the contractor is pre-approved to work. These hours will be auto-paid by the AutoPay date; any hours above and beyond this amount must be approved and paid manually by the employer.
billedHours decimal The total number of hours for which the contractor is invoicing the employer.
additionalHours integer The number of billed hours that are not pre-approved by the employer.
autoPayHours integer The number of hours that will be paid automatically if the timesheet is not manually approved by the employer before the date specified by the autoPayDate property.
nextAuthorizedHours integer The number of hours for which the contractor is pre-approved to work in the following week.
rate decimal The contractor's hourly pay, in US dollars.
amountBilled decimal The total amount, in US dollars, that the contractor is invoicing the client.
amountPaid decimal The total amount, in US dollars, that the employer has paid the contractor on this timesheet to date.
amountOutstanding decimal The total amount, in US dollars, that the employer still owes the contractor on this timesheet.
overdue boolean True if this timesheet was submitted after it was due; otherwise, false.
seenByClient boolean True if the employer has reviewed this timesheet; otherwise, false.

V. Request/Response Examples in JSON

1. Requesting a List of Current Timesheets

A. Request

The following URL requests a list of all current timesheets related to the project whose bidId is .

https://api.elance.com/api2/workroom/27614904/timesheets?access_token=4eb1de8bf06b10210e000005|3680366|GV4kLyVfG8SRedlk2ZvfXg

B. Response

{
    "data": {
        "totalResults": 1,
        "totalPages": 1,
        "page": 1,
        "numResults": 1,
        "bidDetails": {
            "bidId": "30561772",
            "jobId": "30561771",
            "jobName": "Hourly PHP Project",
            "startDate": 1337659200,
            "userType": "PROVIDER",
            "clientUserId": "4124673",
            "clientUserName": "m_eriksen",
            "clientName": "m_eriksen",
            "clientImageURL": "https:\/\/elance.com\/media\/images\/4.0\/no-photo-64x80.jpg",
            "clientCountry": "United States",
            "clientCountryCode": "US",
            "providerUserId": "4124672",
            "providerUserName": "t_mosby",
            "providerName": "Ted Mosby",
            "providerCompany": "Ted Mosby",
            "providerCompanyURL": "https:\/\/elance.com\/s\/t_mosby\/",
            "providerImageURL": "https:\/\/elance.com\/media\/images\/4.0\/no-photo-64x80.jpg",
            "providerProfileURL": "https:\/\/elance.com\/s\/t_mosby\/",
            "providerJobHistoryURL": "https:\/\/elance.com\/s\/t_mosby\/job-history\/",
            "providerCountry": "United States",
            "providerCountryCode": "US",
            "providerCity": "Seattle",
            "providerState": "WA",
            "providerRegion": "021",
            "providerHourlyRate": "33",
            "providerIdVerified": false,
            "providerIsBusiness": false,
            "providerJobs12M": "2",
            "phase": "5",
            "status": "Working",
            "secondaryStatus": "",
            "isHourly": true,
            "isSponsored": false,
            "isDelisted": false,
            "isPreBid": false,
            "isAwarded": true,
            "isCompleted": true,
            "bidAmount": "1972.8",
            "hourlyRate": "49.32",
            "hoursPerWeek": "10",
            "duration": 4,
            "submissionDate": 1337659200,
            "awardedDate": 1337659200
        },
        "timesheets": {
            "0": {
                "id": 1730856,
                "week": "27-MAY-12",
                "bidId": 30561772,
                "client": "m_eriksen",
                "provider": "t_mosby",
                "clientUserId": 4124673,
                "providerUserId": 4124672,
                "projectStatus": "OK",
                "projectStatusChangedBy": "PROVIDER",
                "planComment": "",
                "startDate": 1337572800,
                "endDate": 1338091200,
                "nextEndDate": 1338696000,
                "autoPayDate": 1338609600,
                "totalHours": 0.3,
                "workedHours": 0.3,
                "authorizedHours": 10,
                "billedHours": 0.3,
                "additionalHours": 0,
                "autoPayHours": 0.3,
                "nextAuthorizedHours": 10,
                "rate": 49.32,
                "amountBilled": 14.8,
                "amountPaid": 0,
                "amountOutstanding": 14.8,
                "overdue": false,
                "seenByClient": false
            }
        }
    }
}

VI. Error Codes

Error Description
E_WORKROOM_INVALID_BID Either the bidId supplied in the URL is invalid, or the currently logged in user does not have permission to access that Workroom.

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