The workroom/{bidId}/messages method requests a list of messages sent between the participants of a Workroom.

The messages requested by this method are returned in the order of most recent messages first. A default of 20 messages are returned with each request. Clients can use the refId parameter, supplying the messageId property value of the last message retrieved, to request the next set of messages. Clients can further use the rpp parameter to control the number of messages returned per request.

This method may be called using either an HTTPS GET request or an HTTPS POST request. A POST request may be used to post a new message to the specified Workroom. 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

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

tableofcontents_number_textOptional Query String Parameters

Property Name Data Type Description
refId integer The value of the messageId property (described below) of the last message retrieved. If this parameter is omitted, the 20 most recent messages are returned.
rpp integer The number of messages ("responses per page") returned with each client request.

tableofcontents_number_textResponse Data Description

Property Name Data Type Description
refId integer (JSON string) The numeric messageId associated with the last message retrieved.
numResults integer The number of messages included in the current response.
bidDetails BidData object Information on the associated Workroom identified by the bidId parameter.
messages Zero-based array of MessageData objects (described below) A list of messages posted to the Workroom.

tableofcontents_number_textBidData 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)

tableofcontents_number_textMessageData Object Description

Property Name Data Type Description
messageId integer (JSON string) The unique ID assigned to the message.
userId integer (JSON string) The unique ID, assigned by Elance, to the contractor or employer who sent this message.
userName string The login name of the contractor or employer who sent the message.
text string The body of the message.
timestamp timestamp The date and time when this attachment was uploaded to the Elance server.
attachments Array of AttachmentData objects A zero-based array containing one AttachmentData object (described below) for each file attached to the message. This property is null if the message has no attachments.

tableofcontents_number_textAttachmentData Object Description

Property Name Data Type Description
name string The original file name, minus any file path information from the uploading computer.
extension string The suffix identifying the file type.
iconURL string An image that graphically represents the type of attachment (e.g., a document icon for a document, or a camera icon for a picture).
fileURL string The download path for the full attachment.
thumbURL string A smaller version of the uploaded attachment, suitable for showing as a preview. This property is null if the attachment is not an image file.
tileURL string This property is null if the attachment is not an image file.
size string The total amount of data in the file, returned as a string such as "49 KB" or "100 MB". The format of this string is intended for display only, and may change without notice.

tableofcontents_number_textRequest/Response Examples in JSON

tableofcontents_number_textRequesting a List of Messages

The following HTTPS GET command requests the messages from the Workroom whose bidId is 27614904.

tableofcontents_number_textRequest

https://elance.com/api2/workroom/27614904/messages?rpp=1&access_token=4eb1de8bf06b10210e000005|3680366|e16Ugoi_X90MDzwLoHMVrQ

tableofcontents_number_textResponse

{
    "api": "workroom\/30561769\/messages",
    "rcode": 1,
    "data": {
        "refId": null,
        "numResults": 1,
        "messages": {
            "0": {
                "messageId": "94353925",
                "userId": "4124673",
                "userName": "Marshall E.",
                "displayName": "Marshall E.",
                "text": "Making initial contact. Let me know if you need anything to make this project a success!\n\n-M.",
                "timestamp": 1337666040,
                "attachments": null
            }
        },
        "bidDetails": {
            "bidId": "30561769",
            "jobId": "30561768",
            "jobName": "PHP Development Required ASAP",
            "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,
            "phase": "5",
            "status": "Working",
            "secondaryStatus": "",
            "isHourly": false,
            "isSponsored": false,
            "isDelisted": false,
            "isPreBid": false,
            "isAwarded": true,
            "isCompleted": true,
            "bidAmount": "2191.78",
            "hourlyRate": "0",
            "hoursPerWeek": "0",
            "duration": "",
            "submissionDate": 1337659200,
            "awardedDate": 1337659200,
            "contractEndDate": "Jul 22, 2012",
            "milestonesCount": 1,
            "milestonesCompleted": 0,
            "deliveryCodeId": "13012"
        }
    }
}

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